問題提起: AIエージェントがコードを量産する時、開発はどこで壊れるのか

私たちは今、かつてない生産性のボーナスタイムにいる。AIエージェントは仕様からコードを起こし、修正し、テストを書き、ドキュメントまで吐き出す。タスクを投げれば、数分後には見栄えのよい成果物が並ぶ。一見、理想的な未来だ。しかし、プロジェクトが数週間を越えたあたりから、奇妙なノイズが現れ始める。「なぜこの関数は二重に存在するのか」「さっき直したはずのバグが別ブランチで再発した」「生成されたスクリプトが互いに矛盾している」——。誰も悪くない。だが、全員が少しずつ疲弊する。これはエンジニアの怠慢でも、AIの能力不足でもない。原因は“生成の仕方”にある。

本稿では、AIエージェントによるコード生成がなぜプロジェクトを軋ませるのか、その構造的な要因を掘り下げ、実務で効く「運用原則」と「最小限の仕組み」を提案する。合言葉はシンプルだ。生成量を増やすのではなく、生成の“責任範囲”と“可視性”を設計する。

1. 問題の核心: 量ではなく整合性

AIは“良い感じ”のコードをいくらでも作れる。だがプロジェクトを成功に導くのは“良い感じ”ではなく“整合性”だ。整合性とは、以下が常に噛み合って動く状態を指す。

• 同じ概念に同じ言葉を使うこと（命名の一貫性）
• 同じ目的に同じ場所を使うこと（責任の一貫性）
• 変更がどこに波及するかが常に見えること（影響範囲の可視性）

AIが生む摩擦は、まさにこの整合性を侵食する点にある。高速な生成は、責任範囲の境界を曖昧にし、微小な不整合を雪だるま式に蓄積させる。人間は「把握できない」ことに不安を覚え、AIは「把握していない」まま次のアウトプットを出力する。結果、速度は出ているのに、前進していないように感じる。

2. 典型的な失敗パターン

2-1. 重複コードと幽霊スクリプト

生成のたびに微妙に違う関数やスクリプトが積み重なる。片方を直しても、もう片方は古いまま残る。どちらが正なのか、チームは判断できなくなる。

2-2. “勝手修正”による暗黙の破壊

AIが善意でリファクタリングを行う。だが、それは別ディレクトリの設計意図を踏み越える行為かもしれない。テストは通るが、設計原則が壊れる。後から人が追うと、辻褄合わせに時間を溶かす。

2-3. ドキュメント負債

コードは毎日変わるのに、READMEは昨日のまま。生成コードの文脈を説明する単一の場所が存在しない。結果として「なぜこうしたのか」を誰も答えられない。

2-4. プロジェクトマップの欠落

AIにとっての“全体像”は、プロンプトのスコープに等しい。リポジトリの地図がなければ、エージェントは“近く”の最適解を返すが、“遠く”で破綻する。

3. 解決思想: 生成そのものを設計する

鍵は「1ディレクトリ = 1エージェント = 1つの責任」にすることだ。生成を加速する前に、生成の境界を固定する。これにより、重複発生源が物理的に切断され、変更追跡の単位が明確になる。

3-1. ディレクトリ＝エージェント原則

• 各ディレクトリは1人（=1エージェント）の担当範囲とする。
• そのディレクトリでの生成・修正・テスト・ドキュメント更新まで“責任を完結”させる。
• 別ディレクトリを触る場合は、PMエージェント（統括）経由の合意が必須。

3-2. マストファイルの標準化（人間のための“単一の真実”）

• PROJECT.md: 5分で全体像が把握できるドキュメント。目的・KPI・依存関係を明記。
• DIRECTORY_MAP.md: 物理的構造と依存矢印。どこを変えるとどこに響くかを示す。
• AGENTS.md: 各エージェントの権限・責務・禁止事項。
• 各ディレクトリの README.md: その領域の境界・入出力・主なユースケース。

3-3. 変更の可視化と“越境禁止”

• 変更は必ず“責任ディレクトリ内”で完結させる。
• 越境する変更は、PMエージェントを通じてレビュー。評価エージェントが品質を監査。
• 生成だけでなく“意図”を残す。コードの冒頭に「バージョン・目的・変更履歴・担当」を短く記す。

4. 生成ワークフローの最小実装

以下は、現場で即日導入できる“軽量な運用フレーム”だ。

1. すべての生成タスクは「対象ディレクトリ」を明示して起票する。
2. エージェントは該当ディレクトリ内だけを更新し、README.md とヘッダー情報を同時更新する。
3. 変更後は DIRECTORY_MAP.md と PROJECT.md に影響範囲・決定事項を追記する。
4. 大きな設計変更・越境変更は、PM→評価エージェントの2段承認。
5. コード生成前に“どの文脈が必要か”を明示的に列挙し、プロンプトに同梱する（無駄なコンテキスト投入を防ぐ）。

この5ステップだけで、無秩序な量産は整然とした進行に変わる。重要なのは、生成のスピードではなく、生成の“帰属地”を固定することだ。

5. なぜ人とAIの双方に効くのか

人間にとっては「どのMDを読めば状況が分かるか」が明確になる。AIにとってはコンテキストがスリム化され、プロンプトが安定する。結果として、重複と矛盾が激減し、設計意図が保存される。生成のたびに“その場の最適”に流される誘惑からチームを守れる。

6. よくある反論と実務回答

Q. ルールが多いと速度が落ちないか？

A. ルールは“減速”ではなく“整流”を生む。フローが整えば、レビューとリワークが激減し、総合速度は上がる。現場のボトルネックは生成速度ではなく、後追いの整合作業だ。

Q. 小規模プロジェクトにも必要？

A. 小規模ほど効く。初期から境界を決めておけば、スケール時の摩擦が爆発しない。マストファイルはテンプレートをコピーするだけでよい。

Q. ドキュメント更新が面倒では？

A. だから“最小セット”に絞る。PROJECT.md / DIRECTORY_MAP.md / AGENTS.md / 各README.md の4点だけで充分に効果が出る。

7. 実装チェックリスト（導入1日目）

• [ ] 1ディレクトリ=1エージェント原則の宣言
• [ ] マストファイル4点の雛形を配置
• [ ] 生成ヘッダー（バージョン/目的/担当/履歴）テンプレを準備
• [ ] PM・評価エージェント（人/AI）の役割を割り当て
• [ ] 変更時の追記先（PROJECT/DIRECTORY_MAP/各README）の合意
• [ ] “越境時は合意必須”の合図をCIに組み込み（ラベル/チェック）

8. 結論: 生成は“速さ”ではなく“責任”で管理する

AIエージェントは“書く”ことが得意だ。だが、プロジェクトが求めているのは“維持できる構造”である。量を増やす前に、責任の境界を刻み、意図を残し、可視化する。たったこれだけで、生成は破壊ではなく構築の力に変わる。

最後に強調したい。エージェント導入の本当の競争力は、コード行数ではなく、変更に耐える“運用”。あなたの組織に今必要なのは、もっと賢いプロンプトではなく、もっと賢い“地図”だ。プロジェクトの地図（PROJECT、DIRECTORY_MAP、AGENTS、各README）こそが、AIと人間を同じ方向に向けるコンパスになる。

---

付録: 実務で使える最小テンプレ

1. ファイルヘッダー（各言語共通）

/**
 * Module: <何をするモジュールか>
 * Version: v1.0.x
 * Owner: <エージェント/担当>
 * Inputs: <主な入力>
 * Outputs: <主な出力>
 * Changelog: <YYYY-MM-DD> 初版 / <YYYY-MM-DD> 変更内容
 */

1. ディレクトリREADMEの骨子

# ディレクトリ概要
- 責任範囲
- 主な入出力
- 依存先/依存元
- 変更時の注意点（影響範囲）

1. Pull Request テンプレ

## 目的
## 変更点
## 影響範囲
## 確認項目
## ドキュメント更新（該当箇所）

生成の時代に求められるのは、“書けること”より“保てること”。その第一歩は、エージェントのスピードに合わせて、プロジェクトの地図を先に描くことだ。