title: "12文書でも3文書でもダメだった ― AIに開発を任せる「コア7文書」に行き着くまで"
tags:
- AI
- ClaudeCode
- GitHubCopilot
- 仕様駆動開発
- 開発手法
private: false
updated_at: ''
id: null
organization_url_name: null
slug: ai-spec-driven-seven-documents
ignorePublish: false
はじめに
AIにコードを書かせて、こんな経験はないでしょうか。
- 生成されたコードが、既存のアーキテクチャと全く噛み合わない
- PRが巨大になりすぎて、レビューが不可能になる
- 「なぜこう実装したのか」が分からず、修正に余計な時間がかかる
- 何度言っても、同じような間違いを繰り返す
こういう目に遭うと、「やっぱりAIは信用できない」という結論になりがちです。
でも、何度もAIに開発を任せてきて分かったのは、本当の問題はAIの能力ではないということでした。問題は、AIに渡している「入力」――つまりスコープの曖昧さにあります。
そこで誰もが「じゃあ仕様をちゃんと文書で渡そう」となるのですが、ここで第二の沼にハマります。
開発文書って、結局いくつ必要なんだ？
この記事は、その問いに対して 実際に「12文書」「3文書」「7文書」を試して、それぞれに殴られた 末の考察です。結論だけ言うと最終的に7文書に落ち着いたのですが、面白いのは数よりそこに至る過程のほうだと思うので、その絞り込みの流れを共有します。
そもそも、開発文書はこんなにある
従来のソフトウェア開発では、ドキュメントのテンプレートが 60種類以上 あることも珍しくありません。「さすがに盛ってるだろう」と思うかもしれないので、代表的なものを開発フェーズ順に全部並べてみます。
| フェーズ | 文書 | 数 |
|---|---|---|
| 企画・要件 | 企画書 / 提案依頼書（RFP）/ ビジネス要件定義書（BRD）/ システム要件定義書（SRS）/ 機能要件一覧 / 機能仕様書 / 非機能要件定義書 / ユースケース仕様書 / ユーザーストーリー（ストーリーマップ）/ 要求トレーサビリティマトリクス（RTM） | 10 |
| 設計 | 基本設計書（外部設計）/ 詳細設計書（内部設計）/ アーキテクチャ設計書 / システム構成図 / ネットワーク構成図 / API仕様書（OpenAPI・Swagger）/ データベース設計書（ER図）/ テーブル定義書 / データ・ドメインモデル定義書 / 画面設計書（UI仕様）/ 画面遷移図 / シーケンス図・アクティビティ図 / 状態遷移図 / コンポーネント設計書 / インターフェース定義書（IF一覧）/ ADR（設計判断記録） | 16 |
| セキュリティ・データ | セキュリティ設計書 / 認証・認可設計書 / 個人情報・データ取扱い方針 / バッチ・帳票設計書 | 4 |
| 開発・実装 | コーディング規約 / 命名規則 / 開発環境構築手順書 / Git運用・ブランチ戦略 / コードレビュー基準 / 依存ライブラリ管理表 | 6 |
| テスト・品質 | テスト計画書 / テスト戦略書 / 単体テスト仕様書 / 結合テスト仕様書 / システムテスト仕様書 / 受け入れテスト仕様書（UAT）/ 性能・負荷テスト計画書 / テストデータ定義書 / 不具合管理表（バグ票）/ 品質保証計画書 | 10 |
| リリース・運用 | リリース計画書 / デプロイ手順書 / データ移行計画書 / CI/CDパイプライン定義 / 運用設計書 / 運用手順書 / 監視・アラート設計書 / 障害対応手順書（インシデント対応）/ バックアップ・リストア手順書 / SLA・SLO定義書 / ランブック（Runbook） | 11 |
| プロジェクト管理 | プロジェクト計画書 / WBS・ガントチャート / リスク管理表 / 課題管理表 / 議事録 / 体制図・RACI | 6 |
| ドメイン・索引 | 用語集（ドメイン辞書）/ ビジネスルール定義書 / README | 3 |
ざっと数えても 66種類。数え方によって増減はありますが、まじめに揃えようとすると軽く60を超えるのが現実です。
人間でも全部は読みません。では、これを全部AIに渡せば最強の仕様になるのでしょうか？
答えはNoです。理由は2つあります。
- コンテキストウィンドウの制限：60ファイルを毎回読ませるのは現実的でなく、渡せたとしても重要な情報が薄まる
- もっと根本的な問題：情報が散在すると、文書間に矛盾が生まれる
特に2つ目が効きます。「ユーザー登録の仕様」が要件定義にも機能仕様にもAPI仕様にも書かれていて、しかもそれぞれ微妙に違う――AIはどれを信じればいいか分からなくなります。
試行錯誤の記録：60 → 12 → 3 → 7
ここからが本題です。「ちょうどいい文書の数」を、実際に振れ幅の両端から探っていきました。
実験1：「必要そうなものは全部用意する」→ 12文書
まず、まじめに整理した12文書構成を試しました。
要件定義 / 機能仕様 / 非機能要件 / API仕様 / DB設計 / コンポーネント設計 / テスト計画 / テスト仕様 / デプロイ手順 / 監視設計 / 障害対応 / 用語集
結果、2つの問題が出ました。
- 文書間の重複と矛盾：同じ仕様が複数ファイルに、少しずつ違う記述で散らばる
- AIへの指示の複雑化：「実装して」と言うたびに「要件定義のここと、機能仕様のここと、API仕様のここを参照して」と毎回指定が必要になる
整理したつもりが、かえってAIを迷わせていました。
実験2：振り切って削る → 3文書
逆に「最小限だけでやってみよう」と、3文書（README / ARCHITECTURE / PATTERNS）だけで始めたプロジェクトもありました。
今度は別の問題です。
- ビジネスルールの置き場所がない：「この割引ルールはどこに書く？」「この状態遷移はどこで管理する？」が頻発し、行き場を失った情報が全部READMEに流れ込んで肥大化
少なすぎると、今度は情報が行方不明になりました。
着地：「重複しないが、欠けない」均衡点 → 7文書
12は多すぎて矛盾を生み、3は少なすぎて情報が迷子になる。この両端を行き来した結果、たどり着いたのが 7文書 でした。
60以上の開発文書
│ 多すぎる：コンテキスト超過＋情報が散在して矛盾が生まれる
▼
【実験1】12文書に整理
│ ❌ 文書間の重複と矛盾
│ ❌ 指示が複雑化（毎回「あれとこれとそれを参照して」）
▼
【実験2】3文書まで削る
│ ❌ ビジネスルールの置き場所がない → READMEが肥大化
▼
【結論】コア7文書（重複しない／欠けない 均衡点）
7という数字に意味があるというより、「情報の重複を避けつつ、必要な情報が欠けない」バランスを探した結果がたまたま7だった、という順番です。
残ったコア7文書
最終的に残ったのが、この7つです。それぞれに明確な役割が1つずつ割り当たっていて、「この情報はどこに書くか」で迷わない構成になっています。
| 文書 | 役割 | ひと言で |
|---|---|---|
| MASTER.md | プロジェクトの索引。AIが最初に読む地図 | Where |
| PROJECT.md | なぜ作るか（ビジョン・要件） | Why |
| ARCHITECTURE.md | どう実装するか（構成・技術・ADR） | How |
| DOMAIN.md | ビジネスルール・用語集 | What |
| PATTERNS.md | どう書くか（規約・頻出/アンチパターン） | How to write |
| TESTING.md | 何をテストするか | Verify |
| DEPLOYMENT.md | どうリリース・運用するか | Ship |
この7つは「あれば便利な文書」を集めたものではなく、欠けるとAIが具体的に何に迷うかから逆算して設計されています。
| 欠けている文書 | AIが迷うこと | 結果 |
|---|---|---|
| MASTER.md | どこに何があるか分からない | 無関係なコードを参照する |
| PROJECT.md | なぜこの機能が必要か分からない | 要件と違う実装をする |
| ARCHITECTURE.md | どう実装すべきか分からない | 既存と整合しない設計をする |
| DOMAIN.md | ビジネスルールが分からない | ルール違反の実装をする |
| PATTERNS.md | どう書くべきか分からない | 一貫性のないコードを書く |
| TESTING.md | 何をテストすべきか分からない | テストが漏れる／過剰になる |
| DEPLOYMENT.md | どうリリースすべきか分からない | 運用できない実装をする |
たとえば DOMAIN.md がないままECサイトで「商品購入機能を実装して」と頼むと、「1回の購入は10商品まで」「5,000円以上で送料無料」といったチーム内では当たり前だがどこにも書かれていないルールを、AIは知る術がなく一般的な実装で埋めてしまいます。これは「AIが悪い」のではなく、ルールの置き場所＝DOMAIN.mdを用意していなかった側の問題です。
迷ったときの原則：Why / What / How
7文書まで絞っても、運用していると「この情報、どの文書に書くんだっけ？」と迷う瞬間が来ます。そのとき効くのが、この対応づけです。
- Why（なぜ必要か） → PROJECT.md
- What（何を実現するか） → DOMAIN.md
- How（どう実現するか） → ARCHITECTURE.md
- How to write（どう書くか） → PATTERNS.md
文書は最初から7つ完璧に揃える必要はありません。まずは MASTER.md / ARCHITECTURE.md / PATTERNS.md の3つから始めて、レビューで指摘された内容を該当文書に追記しながら育てていくのが現実的です。
「さっき3文書は失敗したのでは？」と思うかもしれません。失敗したのは3つで止めたケースです。ここでの3つは、ビジネスルールが出てきたら DOMAIN.md を足す、というように7つまで育てる前提のスタート地点。索引も、肥大化しがちな README ではなく専用の MASTER.md に分けています。
それで、効果はあったのか
この7文書構成とIssue駆動の開発フローを整えた状態で、RAGチャットボットの機能実装をAIに任せたときの計測結果です。
| 指標 | 結果 |
|---|---|
| PRマージ率 | 98%（321件中315件） |
| コードレビュー工数 | 97%削減（人間が担当したのは全体の3.3%） |
※ あわせて行数ベースの生産性は業界平均の100倍超を記録しましたが、これは「実装フェーズに限定した行数比較」であり、要件定義などの上流工程は含みません。条件付きの数字として捉えてください。
ポイントは、「AIが速い」のではなく「仕様が整っていれば、AIは速く・正確に動ける」 ということです。98%がそのままマージされている事実が、品質を落とさずにこれを実現できたことを示しています。逆に言えば、仕様が曖昧な状態ではこの生産性は再現できません。
まとめ
- 開発文書は多ければいいわけではない。多すぎると矛盾が生まれ、AIが迷う
- かといって少なすぎるとビジネスルールが行方不明になり、READMEが肥大化する
- 12文書と3文書の両端を試した結果、「重複しない／欠けない」均衡点がコア7文書だった
- 7文書は「あると便利」ではなく「欠けるとAIが何に迷うか」から逆算して設計されている
「文書を何個作るか」で消耗していたのが、「この情報はどの文書に書くか」だけ考えればよくなった――この移行が、AIに安心して開発を任せられるかどうかの分岐点でした。
この記事は、書籍『AI仕様駆動開発 ―― AIエージェント開発の新常識』のエッセンスを抜粋・再構成したものです。各文書に具体的に何を書くか、テンプレート、Issue駆動の実践フロー、組織への導入方法は書籍で詳しく解説しています。
📘 書籍はこちら
- Kindle（電子版）: amzn.asia/d/09XOussK
- ペーパーバック（紙版）: amzn.asia/d/02BXIxN3