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 基金会成立了 Agentic AI Foundation（AAIF），将 AGENTS.md 与 Anthropic 的 MCP、Block 的 goose 一起列为三个创始项目。

截至 2026 年 3 月，超过 60,000 个公开仓库包含 AGENTS.md 文件。拥有详细 AGENTS.md 的项目，agent 产生的 bug 平均减少 35-55%。将 AI 编码工具的上下文配置时间从 20-40 分钟压缩到 2 分钟以内。

这些数字揭示了一个事实：在 AI agent 驱动的开发中，文档不是附属品，而是基础设施。

本文将从第一性原理出发，讲清楚在 AI coding agent 驱动项目开发时，应该写什么文档、怎么写、怎么组织，以及背后的原因。

一、什么是 Agent-Native 文档

1.1 从"写给人看"到"写给 agent 执行"

传统文档的隐含假设是：读者有背景知识、有判断力、能在模糊信息中推断出正确行为。

Agent-native 文档的隐含假设完全不同：读者没有背景知识，没有跨文档的推断能力，但会严格按照看到的内容行动。

这意味着 agent-native 文档有几个核心特征：

显式优于隐式。 人类工程师看到"运行测试"就知道该用 npm test 还是 pytest，agent 不知道。agent-native 文档必须给出确切的命令，包括所有 flags 和参数。AGENTS.md 官方最佳实践中反复强调的第一条就是：给出精确命令，不要给模糊指令。

约束优于建议。 “尽量保持代码整洁"对人类是合理的指导，对 agent 是无效噪音。agent-native 文档用硬约束替代软建议：“所有函数的圈复杂度不超过 10”，“永远不要提交 .env 文件”，“错误处理使用自定义异常类，不用裸 Exception”。

结构化优于叙事化。 Agent 消耗的不是"阅读时间"而是 token。一段流畅的段落对 agent 来说不如一个分层清晰的列表高效。但这不意味着把所有东西都变成列表——而是每一层信息都有明确的位置、明确的格式、明确的引用方式。

可程序化解析。 Agent-native 文档需要包含 agent 可以用来做判断的元数据。比如文档头部的 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 共同阅读。产品决策、技术真源、设计方案。

这三层各有职责，缺一不可。

二、文档在 Coding Agent 运行中的实际作用

要理解文档为什么重要，先要理解 AI coding agent 的工作方式。

2.1 Agent 的执行循环

以 OpenAI Codex 为例，agent 的典型执行流程是：

  1. 启动时读取 AGENTS.md — Codex 从项目根目录开始，沿目录树向下查找所有 AGENTS.md 文件，将它们拼接成一个指令链。这个指令链在整个会话中持续生效。
  2. 接收任务指令 — 来自用户的 prompt。
  3. 规划 — agent 根据指令链 + 任务描述，决定要读哪些文件、执行什么操作。
  4. 工具调用循环 — 读文件、写文件、执行命令、检查结果，循环直到任务完成。
  5. 输出结果 — 提交代码、生成报告等。

文档在这个循环中的作用体现在每一步：

2.2 文档在各环节的具体作用

作为 System Prompt 的延伸。 AGENTS.md 的内容本质上是被注入到 agent 的 system prompt 中的。它定义了 agent 在这个项目里"是谁”、“怎么工作”、“哪些事绝对不能做”。Anthropic 在 Claude Code 的最佳实践中建议，AGENTS.md / CLAUDE.md 应该包含 agent 无法从代码本身推断出的持久化上下文。

作为任务的约束边界。 当 agent 收到"实现用户认证"这样的模糊指令时，如果没有 PRD 定义业务范围、没有 Architecture 定义技术选型、没有 Spec 定义接口细节，agent 只能靠猜——这就是 Addy Osmani 所说的"mind reading"问题。Spec-driven development 的核心洞见就在于：agent 擅长 pattern completion，但不擅长猜测未说明的需求。

作为跨会话的记忆桥梁。 Agent 没有跨会话记忆。昨天的对话上下文，今天全部清零。持久化在仓库中的文档——PRD、Architecture、Spec——就是 agent 的"长期记忆"。每次新会话开始时，agent 读取这些文档，就相当于"恢复记忆"。这就是为什么 Claude Code 最佳实践建议：先用一个会话让 agent 生成 SPEC.md，然后开一个全新会话去执行——新会话有干净的 context，且有一份书面 spec 可以参考。

作为真源的仲裁者。 当代码里的注释说"使用 PostgreSQL"，但 Architecture 文档说"使用 SQLite"，agent 怎么判断哪个对？如果没有明确的真源规则（single source of truth），agent 会随机选择——这就是文档漂移导致 agent 行为不一致的根本原因。

三、为什么"写对文档"比"写好代码"更重要

3.1 从 Context Engineering 的视角理解

Anthropic 在 2025 年正式将 Context Engineering 定义为 Prompt Engineering 的自然演进：prompt engineering 优化的是指令的措辞，而 context engineering 优化的是模型在推理时看到的全部信息集合。

Manus 团队（AI agent 公司）在重建了四次 agent 框架后得出一个核心结论：KV-cache 命中率是生产级 AI agent 最重要的单一指标。 它直接影响延迟和成本。而文档的组织方式——是把所有信息塞进一个大文件，还是分层按需加载——直接决定了这个指标。

LangChain 团队将 context engineering 归纳为四个操作：Write（将信息写到 context window 之外保存）、Select（将相关信息拉入 context window）、Compress（只保留完成任务所需的 token）、Isolate（将上下文拆分到不同的 agent/子任务中）。

这四个操作每一个都与文档设计直接相关：

  • Write — 将设计决策写入 Architecture 文档，将 feature 设计写入 Spec，而不是留在聊天历史里
  • Select — 通过文档分层和引用机制，让 agent 只加载当前任务相关的文档
  • Compress — 文档本身要足够精炼，一份 150 行的 AGENTS.md 比一份 500 行的更有效
  • Isolate — 通过文档拆分，让不同的 sub-agent 只看到自己需要的上下文

3.2 Stanford 研究的警示

Stanford 和 UC Berkeley 的研究发现，即使模型声称支持很大的 context window，在 token 数超过约 32,000 时，模型的准确率就开始下降——这就是"lost-in-the-middle"效应：模型聚焦于上下文的开头和结尾，中间的信息容易被忽略。

这意味着：把所有文档内容塞进一个巨大的 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 精准行动 — agent 带着充分的上下文开始工作
  • 人类可维护 — 每个文档职责单一，修改不会牵连其他文档

四、一个完全由 AI Coding Agent 驱动的项目需要哪些文档

基于 Spec-driven development（GitHub Spec Kit、Amazon Kiro、BMAD-METHOD）的实践、Anthropic 的 context engineering 指南、以及社区的广泛共识，一个 agent-native 项目应该包含以下文档层级：

4.1 AGENTS.md — Agent 的行为操作系统

职责： 定义 agent 的身份、行为约束和工作规则。它是 agent 进入项目时第一个读的文件。

应该包含：

  • 精确的构建、测试、lint 命令（包含所有 flags）
  • 代码风格规则（最好用代码示例而非自然语言描述）
  • 硬约束（“永远不要…"、“必须…"）
  • 文档索引（指向其他文档的路径和用途描述）
  • commit 规范
  • 安全边界

不应该包含：

  • 产品需求（那是 PRD 的事）
  • 系统架构细节（那是 Architecture 的事）
  • Feature 设计方案（那是 Spec 的事）

最佳实践： 控制在 150 行以内。超过 150 行就应该拆分到子文档，在 AGENTS.md 里只留索引。研究表明，frontier thinking LLM 能稳定遵循约 150-200 条指令，超过这个数量合规率开始下降。

4.2 PRD — 产品需求文档

职责： 定义"做什么"和"为什么做”。

对 agent 的作用： 当 agent 需要判断一个 feature 是否在范围内、一个边界情况是否需要处理时，PRD 是最终仲裁者。没有 PRD 的项目，agent 会在产品决策上自由发挥——这通常不是你想要的。

应该包含：

  • 产品目标、目标用户
  • 业务范围和非目标（non-goals 对 agent 极其重要——它能有效阻止 agent “自作主张"添加功能）
  • 页面/功能范围
  • 业务规则和验收标准

不应该包含： 类名、表结构、API 签名——任何技术实现细节。

4.3 Architecture — 系统架构文档

职责： 定义系统级技术真源——技术选型、系统边界、数据模型、核心协议。

对 agent 的作用： 这是 agent 做技术决策的锚点。当 agent 要选择数据库、决定 API 设计风格、判断一个模块的边界时，Architecture 是权威来源。

应该包含：

  • 技术栈和选型理由
  • 系统边界和模块划分
  • 核心数据模型
  • 全局约束（如"所有 API 必须幂等”）
  • 当前阶段的实现状态（“已实现 / 本阶段必须实现 / 延后处理”）

不应该包含： 某个具体 feature 的逐步实现计划。

4.4 Execution Spec — 特性设计文档

职责： 回答"在 PRD 和 Architecture 的约束下，这个具体 feature 怎么设计”。

对 agent 的作用： Spec 是 agent 实现一个 feature 前的"设计图纸"。Addy Osmani（Google Chrome 团队）在 O’Reilly 发表的文章中强调：在 spec-driven workflow 中，spec 驱动了实现、测试和任务拆分——在 spec 被验证之前不应该进入编码阶段。

Thoughtworks 的技术雷达团队进一步指出：specification 不仅仅是 PRD——它应该显式定义目标软件的外部行为，包括输入/输出映射、前置/后置条件、不变式、约束、接口类型、集成契约和状态机。

应该包含：

  • 这个 feature 的目标和验收标准
  • 数据流、状态机、错误处理策略
  • 与其他模块的接口定义
  • 非目标（这个 feature 不做什么）

不应该包含： 逐文件的修改清单（那是 Plan 的事）。

4.5 Execution Plan — 实施计划

职责： 将已确认的 Spec 拆解为可执行的步骤序列。

对 agent 的作用： Plan 是 agent 的任务清单——改哪些文件、按什么顺序改、每步怎么验证。GitHub Spec Kit 的 /tasks 命令本质上就是在生成这个层级的文档。

应该包含：

  • 有序的实施步骤
  • 每步涉及的文件
  • 每步的验证方式（测试命令、预期输出）
  • 并行化建议
  • Commit 切分建议

不应该包含： 设计决策的推导过程（那在 Spec 里）。

4.6 Runbook — 操作手册

职责： 回答"出了问题怎么处理"或"某项依赖怎么接入"。

对 agent 的作用： 当 agent 需要配置环境、连接外部服务、排查部署问题时，Runbook 是操作指南。

4.7 Archive — 归档

职责： 保存已完成或已被替代的文档，保持决策历史可追溯。

对 agent 的作用： 归档文档必须明确标记为 status: archived，否则 agent 可能把旧的设计方案当成当前真源来执行。

五、如何组织文档才最高效

“高效"在 agent-native 语境下有五个维度：精准行动、节省 token、最小 context window 占用、人类可读、易于维护。以下每个组织原则都在这五个维度上做了权衡。

5.1 单一真源原则（Single Source of Truth）

规则：每类信息只能在一个层级中作为最终真源存在。

信息类别真源层级
产品范围、业务目标PRD
全局技术约束、系统边界Architecture
单 feature 设计和验收Execution Spec
任务拆解和实施顺序Execution Plan
环境配置和排障操作Runbook

为什么这对 agent 特别重要： Agent 没有人类那种"这里的信息以那边为准"的隐性判断力。如果同一件事在 Architecture 和 Spec 里各写了一遍且措辞不同，agent 无法判断哪个是最新的。

操作方式： 跨层引用时只链接，不复制。使用标准化引用格式：

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

5.2 信息流方向和冲突解决

PRD → Architecture → Spec → Plan → Code
  • 下游必须服从上游
  • 如果实现中发现上游文档有误，先更新上游，再继续实现
  • 冲突解决优先级：PRD > Architecture > Spec > Plan

为什么"先回写再继续"这条规则如此关键： 如果 agent 在实现中发现 Spec 的接口定义行不通，直接在代码里绕过去，那 Spec 就变成了"过时的谎言”。下次另一个 agent（或人类）看到这个 Spec，会做出错误的判断。先回写文档再继续实现，是保持文档体系一致性的唯一方法。

5.3 Frontmatter 元数据

每份文档头部必须包含可程序化解析的元数据：

---
status: active       # active | superseded | archived
version: "0.1"       # 仅 PRD/Architecture 使用
superseded_by: ""    # 被哪份文档替代
date: "2026-03-29"
---

对五个维度的贡献：

  • 精准行动： Agent 遇到 status: superseded 的文档时，自动跳转到 superseded_by 指向的新文档
  • 节省 token： Agent 不需要读完全文才能判断文档是否有效
  • 人类可读： 打开文档第一眼就能看到状态
  • 易于维护： 归档文档时只需改两个字段

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数据库表、类名、API 实现细节
Architecture逐文件修改步骤、任务排序
Spec完整的产品目标（链接到 PRD）
Plan设计决策推导（链接到 Spec）
RunbookFeature 是否应该存在的讨论

重复测试： 写每一段之前问自己：“这个信息是否已经存在于另一份文档中？“如果是，链接它，不要复制。

六、实战建议

6.1 Spec-Driven Development 的最小工作流

GitHub、Thoughtworks、Google 的工程师们在 2025-2026 年间逐渐收敛出一个共识性的 agent 协作工作流：

  1. Specify — 在 PRD 和 Architecture 约束下，编写 Spec
  2. Plan — 让 agent 基于 Spec 生成实施计划，人类审核
  3. Implement — Agent 按 Plan 逐步实现，每步可独立测试
  4. Verify — 每个步骤完成后验证，不是等全部完成再验证

关键在于：在 Spec 被验证之前不进入编码阶段。 这个门控机制是防止 agent 产出"纸牌屋代码”（看起来能跑但经不住审查的代码）的最有效手段。

6.2 AGENTS.md 的黄金法则

基于 AGENTS.md 官方文档、Anthropic 的 CLAUDE.md 指南、以及社区实践总结的写作原则：

一条代码示例胜过三段自然语言描述。 展示正确的 pattern 和反面 pattern，让 agent 从示例中推断规则，比用英文描述代码风格更有效。

使用三级约束体系：

  • MUST / NEVER — 硬约束，违反即错误
  • SHOULD / PREFER — 强建议，有合理原因可偏离
  • MAY / CONSIDER — 可选建议

每一行都问自己：如果没有这行，agent 会犯错吗？ 如果 agent 已经能自行做对的事情，写进 AGENTS.md 就是噪音。每一行多余的指令都在稀释真正重要的指令。

6.3 文档维护的现实策略

文档最大的敌人不是写不出来，而是写完之后逐渐腐烂（documentation rot）。几个实际可行的策略：

把文档当代码管理。 Commit 到 git，做 code review，在 PR 中修改。版本化意味着你随时可以 git diff 看到文档的演进。

Feature 完成后的归档纪律。 每次 feature 完成，检查对应的 Spec 和 Plan 是否应该归档。不归档的结果是：下次 agent 扫描 docs/execution/specs/ 目录时，会看到一堆已完成的旧设计，浪费 token 且增加混淆风险。

定期审计。 每隔一段时间，让 agent 扫描 docs/ 目录，生成一份审计报告——哪些文档缺少 frontmatter、哪些文档的 status 可能需要更新、哪些文档存在跨层内容污染。这本身就是一个适合 agent 执行的任务。

七、写在最后：文档是 Agent 时代的"基础设施代码”

回顾软件工程的历史，每一次范式转移都伴随着"什么是核心产物"的重新定义：

  • 瀑布时代，核心产物是需求规格书
  • 敏捷时代，核心产物是可工作的软件
  • DevOps 时代，核心产物是基础设施即代码
  • Agent 时代，核心产物正在变成 specification 本身

Thoughtworks 的技术雷达团队在审视 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