Agent-Nativeドキュメントエンジニアリング：AI Coding Agent駆動開発の文書体系設計ガイド

「チームメンバー」がAI coding agentなら、文書はもはや「人が読む参考資料」ではなく、システム全体を操作するインターフェースです。その品質がagentの出力品質を直接左右します。

はじめに：「良い文書」の定義が書き換えられている理由

2025年以前、プロジェクト文書の読者は人間でした。READMEの品質が多少低くても、経験豊富なエンジニアなら直感を頼りにプロジェクトを動かせました。

2025年8月、OpenAIはCodex CLIのためにAGENTS.md規約を作りました。AI coding agentへ向けてプロジェクトの指針を記す専用ファイルです。数か月のうちに、GitHub Copilot、Cursor、Windsurf、Google Jules、Gemini CLI、Aider、Blockのgooseなど、主要なAIコーディングツールがすべてこの形式へ対応しました。AnthropicのClaude Codeも、同じ考え方のCLAUDE.mdを採用しています。2025年12月にはLinux FoundationがAgentic AI Foundation（AAIF）を設立し、AGENTS.md、AnthropicのMCP、Blockのgooseを三つの創設プロジェクトとしました。

2026年3月時点で、60,000件を超える公開リポジトリがAGENTS.mdを含んでいました。詳細なAGENTS.mdを持つプロジェクトでは、agentが生むbugが平均35〜55%減り、AIコーディングツールのcontext設定時間も20〜40分から2分未満へ短縮されました。

これらの数字が示す事実は明確です。AI agent駆動開発において、文書は付属品ではなく基盤です。

この記事では第一原理から出発し、AI coding agentがプロジェクト開発を担う場合に、どの文書を作り、どう書き、どう構成すべきか、そしてその理由を説明します。

1. Agent-Native文書とは何か

1.1 「人が読むため」から「agentが実行するため」へ

従来の文書は、読者が背景知識と判断力を持ち、曖昧な情報から正しい行動を推測できることを暗黙に前提とします。

Agent-native文書の前提はまったく異なります。読者に背景知識も、文書をまたいだ推測能力もない一方、見た内容には厳密に従って行動すると考えます。

そのため、agent-native文書にはいくつかの中核的な特徴があります。

暗黙より明示。 人間のエンジニアなら「テストを実行する」と読めばnpm testかpytestかを判断できますが、agentには分かりません。agent-native文書は、すべてのflagと引数を含む正確なコマンドを示す必要があります。AGENTS.mdの公式ベストプラクティスが繰り返し強調する第一原則も、曖昧な指示ではなく正確なコマンドを示すことです。

提案より制約。 「コードをできるだけきれいに保つ」は人間には妥当な指針でも、agentには無効なノイズです。agent-native文書では、柔らかい提案を「すべての関数で循環的複雑度を10以下にする」「.envファイルを絶対にコミットしない」「エラー処理には独自例外classを使い、裸のExceptionを使わない」といった強制的な制約へ置き換えます。

叙述より構造化。 Agentが消費するのは「読書時間」ではなくtokenです。流れるような段落より、階層が明確なリストのほうが効率的です。ただし、すべてをリストへ変えるという意味ではありません。各情報層に明確な場所、形式、参照方法を用意するという意味です。

プログラムで解析可能。 agent-native文書には、agentが判断に使えるmetadataを含める必要があります。文書冒頭のfrontmatter（status: active）、標準化した参照形式（[SOURCE: architecture-v0.1.md#data-model]）、状態マーカー（superseded_by: architecture-v0.2.md）などです。

1.2 READMEを置き換えるのではなく、階層として補う

AGENTS.mdがREADME.mdを置き換えるという誤解がよくあります。実際には、それぞれ異なる読者へ向けたものです。

  • README.md — 人間向け。プロジェクト概要、クイックスタート、貢献ガイド。
  • AGENTS.md / CLAUDE.md — AI agent向け。行動制約、ビルドコマンド、コード規約、ワークフロー規則。
  • プロジェクト文書体系（PRD、Architecture、Specなど）— 人間とagentの双方が読む。製品判断、技術的な真源、設計案。

三層はそれぞれ責務を持ち、どれも欠かせません。

2. Coding Agentの動作において文書が実際に果たす役割

文書が重要な理由を理解するには、まずAI coding agentの動作方法を理解する必要があります。

2.1 Agentの実行ループ

OpenAI Codexを例にすると、agentの典型的な流れは次のとおりです。

  1. 起動時にAGENTS.mdを読む — Codexはプロジェクトルートから開始し、ディレクトリツリーを下りながらすべてのAGENTS.mdを探し、一つの指示チェーンへ連結します。この指示チェーンはセッション全体で有効です。
  2. タスク指示を受け取る — ユーザーのpromptです。
  3. 計画する — 指示チェーンとタスク説明を基に、どのファイルを読み、どの操作を行うかを決めます。
  4. ツール呼び出しのループ — ファイルの読み書き、コマンド実行、結果確認を、タスク完了まで繰り返します。
  5. 結果を返す — コードの提出、レポート生成などです。

文書は、このループのすべての段階へ影響します。

2.2 各段階における文書の具体的な役割

System Promptの延長。 AGENTS.mdの内容は、本質的にagentのsystem promptへ注入されます。このプロジェクトでagentが「誰」であり、「どう働き」、「何を絶対にしてはいけないか」を定義します。AnthropicのClaude Codeベストプラクティスは、コード自体から推測できない永続的なcontextをAGENTS.mdまたはCLAUDE.mdへ記すことを推奨しています。

タスクの制約境界。 agentが「ユーザー認証を実装する」という曖昧な指示を受けたとき、業務範囲を定義するPRD、技術選択を定義するArchitecture、インターフェースの詳細を定義するSpecがなければ、推測するしかありません。これがAddy Osmaniの言う「mind reading」の問題です。Spec-Driven Developmentの中心的な洞察は、agentがpattern completionには強い一方、明示されていない要件の推測には弱いことです。

セッションをまたぐ記憶の橋。 Agentにはセッション間の記憶がありません。昨日の会話contextは今日には消えています。リポジトリへ永続化したPRD、Architecture、Specがagentの「長期記憶」です。新しいセッションの開始時に文書を読めば、「記憶を回復」できます。Claude Codeのベストプラクティスが、あるセッションでSPEC.mdを作り、別の新しいセッションで実行することを勧める理由でもあります。新しいセッションにはきれいなcontextがあり、書面のspecを参照できます。

真源の仲裁者。 コードコメントが「PostgreSQLを使う」と言い、Architecture文書が「SQLiteを使う」と言う場合、agentはどちらを選ぶべきでしょうか。明確なsingle source of truthの規則がなければ、無作為に選ぶ可能性があります。文書のdriftがagentの一貫しない行動を生む根本原因です。

3. 「良いコードを書くこと」より「正しい文書を書くこと」が重要な理由

3.1 Context Engineeringの視点

Anthropicは2025年、Context EngineeringをPrompt Engineeringの自然な進化として正式に定義しました。prompt engineeringは指示の表現を最適化し、context engineeringは推論時にモデルが見る情報全体を最適化します。

Manusチームはagentフレームワークを四度作り直した末、KV-cacheのヒット率が、本番AI agentで最も重要な単一指標である という結論へ至りました。遅延とコストへ直接影響します。すべての情報を一つの大きなファイルへ入れるか、階層化して必要なときに読み込むかという文書の構成方法が、この指標を直接左右します。

LangChainチームは、context engineeringを四つの操作へ整理しています。Writeは情報をcontext windowの外へ書いて保存すること、Selectは関連情報をcontext windowへ取り込むこと、Compressはタスク完了に必要なtokenだけを残すこと、Isolateはcontextを異なるagentや部分タスクへ分離することです。

四つの操作はすべて文書設計へ直接関係します。

  • Write — 設計判断をArchitectureへ、feature設計をSpecへ記録し、会話履歴へ残さない
  • Select — 文書の階層化と参照機構で、現在のタスクに関係する文書だけをagentへ読み込ませる
  • Compress — 文書自体を十分に簡潔にする。500行より150行のAGENTS.mdが効果的
  • Isolate — 文書を分割し、各sub-agentに必要なcontextだけを見せる

3.2 Stanfordの研究による警告

StanfordとUC Berkeleyの研究は、モデルが大きなcontext windowへの対応をうたっていても、token数が約32,000を超えると正確性が下がり始めることを示しました。これが「lost-in-the-middle」効果です。モデルはcontextの冒頭と末尾へ集中し、中央の情報を見落としやすくなります。

つまり、すべての文書内容を一つの巨大なAGENTS.mdへ詰め込むことはアンチパターンです。 情報は階層化し、必要に応じて、段階的に公開する必要があります。

3.3 Progressive Disclosure：段階的な情報公開

HumanLayerチームはCLAUDE.mdのベストプラクティスで、Progressive Disclosure（段階的な情報公開） という重要な原則を示しました。

中心となる考え方は、AGENTS.mdでagentが必要とする可能性のあるすべての情報を伝えるのではなく、情報を見つける方法 を伝え、必要になったときだけ読ませることです。

# AGENTS.md内
## 文書インデックス
- ビルドとテストの手順：agent_docs/building_the_project.mdを参照
- コード規約：agent_docs/code_conventions.mdを参照
- データベースschema：agent_docs/database_schema.mdを参照
- サービス間通信パターン：agent_docs/service_communication_patterns.mdを参照

タスクを始める前に、上記のどの文書が現在のタスクに関係するか判断し、変更前に読んでください。

このパターンは、次のすべてを満たします。

  • tokenの節約 — 関係のない文書を読み込まない
  • context windowの占有を最小化 — 現在のタスクに必要な情報だけをcontextへ入れる
  • Agentの正確な行動 — 十分なcontextを持って作業を始める
  • 人間による保守性 — 各文書の責務が一つで、変更がほかの文書へ波及しない

4. AI Coding Agentだけで駆動するプロジェクトに必要な文書

GitHub Spec Kit、Amazon Kiro、BMAD-METHODなどのSpec-Driven Developmentの実践、Anthropicのcontext engineeringガイド、コミュニティの広い共通認識に基づくと、agent-nativeプロジェクトには次の文書階層が必要です。

4.1 AGENTS.md：Agentの行動OS

責務： agentの立場、行動制約、作業規則を定義します。agentがプロジェクトへ入るとき、最初に読むファイルです。

含めるもの：

  • すべてのflagを含む正確なbuild、test、lintコマンド
  • コードスタイル規則。自然言語よりコード例を推奨
  • 「絶対にしない」「必ず行う」といった強制的な制約
  • 他文書のパスと用途説明を示す文書インデックス
  • commit規約
  • セキュリティ境界

含めないもの：

  • 製品要件。PRDの責務です
  • システムアーキテクチャの詳細。Architectureの責務です
  • Feature設計。Specの責務です

ベストプラクティス： 150行以内に収めます。超える場合は子文書へ分割し、AGENTS.mdにはインデックスだけを残します。frontier thinking LLMが安定して従える指示は約150〜200件で、それを超えると遵守率が下がり始めるという研究があります。

4.2 PRD：製品要件文書

責務： 「何を作るか」と「なぜ作るか」を定義します。

agentにとっての役割： featureが範囲内か、境界事例を扱う必要があるかを判断するとき、PRDが最終的な仲裁者です。PRDがなければagentは製品判断を自由に行いますが、通常それは望ましくありません。

含めるもの：

  • 製品目標と対象ユーザー
  • 業務範囲とnon-goals。non-goalsはagentが独断で機能を追加することを防ぐため、特に重要です
  • ページと機能の範囲
  • 業務規則と受け入れ基準

含めないもの： class名、table構造、API signatureなど、あらゆる技術実装の詳細。

4.3 Architecture：システムアーキテクチャ文書

責務： 技術選択、システム境界、データモデル、中核protocolなど、システム全体の技術的な真源を定義します。

agentにとっての役割： 技術判断の錨です。データベースの選択、API設計形式、モジュール境界を決めるとき、Architectureが権威ある情報源です。

含めるもの：

  • 技術スタックと選択理由
  • システム境界とモジュール分割
  • 中核データモデル
  • 「すべてのAPIを冪等にする」などの全体制約
  • 現在の段階における実装状態。「実装済み / この段階で必須 / 延期」

含めないもの： 特定featureの段階的な実装計画。

4.4 Execution Spec：機能設計文書

責務： 「PRDとArchitectureの制約下で、具体的なfeatureをどう設計するか」へ答えます。

agentにとっての役割： feature実装前の「設計図」です。Google ChromeチームのAddy OsmaniはO’Reillyの記事で、spec-driven workflowではspecが実装、テスト、タスク分解を駆動し、specが検証されるまでコーディングへ進むべきではないと強調しています。

ThoughtworksのTechnology Radarチームは、specificationが単なるPRDではないと指摘しています。入出力の対応、事前・事後条件、不変条件、制約、interface型、統合契約、状態機械など、対象ソフトウェアの外部動作を明示的に定義すべきです。

含めるもの：

  • featureの目標と受け入れ基準
  • データフロー、状態機械、エラー処理戦略
  • 他モジュールとのinterface定義
  • non-goals。このfeatureが行わないこと

含めないもの： ファイルごとの変更一覧。Planの責務です。

4.5 Execution Plan：実装計画

責務： 確認済みのSpecを実行可能な段階の列へ分解します。

agentにとっての役割： 変更するファイル、順序、各段階の検証方法を示すタスク一覧です。GitHub Spec Kitの/tasksコマンドは、本質的にこの層の文書を生成します。

含めるもの：

  • 順序づけた実装手順
  • 各手順に関係するファイル
  • 各手順の検証方法。テストコマンドと期待出力
  • 並列化の提案
  • Commitの分割案

含めないもの： 設計判断の導出過程。Specに記します。

4.6 Runbook：操作手順書

責務： 「問題が起きたときにどう処理するか」「依存関係をどう接続するか」へ答えます。

agentにとっての役割： 環境設定、外部サービスへの接続、デプロイ問題の診断で使う操作ガイドです。

4.7 Archive：アーカイブ

責務： 完了または置き換えられた文書を保存し、判断の履歴を追跡可能にします。

agentにとっての役割： アーカイブ文書はstatus: archivedと明示しなければなりません。そうしなければagentが古い設計を現在の真源と見なして実行する可能性があります。

5. 文書を最も効率よく構成する方法

agent-nativeの文脈での「効率」には、正確な行動、token節約、context window占有の最小化、人間の可読性、保守性という五つの側面があります。以下の構成原則は、この五側面のバランスを取ります。

5.1 Single Source of Truth（単一真源）

規則：各種類の情報は、一つの階層だけを最終的な真源とします。

情報の種類真源となる階層
製品範囲、業務目標PRD
全体の技術制約、システム境界Architecture
一つのfeatureの設計と受け入れExecution Spec
タスク分解と実装順序Execution Plan
環境設定とトラブルシューティングRunbook

agentにとって特に重要な理由： agentには、人間が暗黙に行う「こちらよりあちらを優先する」という判断力がありません。同じ内容をArchitectureとSpecの両方へ異なる表現で書くと、どちらが新しいか判断できません。

運用方法： 階層をまたぐ参照では、複製せずlinkだけを使います。標準化した参照形式を使います。

[SOURCE: architecture-v0.1.md#data-model]

5.2 情報の流れと競合解決

PRD → Architecture → Spec → Plan → Code
  • 下流は上流に従わなければなりません。
  • 実装中に上流文書の誤りが分かった場合、先に上流を更新し、その後に実装を続けます。
  • 競合解決の優先順位：PRD > Architecture > Spec > Plan

「先に書き戻してから続ける」規則が重要な理由： agentが実装中にSpecのinterface定義が成立しないと気づき、コードだけで回避すると、Specは「古い虚偽」になります。次に読むagentや人間は誤った判断をします。実装を続ける前に文書を書き戻すことが、体系の一貫性を保つ唯一の方法です。

5.3 Frontmatterメタデータ

各文書の冒頭には、プログラムで解析できるmetadataを含めます。

---
status: active       # active | superseded | archived
version: "0.1"       # PRD/Architectureのみ
superseded_by: ""    # この文書を置き換える文書
date: "2026-03-29"
---

五つの側面への貢献：

  • 正確な行動： agentがstatus: supersededを見つけると、superseded_byが示す新しい文書へ移動
  • token節約： 全文を読まず、文書が有効か判断可能
  • 人間の可読性： 文書を開いてすぐ状態を確認可能
  • 保守性： アーカイブ時には二つのfieldだけを変更

5.4 命名規約

PRD:           prd-v{major.minor}.md
Architecture:  architecture-v{major.minor}.md
Spec:          YYYY-MM-DD-<topic>-design.md
Plan:          YYYY-MM-DD-<topic>-plan.md
Runbook:       <topic>-setup.md / <topic>-runbook.md

重要な詳細： Specは-design.md、Planは-plan.mdで終わります。装飾ではなく、agentがファイル名だけで文書種別を区別するための仕組みです。

5.5 ディレクトリ構成

project-root/
├── AGENTS.md                          # Agentの入口
├── docs/
│   ├── DOCUMENT-STANDARD.md           # 文書規約
│   ├── prd-v0.1.md
│   ├── architecture-v0.1.md
│   ├── execution/
│   │   ├── specs/                     # 有効なfeature設計
│   │   └── plans/                     # 有効な実装計画
│   ├── runbooks/                      # 操作手順書
│   └── archive/                       # アーカイブ

設計理由：

  • SpecとPlanをexecution/配下へ置き、PRD、Architectureなど安定した文書から物理的に分離
  • agentがディレクトリ位置から文書のライフサイクル特性を判断可能
  • アーカイブ文書をarchive/へ集約し、各所へ散在させない

5.6 記述の境界——重複を能動的に避ける

記述中の文書含めないもの
PRDデータベースtable、class名、API実装の詳細
Architectureファイルごとの変更手順、タスク順序
Spec製品目標の全文。PRDへlink
Plan設計判断の導出。Specへlink
RunbookFeatureが存在すべきかという議論

重複テスト： 各段落を書く前に「この情報は別の文書にすでに存在するか」と確認します。存在するなら複製せず、linkします。

6. 実践的な提案

6.1 Spec-Driven Developmentの最小ワークフロー

2025〜2026年に、GitHub、Thoughtworks、Googleのエンジニアは、共通するagent協働の流れへ収束しました。

  1. Specify — PRDとArchitectureの制約下でSpecを書く
  2. Plan — agentにSpecから実装計画を生成させ、人間がreviewする
  3. Implement — AgentがPlanに従って段階的に実装し、各段階を個別にテスト可能にする
  4. Verify — すべてが終わってからではなく、各段階の完了後に検証する

重要なのは、Specを検証するまでコーディングへ進まないこと です。このゲートは、動くように見えても検証に耐えない「砂上の楼閣のコード」をagentに作らせない、最も効果的な方法です。

6.2 AGENTS.mdの黄金律

AGENTS.mdの公式文書、AnthropicのCLAUDE.mdガイド、コミュニティの実践をまとめると、次の原則になります。

コード例一つは自然言語三段落に勝ります。 正しいpatternと反面例を示し、agentに例から規則を推測させるほうが、コードスタイルを英語で説明するより効果的です。

三段階の制約体系を使います。

  • MUST / NEVER — 強制的な制約。違反はエラー
  • SHOULD / PREFER — 強い推奨。妥当な理由があれば外れてよい
  • MAY / CONSIDER — 任意の提案

各行について、「この行がなければagentは間違えるか」と問います。 agentが自力で正しくできることをAGENTS.mdへ書くのはノイズです。不要な指示は、真に重要な指示を薄めます。

6.3 現実的な文書保守戦略

文書の最大の敵は、書けないことではなく、書いた後に徐々に腐るdocumentation rotです。実行可能な戦略をいくつか挙げます。

文書をコードとして管理します。 Gitへcommitし、code reviewを行い、PR内で変更します。バージョン管理によって、いつでもgit diffで文書の変化を確認できます。

Feature完了時のアーカイブ規律。 featureが終わるたびに、対応するSpecとPlanをアーカイブすべきか確認します。アーカイブしなければ、次のagentがdocs/execution/specs/をscanしたとき、完了済みの古い設計を大量に読み、tokenを浪費し、混乱するリスクが増えます。

定期監査。 定期的にagentへdocs/をscanさせ、frontmatterのない文書、更新が必要な可能性のあるstatus、階層間で内容が混在している文書を示す監査reportを作らせます。これ自体がagentに適したタスクです。

7. 最後に：文書はAgent時代の「Infrastructure as Code」

ソフトウェアエンジニアリングの歴史では、パラダイムが変わるたびに「中核的な成果物」が再定義されてきました。

  • ウォーターフォール時代の中核成果物は要件仕様書
  • アジャイル時代は動くソフトウェア
  • DevOps時代はInfrastructure as Code
  • Agent時代はspecificationそのものが中核成果物になりつつある

ThoughtworksのTechnology Radarチームは、Spec-Driven Developmentを検討する中で、specificationとcodeのどちらがソフトウェア開発の最終成果物なのかという未解決の問いを示しました。答えによって、ワークフローと開発実践はまったく異なります。

最終的な答えが何であれ、一点は明確です。agent駆動開発では、文書品質の上限がコード品質の上限を決めます。 Agentが生成できるのは理解したものだけであり、その理解は渡された文書から得られます。

良い文書を書くことが、良いコードを書く前提です。

参考資料：

  • AGENTS.md公式仕様（agents.md）
  • OpenAI Codex公式文書 — Custom instructions with AGENTS.md
  • Anthropic — Effective context engineering for AI agents
  • Anthropic — Claude Code Best Practices
  • Addy Osmani — How to write a good spec for AI agents（O’Reilly Radar, 2026）
  • Thoughtworks — Spec-driven development: Unpacking one of 2025’s key new practices
  • GitHub Blog — Spec-driven development with AI
  • Manus — Context Engineering for AI Agents: Lessons from Building Manus
  • LangChain — Context Engineering for Agents
  • Martin Fowler / Thoughtworks — Context Engineering for Coding Agents
  • HumanLayer — Writing a good CLAUDE.md
  • Particula Tech — AGENTS.md Explained: The File That Makes AI Coding Agents Useful