1. はじめに / 課題
昨今、ClaudeCodeのようなAIエージェントがコードを書いてくれるようになり、実装速度は大きく向上しました。
私も手作業でコードを書くことがほぼなくなりました。
しかし、その一方でよく遭遇するのが、局所的には正しいがプロジェクト全体の設計とは矛盾している実装をAIが自信満々に提案するという問題です。
これはAIの能力不足というより、セッションごとに文脈がリセットされ、過去の設計判断や背景を継続して保持できないことが原因です。
そのため、AI駆動開発では「設計判断を的確にAIへ伝える仕組み」が重要になります。
この記事では、docs/ を設計の唯一の正（Single Source of Truth）として運用し、AIによる実装・レビュー・ドキュメント更新を組み合わせることで、設計と実装の乖離を最小限に抑える運用方法を紹介します。
▪️イメージ図
2. AIが設計を理解するための docs/ 構成
AIにプロジェクト全体の文脈を理解させ、実装の一貫性を保つためには、アーキテクチャやドメインルールなどの「お約束ごと」を docs/ ディレクトリ配下に集約・整理することが重要です。
AIエージェントには AGENTS.md などを経由して、これらの docs/ をコンテキスト（設計の正）として読み込ませた上で実装やコードレビューを行わせます。
これにより、プロジェクト固有の文脈を外さない高品質なアウトプットが得られるようになります。
以下のように役割ごとにドキュメントを分割・管理します。
例）
docs/
├── README.md
├── architecture.md
├── domain.md
├── data-model.md
├── api.md
├── decisions.md
├── concerns.md
└── development.md
| ファイル | 役割 | 主な内容 |
|---|---|---|
README.md |
ドキュメント全体の入口 | 参照順序、更新ルール、各ファイルへのリンク |
architecture.md |
システム全体の設計 | レイヤー構成、責務分担、ディレクトリ構成 |
domain.md |
ドメイン知識 | 業務ルール、用語集、ユースケース |
data-model.md |
データ設計 | ER図、テーブル設計、状態遷移 |
api.md |
API設計 | エンドポイント、リクエスト・レスポンス、認可方針 |
decisions.md |
設計判断の記録 | なぜその設計を採用したか、却下した案 |
concerns.md |
注意事項・例外仕様 | バグに見えるが意図した仕様、変更時の注意点 |
development.md |
開発ルール | 開発フロー、テスト方針、コーディング規約 |
3. この仕組みの良いところ
3.1 実装の精度が上がる
AIは実装前に AGENTS.md や docs/ を参照し、プロジェクト固有の設計方針やルールを確認します。
そのため、単に動くコードではなく、既存のアーキテクチャや責務分担に沿ったコードを生成しやすくなります。
また、実装後にコードとドキュメントの差分を確認させることで、設計から外れた実装を早い段階で検出できます。
3.2 コードレビューの精度が上がる
PR作成時にも、AIにAGENTS.mdやdocs/と変更内容を比較させます。
これにより、一般的なコード品質だけでなく、プロジェクト固有の設計ルールに違反していないかまで確認できます。
レビュー基準がドキュメントとして明確になるため、AIによる的外れな指摘や、レビュアーごとの判断のばらつきも減らせます。
4. 注意点
この運用では、docs/を常に最新の状態に保つ必要があります。
実装だけが変更され、ドキュメントの更新を忘れると、AIが古い設計情報を正しいルールとして参照してしまいます。その結果、誤った実装やレビューにつながる可能性があります。
そのため、コードを変更した際は、docs/の更新が必要かも同時に確認する運用が重要です。
5. docs の更新も AI で自動化する
docs/ を「設計の正」として運用するためには、常に最新の状態を保つ必要があります。
しかし、人が毎回ドキュメントを更新する運用では、更新漏れが発生しやすく、AIが古い設計情報を参照してしまいます。
そこで、コード変更後にAIが実装と docs/ の差分を確認し、更新が必要かを判定する仕組みを導入しています。
差分が見つかった場合は、次の2パターンに分けて運用します。
パターン1: docs/ が正しく、実装が間違っている
AIが設計との不整合を検知し、人間へ修正を提案します。
この場合は、docs/ は更新せず、実装を修正します。
パターン2: 実装が正しく、docs/ が古い
人間が「設計変更が正しい」と判断した場合のみ、AIが docs/ を更新し、その変更もPRへ含めます。
つまり、AIは更新作業を担当し、どちらを正とするかの判断は人間が行います。
この役割分担により、docs/ を最新に保ちながら、設計と実装の一貫性を維持できます。
6. 導入して感じた効果
実際にこの運用を取り入れてから、AIとのやり取りは以前よりも安定するようになりました。
これまでは、AIが一般的なベストプラクティスに基づいた実装を提案する一方で、プロジェクト固有の設計方針や責務分担を考慮できず、設計とのズレが生じることがありました。
しかし、docs/ を設計の唯一の正（Single Source of Truth）として運用し、AIが常にその内容を参照して実装・レビューを行うようにしたことで、次のような効果を実感しています。
- AIがプロジェクト固有の設計方針を考慮した実装を提案するようになった
- 設計と実装の乖離を、PRの段階で早期に検出できるようになった
- AIによるコードレビューが、プロジェクト固有のルールに沿った指摘になった
-
docs/が設計の唯一の正として機能し、設計判断をチーム全体で共有しやすくなった
もちろん、この仕組みだけですべての問題を解決できるわけではありません。
しかし、AIに毎回プロジェクトの背景や設計思想を説明し直す必要が大幅に減り、一貫性を保ちながら開発を進められるようになりました。
AI駆動開発では「AIにコードを書かせること」だけでなく、「AIが正しい判断をできる環境を整えること」も同じくらい重要だと感じています。
7. 運用上の注意点
docs/ を設計の正として運用する場合、ドキュメントを増やすこと自体が目的にならないよう注意が必要です。
特に、次の点を意識して運用しています。
-
docs/を細かく分割しすぎない - 同じ内容を複数のファイルへ書かない
-
docs/の変更も必ずPRレビューの対象にする - 同じ設計情報を複数箇所で管理せず、「設計の正」は一箇所に集約する
ドキュメントを細かく分割しすぎると、AIが必要な情報を探しにくくなり、人間にとっても全体像を把握しづらくなります。
また、同じ設計ルールを複数のファイルへ記述すると、更新漏れによって内容に矛盾が生じる可能性があります。
AIは矛盾した情報のどちらを優先すべきか判断できないため、誤った実装やレビューにつながりかねません。
そのため、設計情報はできるだけ一箇所に集約し、別のドキュメントから参照する場合は、同じ内容を重複して書くのではなくリンクを張るようにします。
さらに、コードだけでなく docs/ の変更もPRに含め、実装内容と設計内容が一致しているかをレビューすることが重要です。
この運用を形骸化させないためには、ドキュメントの量を増やすことよりも、必要な情報が整理され、常に最新の状態に保たれていることを優先する必要があります。
8. まとめ
AI駆動開発では、「AIにコードを書かせること」だけでなく、「AIが正しい判断をできる環境を整えること」が重要だと感じています。
docs/ を設計の唯一の正（Single Source of Truth）として運用することで、AIはプロジェクト固有の設計方針を踏まえた実装やレビューを行いやすくなり、設計と実装の一貫性も保ちやすくなりました。
もちろん、この運用だけですべての課題が解決するわけではありません。しかし、AIに毎回設計の背景を説明し直す手間が減り、より安心してAIと開発を進められるようになったと実感しています。
今後もAIエージェントは進化していくと思いますが、その性能を最大限に引き出すためには、AIが正しく判断できる環境づくりも、これまで以上に重要になっていくと考えています。