開発の進め方
開発の依頼はinta:devで受け、要望の整理から実装、検証、依頼された成果物の確認まで進めます。工程ごとに別のSkillを探す手間を減らすため、入口をまとめています。このページでは、弊社が開発で揃える確認事項と、製品ごとの設定への反映を扱います。プラグイン全体の整理方針はプラグインにまとめています。
依頼と完了の確認事項
作業を始めるときは、目的、利用者、完了条件、許可された外向き操作を確認します。リポジトリの指示、未コミットの変更、既存のIssueとPull Request、関連する仕様と実装も読みます。これらを飛ばすと、並行作業の変更を上書きしたり、すでに決まっている方針と食い違ったりするためです。
設計は利用者に必要な振る舞いから実装へ進め、仕様とテストを同じ変更範囲で更新します。別件の修正は混ぜません。完了時には、変更に必要なformat、lint、型検査、テストの結果と、依頼された成果物を確認します。コードから読めない意思決定は.docs/へ残します。
技術構成を選ぶ
新規製品では、標準スタックを起点に次の条件で選びます。既存製品では、採用済みの構成と制約を確認し、通常の機能修正に技術の移行を混ぜません。
- 配信、サーバー処理、データベース、ファイル保存は、CloudflareのWorkers、D1、R2へ寄せる。小規模から中規模の製品で、契約先と運用アカウントをまとめるため
- 画面とAPIを別リポジトリへ分けるほどの規模でなければNext.jsを選ぶ。独立したAPIサーバーが必要な場合はHonoを使う
- 新しい画面の雛形はshadcn/uiのcreateでNext.jsとBase UIを選び、スタイルはTailwind CSSに揃える。既存製品では導入済みの部品を使い、部品の土台の移行は別の変更として扱う
- Cloudflare D1へのアクセスはDrizzle ORMを使い、型定義と実DBの一致をmigration（DB構造の変更手順）の適用と結合テストで確認する
- APIはURLとHTTPメソッドで操作を表すRESTfulな設計を標準にする。独自の規約を増やさず、レビューと引き継ぎで同じ読み方ができるようにするため
- 業務ルールが複雑になる製品ではDDD（業務上のルールを中心に設計する考え方）を採用する。単純な表示やCRUD（作成・取得・更新・削除）へ先回りして層を増やさない。分離の条件はアーキテクチャに従う
- 新規製品のlint・formatなどの開発コマンドはvp（vite-plus）へ統一する。既存リポジトリでは使用中のツールを維持する
標準から変える場合は、必要な機能、制約、運用負担を比較し、採用理由をリポジトリの仕様書へ残します。
完了の定義
コードが変わっただけでは、完了と呼びません。必要な検証と成果物が揃って、はじめて完了です。テストは実装後に別の担当へ渡す後工程ではなく、実装と同時に進む検証活動で、結果が揃うまで完了にしません（テスト戦略）。実施できなかった検証、既存の失敗、残ったリスクは、成功と区別して報告します。
外向き操作の境界
Issue起票、push、Pull Request、mergeなど、リポジトリの外の状態を変える操作は、依頼された地点までに限定します。commitやパッケージの追加は手元に閉じる操作ですが、これも依頼の範囲を超えては行いません。調査、レビュー、プレビューは読み取り専用で始めます。
一方で、mergeまで明示された依頼では、承認済みの工程ごとに再確認を挟みません。確認を返すのは、結果を変える選択が未決定の場合、権限が不足する場合、依頼の対象外へ拡張が必要になった場合だけです。確認の粒度を細かくしすぎると、人間が承認を機械的に押すだけになり、確認の意味が失われます。
ブランチとworktreeの境界
primary checkout（手元の作業コピー）のブランチは切り替えません。Issueの実装は、Issueごとのlinked worktree（1つのリポジトリから複数の作業コピーを並べて持てるGitの機能。git worktree）へ隔離し、git switchやgh pr checkoutでprimary checkout自体を別ブランチへ動かしません。この境界があると、複数の作業が同じ作業コピーを取り合って壊すことがなくなります。他の人やAIが作業中の変更は、無関係な整形、削除、巻き戻しをせず保護します。
公開範囲と接続先の設定
CLAUDE.mdに記録した前提を、GitHubの権限、環境ごとの設定、プレビューの閲覧制限へ反映します。文章の更新と設定の変更は別の操作なので、両方を確認します。
リポジトリの公開範囲
弊社では、public化の判断と実行を組織のオーナーへ限定します。GitHubの組織設定のSettings > Access > Member privilegesで、次の2つを確認します。
- Repository visibility change: 「Allow members to change repository visibilities for this organization」を外し、既存リポジトリの可視性変更をオーナーへ限定する
- Repository creation: メンバーが作成できる種類を制限する。privateだけに絞る設定はGitHub Enterprise Cloud限定のため、Freeプランの組織ではメンバーによる作成自体を止め、オーナーが作成する
可視性変更を許可している場合は、リポジトリのadmin権限を持つ人やGitHub Appも変更できます。作成の制限だけでは既存リポジトリのpublic化を防げないため、両方を確認し、AIが使うアカウントやAppにはadmin権限を付けません。設定の利用条件は可視性変更の制限と作成の制限で確認します。
秘密情報と環境変数
秘密の値を保存する.envなどのファイルは.gitignoreで除外し、Gitの管理対象と履歴に値が入っていないことを確認します。すでにcommitした値は、除外設定を足すだけでは消えません。漏れた値の扱いはトークン・APIキーに従います。
Next.jsのNEXT_PUBLIC_で始まる環境変数は、コードから参照すると配信するJavaScriptへ埋め込まれます。秘密のキーには使わず、サーバー側に限定します（Next.js: Environment Variables）。開発・テストの設定へ本番DBの接続情報や本番の決済・送信キーを置きません。
プレビューの閲覧制限
Cloudflare WorkersのPreview URLは、有効にすると公開されます。社内情報や未公開の機能を含む場合はCloudflare Accessなどで閲覧者を制限し、許可された利用者と未ログイン・許可のない利用者の両方で結果を確認します。リポジトリのprivate設定を、配信先の閲覧制限として扱いません。
記録
コードから読めない意図、顧客の声、製品判断は.docs/へ残します（仕様書を残す）。ファイルを丸ごと再生成せず、矛盾した部分だけを更新します。CHANGELOGには、利用者にとって価値のある変更だけを記録します。