AIコーディングエージェント時代のプロジェクト構造設計 ─ 仕様をどこに、どう置くか
（2026年2月6日時点の記事です）
1. はじめに
「Docs as Code × 仕様駆動開発 × 生成AI」の組み合わせがすごい、という話を聞いて自分なりに可能性を探ってみました。ただ、正直なところ、これらの概念を無理に組み合わせても新たな価値は生まれないと思われます。
というのも、Docs as Codeも仕様駆動開発も、ソフトウェア工学では以前から存在する考え方です。FastAPIがOpenAPIドキュメントを自動生成するように、すでにツールに組み込まれています。「思想」として再発見するより、いま実際に何が変わっているのかを考えた方が有益です。
AIエージェントを利用することで変わったのは「仕様を誰が読むか」です。
Claude Code、Cursor、Windsurf等のAIコーディングエージェントは、プロジェクト内のファイルを直接読みます。つまり、人間だけでなくAIエージェントがコンテキストとして消費することを前提にした仕様の置き方を考える必要が出てきました。
この記事では、AIエージェントと協働するためのプロジェクト構造設計について、私の実践と考察を共有します。
この記事はAIエージェントを利用してコーディングしたい。
AIエージェントを用いたコーディングの効果的な実装を行いたい。
これらの問題に対処するための初歩的な読み物となります。
2. なぜ「仕様の置き場所」が問題になるのか
2.1. AIエージェントの読み方
現在のAIコーディングエージェント（Claude Code、Cursor、Windsurf等）は、以下のような形でプロジェクトのコンテキストを取得しています。
-
プロジェクトルールファイル（
CLAUDE.md、.cursorrules等）を最初に読む - コードベース全体をコンテキストとして参照できる
- 必要に応じてファイルを検索・読み込みする
つまり、AIエージェントにとってのSSoT（Single Source of Truth）はリポジトリそのものです。Confluenceに書かれた仕様書でも、Notionのページでも、Google Docsでもありません。リポジトリ内にあるファイルです。
2.2. 従来のドキュメント管理との違い
従来の「docs/にREADMEやAPIリファレンスを置く」運用と何が違うのか。大きな違いは読み手の特性です。
人間が読む場合：
構造化された見出し、図表、リンク、コンテキストの省略（前提知識を仮定）が有効です。
AIエージェントが読む場合：
前提知識を仮定できません。プロジェクト固有の判断基準、制約、設計意図を明示的にテキストで書く必要があります。また、参照パスが明確であること（どのファイルを見ればわかるのか）が重要です。
2.3. MCP経由のアクセスは必要か
「MCPサーバーを立てて仕様書にアクセスさせる」というアプローチを見かけますが、仕様書へのアクセスに限って言えば、多くの場合オーバーエンジニアリングです。
MCPが活きるのはコードベースの外にある情報源へのアクセスです。例えばSlack、Jira、データベース、外部APIなど。仕様がリポジトリ内のマークダウンファイルとして存在するなら、AIエージェントはそのまま読めます。わざわざMCPサーバーを経由する必要はありません。
ただこれは中小規模の開発、Webアプリなど比較的軽量な開発に限ります。 5. この方法の適用範囲と限界 以降に記載するように、この手法には限界があると考えています。
3. プロジェクト構造の設計
3.1. 基本構造
AIエージェントがコンテキストを効率よく取得できるプロジェクト構造の一例です。
project/
├── .claude/
│ ├── CLAUDE.md # プロジェクトのメインルール（インデックス）
│ ├── rules/
│ │ ├── code-style.md # コーディング規約
│ │ ├── testing.md # テスト規約
│ │ └── api-design.md # API設計ルール
│ └── skills/ # プロジェクト固有のスキル（必要に応じて）
├── spec/
│ ├── overview.md # システムの設計意図・全体像
│ ├── architecture.md # アーキテクチャの判断と理由
│ ├── domain/
│ │ ├── user.md # ドメインモデルの定義・制約
│ │ └── order.md
│ └── api/
│ ├── endpoints.md # API仕様（または OpenAPI yaml）
│ └── error-codes.md # エラーコード体系
├── docs/ # 人間向けドキュメント（セットアップ手順等）
├── src/
└── tests/
Claude Codeでは、.claude/rules/ 配下のマークダウンファイルがメインの CLAUDE.md と同じ優先度で自動的に読み込まれます。importは不要で、ファイルを置くだけで有効です。これにより、チーム内でルールの担当を分けられます（フロントエンドチームが code-style.md を、セキュリティチームが security.md を管理する等）。
ポイントは .claude/ とは別に spec/ ディレクトリを導入し、docs/ とも分離することです。
なお、この spec/ ディレクトリの考え方は、AWSが開発したAIコーディングIDE「Kiro」のspec-driven developmentに近いイメージです。Kiroでは .kiro/ 配下に要件定義→設計→実装タスクの3フェーズで構造化された仕様を管理します。本記事ではClaude Codeを前提としているため、ツール固有のディレクトリ（.kiro/）ではなくリポジトリ直下の spec/ として切り出していますが、「仕様をファーストクラスの成果物としてリポジトリ内で管理する」という思想は共通です。
3.2. .claude/、spec/、docs/ の役割分担
.claude/：エージェントへのルールと指示
AIエージェントが毎回自動的に読み込む、プロジェクトの「どう振る舞うべきか」を記述する場所です。
記載する内容の例：
-
CLAUDE.md：プロジェクト概要、技術スタック、spec/への参照（インデックス） -
rules/code-style.md：コーディング規約、命名規則 -
rules/testing.md：テストの書き方、カバレッジ基準 -
rules/配下のルールファイル：チームごとに分割管理可能
※なお、Cursorも同様にrulesを設定する項目があり、AIエージェント全般に振る舞いを設定する構造は搭載されています。
spec/：設計判断と制約の記録
AIエージェントと人間の両方が参照する、プロジェクトの「なぜそうなっているか」を記述する場所です。.claude/rules/とは異なり、自動読み込みはされません。AIエージェントが必要に応じて参照しに行く形です。
記載する内容の例：
- システムの設計意図と全体像
- アーキテクチャ上の判断とその理由（ADR的な役割）
- ドメインモデルの定義、ビジネスルール、制約条件
- API仕様やインターフェース定義
- 命名規則やコーディング規約のうち、設計判断に関わるもの
docs/：運用・手順の記録
主に人間が読む、プロジェクトの「どうやるか」を記述する場所です。
記載する内容の例：
- セットアップ手順、開発環境構築
- デプロイ手順
- トラブルシューティング
- 自動生成されたAPIリファレンス（FastAPI + OpenAPI等）
3.3. .claude/CLAUDE.md（プロジェクトルールファイル）の位置づけ
.claude/CLAUDE.mdは、AIエージェントへの最初の入口です。ここにはプロジェクト全体のコンテキストを凝縮しつつ、詳細はspec/への参照で示します。rules/配下のファイルと合わせて自動的に読み込まれるため、ルールの分割管理が可能です。
# プロジェクト概要
本プロジェクトは〇〇のバックエンドAPIです。
## 技術スタック
- Python 3.12 / FastAPI
- PostgreSQL 16
- テスト: pytest
## 設計方針
- 詳細は spec/overview.md および spec/architecture.md を参照
- ドメインモデルの定義は spec/domain/ 配下を参照
## やってはいけないこと
- ORMのモデルに直接ビジネスロジックを書かない
- spec/domain/ の制約に反する実装をしない
コーディング規約やテスト規約は .claude/rules/ に分離しているため、CLAUDE.md自体は簡潔に保てます。重要なのは肥大化させないことです。エージェントは毎回これを読むため、コンテキストウィンドウを圧迫します。詳細はspec/やrules/に委譲し、CLAUDE.mdはインデックスとしての役割に留めます。
4. 仕様の書き方：AI時代に何が変わるか
4.1. 「仕様を書いてからAIに渡す」は一方向すぎる
「仕様駆動開発」の文脈では「人間が仕様を書く → AIがコードを生成」という一方向のフローが想定されがちですが、2025年後期からはAIコーディングは対話的・反復的です。
現実的なワークフロー：
-
spec/に初期的な設計意図・制約を書く - AIエージェントに実装を依頼する
- AIの出力をレビューし、必要に応じて
spec/を更新する - 修正指示を出す → AIが反映する → 繰り返し
つまり仕様と実装が双方向に影響し合うのが自然な形です。spec/は「最初に完成させる設計書」ではなく、プロジェクトの意思決定が蓄積されていくドキュメントです。
ただ、課題がないわけではなく、「いつ誰が仕様を変更・更新するのか」です。
AIに任せれば良いのですが、明確にAIが仕様を壊す問題とコード変更による乖離問題などがあります。
コントロールをAIに任せすぎるのは、危険です。
4.2. AIエージェントが読みやすい仕様の書き方
AIエージェントに効果的に伝わる仕様には、いくつかの傾向があります。
明示的に書く： 「常識的に考えれば分かる」はAIには通用しません。判断基準を明文化します。
## ユーザー認証
- アクセストークンの有効期限は30分
- リフレッシュトークンの有効期限は7日
- パスワードはbcryptでハッシュ化（コストファクター12）
- ログイン試行は5回失敗で15分ロック
「なぜ」を書く： 制約だけでなく理由を書くことで、AIが文脈を理解し、想定外のケースでも適切に判断できるようになります。
## ページネーション
カーソルベースのページネーションを使用する。
オフセットベースを使わない理由：データ量が多く、深いページでパフォーマンスが劣化するため。
否定形の制約を明記する： AIは「やっていいこと」には柔軟に対応しますが、「やってはいけないこと」は明示しないと守れません。
## やってはいけないこと
- ユーザーの個人情報をログに出力しない
- 外部APIの呼び出しをトランザクション内で行わない
- テーブルのカラム追加時にNOT NULL制約をデフォルト値なしで追加しない
4.3. ドキュメントの自動更新について
「CI/CDパイプラインで生成AIにドキュメントを更新させる」という提案を見かけますが、現時点では実用性に疑問があります。CI/CDにLLM APIを組み込むと、非決定的な出力がパイプラインに入り、コストとレイテンシも問題になります。
より実用的なのは、AIエージェントがコード変更とドキュメント変更を同時にコミットするパターンです。PR作成時に「関連するspec/やdocs/も更新して」と指示すれば、開発フロー自体にドキュメント更新が組み込まれます。
既にツールに組み込まれている自動生成（FastAPI → OpenAPI等）は引き続き使いつつ、設計判断や制約の記録はAIエージェントと人間が協働して更新する、というのが現実的な運用です。
5. この方法の適用範囲と限界
5.1. マークダウンベースの仕様管理が通用する範囲
ここまで紹介した spec/ ディレクトリにマークダウンで仕様を管理するアプローチは、主にWebアプリケーションや比較的小〜中規模のソフトウェアプロジェクトを想定しています。
正直に言えば、このやり方には明確な限界があります。
5.2. 大規模システム・組み込みでは通用しない
組み込みシステム、自動車、航空宇宙、医療機器などの分野では、仕様管理の要求レベルがまったく異なります。
実務での経験が薄い分野もあるので、AIに手伝ってもらったところ以下などが候補として上がりました。
マークダウンでは足りないもの：
- トレーサビリティ：要件→設計→実装→テストの追跡関係を厳密に管理する必要がある。マークダウンのリンクでは到底足りない
- 要件の属性管理：各要件にID、優先度、ステータス、担当者、検証方法、安全性レベル等の属性が必要。マークダウンのテキストでは構造化が限界に達する
- 変更管理：要件変更時の影響範囲分析（インパクト分析）を自動化する必要がある
- 規制対応：ISO 26262（自動車）、DO-178C（航空）、IEC 62304（医療機器）等の安全規格への準拠を証明するための文書体系が求められる
- 数千〜数万件の要件：規模が大きくなると、ファイルベースのフラットな管理では破綻する
こうした領域で使われているツール群：
- IBM DOORS / DOORS Next：要件管理の業界標準。トレーサビリティマトリクス、変更管理、ベースライン管理を備える
- SysML / MBSE（モデルベースシステムズエンジニアリング）：要件を構造化されたモデルとして管理し、設計要素やテストケースとの関係を可視化する
- Jama Connect、Polarion、codebeamer等の専用ALMツール
これらは「マークダウンで書いてGit管理」の世界とは根本的に異なるパラダイムです。
5.3. AIエージェントとの接続はMCPが活きる領域
要件管理ツールに格納された仕様をAIエージェントが参照するには、MCPサーバー経由でのアクセスが現実的な手段になります。リポジトリ内のマークダウンとして管理しきれない規模と複雑さだからこそ、専用ツール＋MCPという構成に意味が出てきます。
5.4. この記事で扱っている範囲
改めて整理すると、本記事のアプローチが適しているのは以下のような場合です。
- Webアプリケーション、API、モバイルアプリ等のソフトウェア開発
- チーム規模が数名〜数十名程度
- 安全規格への厳密な準拠が求められない
- 要件の数が数百件程度まで
組み込みや大規模システムの仕様管理にAIを活用する話は、それ自体が別の大きなテーマです。本記事ではスコープ外としますが、この領域でのAI活用は今後急速に進むと思われます。
6. まとめ
「Docs as Code」や「仕様駆動開発」を思想として再発見するより、AIエージェントが参照するコンテキストをどう設計するかという実務的な問いに向き合う方が生産的です。
ポイントを整理すると：
- 仕様はリポジトリ内に置く。 AIエージェントが直接読めることが重要。MCPサーバーを経由する必要は基本的にない。
-
.claude/、spec/、docs/を分離する。 エージェントへのルール（.claude/）、設計判断・制約（spec/）、運用手順（docs/）は役割が異なる。 -
.claude/CLAUDE.mdはインデックスにする。 ルールはrules/に分割し、詳細はspec/に委譲して肥大化させない。 - 仕様は一方向ではなく双方向で育てる。 AIエージェントとの対話を通じて、仕様と実装が相互に洗練されていく。
- ドキュメント更新はCI/CDより開発フローに組み込む。 AIエージェントにコードとドキュメントを同時に更新させる。
特別に新しい概念はありません。リポジトリにマークダウンで仕様を置いてGit管理する、というのは昔からやっていたことです。ただ、「AIエージェントが読む」という新しい読み手が加わったことで、書き方と構造に気を配る理由が明確になったのだと思います。
また、本記事の4.1. 「仕様を書いてからAIに渡す」は一方向すぎる にも記載した問題を解決すると思われる、Agent Teamsが発表されました。（記事を書いた前日に発表）
1歩遅れても良いので、取り組んでいくことでAIとの協働できる環境が構築できるのではないかと思います。少しづつ取り組んでいきたいですね。
この記事が参考になれば幸いです。異なる意見や感想があれば、ぜひコメントでお聞かせください。