Summary
この文書の要点
- セットアップ、起動、テスト、ビルドを短いコマンドで明示する。
- AI向けルールには禁止事項と確認観点を書く。
- 依存インストール、環境変数、seed、起動、検証コマンドを一つの入口にまとめる。
- AIが変更した後に、人もCIも同じコマンドで確認できるようにする。
どこが設計の難所か
AIエージェントはコードを読めますが、ローカル環境の暗黙知までは分かりません。依存インストール、環境変数、起動順序、テスト方法が曖昧だと、作業のたびに同じ失敗を繰り返します。
すべての情報を長大なドキュメントにすると読まれません。AIにも人間にも効く形にするには、作業開始時に見る短いルールと、詳細手順を分ける必要があります。
AIエージェントはコードを速く変更できますが、環境構築が曖昧だと検証が属人化します。手元では動く、別の実行者では動かないという状態では、AIによる変更の価値が下がります。
境界をどう切るか
リポジトリ直下にAI向けルール、README、検証コマンド一覧を置きます。AI向けには、編集してよい範囲、触ってはいけない秘密情報、必ず実行する検証、デプロイ時の承認条件を書きます。
設計では、リポジトリの入口を明確にします。セットアップ、開発サーバー起動、テスト、型チェック、フォーマット、データ初期化をドキュメントだけでなくスクリプトとして提供し、AIにも人にも同じ手順を使わせます。
実装で効く細部
package.jsonのscriptsやMakefileに、dev、typecheck、test、build、lintをまとめます。初回セットアップは1コマンドに寄せ、失敗しやすいキャッシュ削除やロックファイル再生成はトラブルシュートとして残します。
package scripts、Makefile、Docker Compose、サンプルenv、seedデータを揃えます。AIエージェント向けには、作業開始時に読むルール、禁止事項、検証コマンド、公開不可情報をAGENTS.mdなどにまとめます。
- 初回セットアップと日常起動を分け、何度実行しても安全なコマンドにする。
- サンプルenvには秘密情報を入れず、必須変数の説明と検証を用意する。
- AIが生成した変更もCIで同じtypecheckやtestを通す。
壊れ方を観測する
検証では、新しいワークツリーでREADMEだけを見て起動できるか、AIエージェントがルールを読んで適切な検証まで到達できるかを確認します。CIとローカルのコマンド名も揃えます。
検証では、新しい作業環境でREADMEまたはAGENTS.mdの手順だけで起動できるかを確認します。依存キャッシュがない状態、DBが空の状態、ポート競合時の挙動も見ます。
捨てた選択肢とトレードオフ
ルールを細かくしすぎると、AIの作業が硬直します。禁止事項は秘密情報や本番操作など重要なものに絞り、通常の実装判断は既存パターンを読むよう促す方が効果的です。
ブートストラップ整備は機能開発ではないため後回しにされがちです。しかし環境が不安定なままAIエージェントを使うと、修正速度より確認コストが上回ります。小さなスクリプトから始めるだけでも効果があります。
現場に残す判断軸
AIエージェント開発の再現性は、モデル性能だけでは決まりません。リポジトリに作業の入口と検証手順を明確に置くことで、人間にもAIにも扱いやすい開発環境になります。
AIエージェントの再現性は、モデルの性能だけでは決まりません。同じ入口、同じ検証、同じルールを用意することが、AIを開発プロセスに安全に組み込む土台になります。
