ドキュメントは AI 開発の「燃料」になる

AI にコードを書かせると最初に効いてくるのは、モデルの賢さではなく「AI に何を見せたか」です。同じ Claude Code を使っても、空っぽのリポジトリで指示するのと、システムの全体像・制約・過去の判断がドキュメントとして揃ったリポジトリで指示するのとでは、出てくるコードの質がまるで違います。AI は人間のように「この会社では普通こうする」「あの取引先の仕様は特殊だ」という暗黙の文脈を持っていません。だからこそ、ドキュメントがそのまま AI の判断材料、つまり燃料になります。

先に結論を述べます。AI 駆動開発で速度と品質を両立させたいなら、ドキュメントを実装より先に置き、AI と人間が同じ一次情報を見て、実装が変わったらドキュメントも同じ変更単位で更新し続ける。この運用がドキュメント駆動開発です。ポイントは「ドキュメントを書くこと」ではなく「ドキュメントを陳腐化させない仕組みを持つこと」にあります。多くのプロジェクトでドキュメントが役に立たないのは、書いていないからではなく、書いた直後から実装とずれていき、誰も信用しなくなるからです。

AI が相手になると、この陳腐化のコストが跳ね上がります。古いドキュメントを一次情報として渡せば、AI は古い前提のまま自信満々に実装を進めてしまう。人間なら「この設計書、最近の実装と違うな」と勘で気づくところを、AI はそのまま信じます。逆に言えば、ドキュメントを常に正しい状態に保てれば、AI は最も強力な実装パートナーになります。本記事では、AI が読む前提のドキュメント構造、実装からの同期方法、そして陳腐化を防ぐ更新フローと CI チェックまでを、実務の手順として整理します。

ドキュメント駆動開発とは — 仕様駆動との関係

ドキュメント駆動開発 (documentation driven development) は、ドキュメントを人間と AI が共有する一次情報として扱い、設計・実装・保守のすべてをそのドキュメントを起点に進める開発スタイルです。ここでいうドキュメントは「あとで読む資料」ではなく「これから何を作るかを定義し、AI への入力にもなる生きた情報」を指します。

近い概念に仕様駆動開発があります。仕様駆動開発は、機能ごとの仕様 (spec) を一次情報にして、そこから実装とテストを導くアプローチです。ドキュメント駆動開発はその一段広い概念で、機能仕様だけでなく、システム全体の構造・運用ルール・設計判断の記録までを含めて「リポジトリに残す文書群」全体を駆動の対象にします。ここで対象になるシステム全体の構造そのものを AI が書きやすい形に設計する考え方は AI 駆動開発のアーキテクチャ設計 — AI が書きやすい構造 で扱っています。仕様駆動開発の具体的な進め方は 仕様駆動開発を AI で実践する で詳しく扱っているので、本記事はその外側にある「プロジェクト全体のドキュメント運用」に焦点を当てます。

両者の関係を整理すると次のようになります。

観点仕様駆動開発ドキュメント駆動開発
起点になる文書機能ごとの仕様 (spec)spec を含むドキュメント群全体
カバー範囲何を作るかの定義構造・制約・判断・運用も含む
主に効く場面機能開発の品質と手戻り削減長期保守・引き継ぎ・チーム開発
AI への渡し方該当 spec をコンテキストへCLAUDE.md を目次に一次情報へ誘導

両者は排他的ではありません。実務では、ドキュメント駆動開発という大枠の中に仕様駆動開発が入れ子になっている、と捉えるのが自然です。プロジェクト全体のドキュメント基盤を整えたうえで、個々の機能は spec を起点に作っていく。この組み合わせが、AI 駆動開発を長く回すための土台になります。

AI が読む前提のドキュメント構造

ドキュメントを AI の燃料にするには、「人間が読む資料」とは違う設計が要ります。AI は毎回コンテキストをゼロから読み込むため、どこに何が書いてあるか、どれが正で何が制約かが構造として明示されていないと、必要な情報にたどり着けません。実務で効くのは、役割ごとにドキュメントを分けて、AI への入口を 1 つに絞る構造です。

CLAUDE.md — 一次情報への目次兼ルールブック

CLAUDE.md は、AI エージェントが毎回のセッションで最初に読む前提条件と禁止事項の凝縮版です。ここにはプロジェクト構造の要点、ビルド・テスト・lint のコマンド、コーディング規約、そして「やってはいけないこと」を簡潔に書きます。重要なのは、CLAUDE.md にすべてを詰め込まないことです。詳細は spec や設計書へリンクで誘導し、CLAUDE.md 自体は「一次情報への目次」として軽く保ちます。肥大化した CLAUDE.md はかえって AI の判断を鈍らせるため、目次役に徹させるのがコツです。CLAUDE.md の具体的な書き方は CLAUDE.md ベストプラクティス にまとめています。

spec — 何を作るかを定義する一次情報

機能ごとの仕様は、リポジトリ内に Markdown で置き、受け入れ条件を具体的に書きます。AI に実装を依頼するときは「この spec の受け入れ条件をすべて満たす実装とテストを書く」と指示し、どの条件を根拠にしたかを説明させます。spec は機能単位に分割しておくと、必要な部分だけをコンテキストに渡せて精度が上がります。

ADR — 設計判断の理由を残す記録

ADR (Architecture Decision Record) は「いつ・なぜ・何を決めたか」を一件ずつ短く残す文書です。たとえば「キャッシュに Redis ではなくインメモリを選んだ理由」「この外部 API はリトライ前提で叩く」といった判断を記録します。ADR が効くのは保守フェーズです。古い記述を見たとき、その判断が今も有効なのか、変えてよいのかを ADR から判断できます。AI に改修を任せるときも、ADR を渡せば「過去にこの選択をした理由」を踏まえた提案が返ってきます。

README — 人間とAIの共通の入口

README はプロジェクトの概要、起動方法、ディレクトリ構成の地図を担います。人間の新規参加者にも AI にも最初の地図として機能するため、ここが古いと全員が迷子になります。

この四層を「CLAUDE.md が目次、spec が定義、ADR が判断の記録、README が地図」という役割分担で運用すると、AI に渡す情報がきれいに整理され、コンテキストの無駄が減ります。AI への具体的な指示の組み立て方は AI 駆動開発のためのプロンプト設計 も参考にしてください。

実装からドキュメントを同期させる仕組み

ドキュメントを先に置くといっても、すべてを手で書き続けるのは現実的ではありません。ここで AI を使うと、実装とドキュメントの距離を縮められます。

まず初版づくりです。既存コードからドキュメントを起こす場合、AI に「このディレクトリのコードを読み、README とディレクトリ構成の地図を作って」「このモジュールの公開関数から API リファレンスのたたき台を起こして」と依頼します。ゼロから書くより速く、抜け漏れも減ります。ただし自動生成された文章は「現状のコードの説明」にすぎず、意図や制約は含まれません。生成物はあくまでたたき台として、人間が意図と制約を書き足します。

次に変更時の同期です。実装を変えたら、その同じ作業の中で AI にドキュメントの該当箇所も直させます。Claude Code に対して「この変更に合わせて、関連する spec と README を更新して。変えた箇所と理由も説明して」と指示すれば、コードとドキュメントを 1 つの変更単位として動かせます。ここで効くのが、コードとドキュメントを同じ Pull Request に含めるルールです。コードだけ先にマージしてドキュメントを後回しにできる構造だと、後回しは永久に来ません。

棚卸しにも AI が使えます。定期的に「README に書かれた起動手順を実際のコードと照合し、食い違いを列挙して」「この spec の受け入れ条件のうち、現在の実装で満たせていないものを挙げて」と AI に監査させると、人間が気づきにくいずれをまとめて洗い出せます。ドキュメントの分量が増えるほど、この監査の自動化が効いてきます。

ただし注意点があります。AI に「ドキュメントを更新して」とだけ頼むと、それらしく書き換えますが、本当に実装と一致しているかは AI も保証しません。生成物を鵜呑みにせず、最終的な正しさは人間のレビューか、次に述べる CI チェックで担保します。AI は同期作業の手数を減らす道具であって、正しさの保証役ではない、という線引きが大事です。

陳腐化を防ぐ更新フローと CI チェック

ドキュメント駆動開発が失敗する最大の原因は、ドキュメントが書かれないことではなく、書いた直後からずれていき誰も信用しなくなることです。これを人の善意で防ぐのは無理があります。仕組みで止めます。

第一に、更新フローをルール化します。具体的には、実装を変える Pull Request には関連ドキュメントの更新を必ず含める、というレビュー条件を置きます。レビュアーは「このコード変更に対応するドキュメントの差分があるか」「spec にない挙動が混入していないか」を確認します。ドキュメントだけ古くなる状態を構造的に作らないことが、最も効く一手です。

第二に、CI で機械的にチェックします。文章だけのドキュメントは CI で検証しづらいと思われがちですが、いくつかの観点は自動化できます。

  • ドキュメント内に書いたコマンドやコードスニペットを CI で実際に実行し、動かなければ落とす
  • ドキュメントから参照しているファイルパスやリンクが実在するかをチェックし、リンク切れを検知する
  • spec の受け入れ条件をテストへ落とし、spec 由来のテストが全て通ることをマージ条件にする
  • CLAUDE.md に書いたビルド・テストコマンドが、実際の CI で使うコマンドと一致しているかを照合する

こうした仕組みを入れると、コードを変えてドキュメントを放置した瞬間に CI が赤くなり、ずれが本番へ流れる前に止まります。spec の受け入れ条件をテストにする手法は仕様駆動開発で詳しく扱っていますが、ドキュメント全体に対しても「文章とコードの一致を機械で検知する」という発想は同じです。

第三に、棚卸しを定期業務に組み込みます。CI で拾えるのは形式的なずれだけで、「この設計判断はもう古い」といった意味的な陳腐化は拾えません。スプリントごと、あるいはリリースごとに AI を使った監査を回し、ADR を見ながら「今も有効か」を人間が判断する時間を取ります。これを習慣にすると、ドキュメントが「信用できる一次情報」のまま保たれます。

ドキュメント駆動は引き継ぎ・保守でこそ効く

ドキュメント駆動開発の投資が最も報われるのは、開発の初期ではなく引き継ぎと保守のフェーズです。

担当者が変わるとき、コードだけが残っていると、新しい担当者は「なぜこう作ったのか」をコードから推測するしかありません。推測は外れることがあり、外れた前提のまま改修すると事故になります。spec と ADR が残っていれば、何を作ろうとしたのか、なぜその設計を選んだのかが文書から分かり、引き継ぎの所要時間が大きく縮まります。AI に改修を任せる場合も同じで、ドキュメントが揃っていれば AI は過去の意図と制約を踏まえた提案を返してきますが、コードしかなければ表面的な変更しかできません。

保守フェーズでは、ドキュメントが「変えてはいけないものの番人」になります。ドメインルールや外部 API の仕様といった制約をドキュメントに明記しておけば、AI に改修を依頼したときに「この制約は守れ」と一次情報として渡せます。制約が暗黙知のままだと、AI は知らずに制約を踏み抜く実装を出してきます。ドキュメント駆動開発は、こうした暗黙知を文書として外部化し、人にも AI にも安全に作業させるための基盤になります。

長期運用する業務システムほど、この効果は大きくなります。数年にわたって複数の担当者と複数の AI エージェントが触るシステムでは、ドキュメントが唯一の連続性を保つ媒体になるからです。

FIXIT のドキュメント運用と効果

FIXIT では、AI 駆動開発のクリエイティブスタジオとして、クライアントワークと社内開発の双方でドキュメント駆動の運用を標準にしています。リポジトリには CLAUDE.md を目次として置き、機能ごとの spec、設計判断を残す ADR、そして人間と AI 共通の入口になる README を役割分担で整備します。実装を変える Pull Request にはドキュメントの更新を必ず含めることをレビュー条件にし、CI ではドキュメント内のコマンドやリンクの整合性を機械的にチェックしています。

この運用で実感している効果は主に 3 つです。1 つ目は、AI が出すコードの初期品質が上がること。正しい一次情報を渡せるため、的外れな実装による手戻りが目に見えて減ります。2 つ目は、引き継ぎが速くなること。新しいメンバーや別の AI エージェントが入っても、ドキュメントから前提を素早く把握できます。3 つ目は、保守時の事故が減ること。制約が文書化されているため、AI に改修を任せても暗黙のルールを踏み抜きにくくなります。

特別なツールが必要なわけではありません。Markdown のドキュメントを正しく構造化し、更新を実装と同じ変更単位に縛り、CI で整合性を見る。この地味な運用の積み重ねが、AI 駆動開発の速度と品質を底支えします。ドキュメント駆動開発をどこから始めればよいか、自社の体制でどう回せばよいかは、プロジェクトの状況によって最適解が変わります。FIXIT の AI 駆動開発サービス では、ドキュメント基盤の設計から CI への組み込みまで含めて伴走しています。

まとめ

ドキュメント駆動開発は、ドキュメントを実装より先に置き、AI と人間が同じ一次情報を見て、実装が変わったらドキュメントも同じ変更単位で更新し続ける運用です。AI が暗黙の文脈を持たないからこそ、正しいドキュメントは最も効く燃料になり、古いドキュメントは最も危険な誤情報になります。CLAUDE.md を目次に、spec で何を作るかを定義し、ADR で判断を残し、README で地図を示す。そして更新フローと CI チェックで陳腐化を仕組みとして止める。この型を持てば、仕様と実装の乖離を防ぎながら、AI 駆動開発を長期にわたって安全に回せます。

自社のプロジェクトでドキュメント駆動の運用をどう設計し、AI 駆動開発をどう進めればよいか迷っている方は、AI 駆動開発の進め方を相談する からお気軽にお問い合わせください。現状の体制に合わせた具体的な進め方を一緒に整理します。