Agent.md Claude.md 文档的书写规范有很多，今天又更新了一下报告，附带的另两篇文章有具体规范和模板，供参考。

基于真实公开样本、作者复盘、官方机制说明与实证研究整理完成日期：2026-04-18

全文 1.1 万字，注意阅读时间。

0. 执行摘要

这次研究最重要的发现是：真正有效的 Agent 文档，不是“给 AI 看的 README”，而是一个低歧义、可执行、可验证、可维护的运行控制面。

它最核心的机制，不是“讲得多”，而是这五件事：

1. 路由：先告诉 agent 去哪里看，而不是把所有知识堆在一个文件里。
2. 边界：明确哪些不能碰、哪些不能猜、哪些必须先确认。
3. 完成定义：什么算完成，必须跑什么验证，什么证据才算交付。
4. 上下文压缩：只保留高频、稳定、项目特有、跨会话重复有用的信息。
5. 分层：根文档放常驻规则，复杂流程拆到外部 docs、skills、scripts、plans。

最常见但无效的写法，不是“写得差”，而是“写得像样但不产生执行收益”：

• 大段背景介绍、价值观口号、泛化最佳实践
• 没有命令、没有路径、没有验证顺序的抽象要求
• 把低频长流程直接塞进根文档
• 写一堆约束，却没有指出适用范围、优先级、例外条件
• 想用文档替代脚本、CI、权限与工具层面的硬约束

对个人实践最值得立刻采用的建议是：

• 根文档先只写四类东西：项目地图、精确命令、禁区、完成定义
• 对复杂仓库使用根文档路由 + 目录级局部文档
• 长流程不要堆在主文档里，用外部文档承接，再由主文档指过去
• 给文档设置长度预算：根级常驻文档以 80-150 行为宜，>200 行进入警戒，优先拆分
• 每次 agent 或 reviewer 重复犯同一种错，就评估是否应升级为常驻规则
• 把根文档当成活的操作配置，不是一次性写完的宣言

1. 研究范围、样本框架与方法说明

1.1 研究范围

主重点放在工程项目仓库中的常驻 agent 指令文档，也就是 agent 在仓库里会自动读取、影响编码与协作行为的文档。重点覆盖：

• AGENTS.md
• CLAUDE.md
• .github/copilot-instructions.md
• 与上述文件承担同类职责的局部说明文档

次级扩展覆盖：

• 通用任务型 Agent 文档
• 研究/分析型 Agent 文档
• 自动化/工作流型 Agent 文档
• 外部 PLANS.md / runbook / skill 文档等补充形态

1.2 信息源优先级

本研究按以下优先级取材：

1. 真实公开样本
2. 作者自述与实践复盘
3. 社区共识与讨论
4. 官方资料

理由很简单：这项任务研究的不是“工具方推荐你怎么写”，而是“什么写法在真实仓库里长期有效”。官方资料很重要，但更适合说明机制边界，不适合单独拿来下“有效性定论”。

1.3 样本分类方法

为了避免把不同东西混在一起，本研究按“文档作用”而不是“文件名”分类：

1.4 证据分级

强证据

• 真实仓库中的公开文档样本，可看到全文或关键段落
• 能结合仓库结构理解其使用语境
• 有多样本交叉印证
• 或有官方文档明确说明加载机制、优先级、适用边界
• 或有实证研究提供大样本统计支持

中证据

• 有真实样本，但缺少效果复盘
• 或有作者第一手复盘，但样本来自单一团队/单一项目
• 或多个来源方向一致，但缺少因果证明

弱证据

• 模板仓库、纯教程、无实际使用上下文的 gist
• 社区转述、二手总结
• 泛化观点，没有具体样本或机制支撑

1.5 研究方法

本次结论主要来自三类证据的叠加：

1. 真实仓库样本阅读
2. 机制边界核实
3. 跨样本归纳

其中，实证研究 Agent READMEs: An Empirical Study of Context Files for Agentic Coding 提供了一个很有价值的底盘：它分析了 1,925 个仓库中的 2,303 份 agent context files，覆盖 CLAUDE.md、AGENTS.md、copilot-instructions.md。这让我们至少可以知道“大家实际在写什么”“这些文件是静态还是活的”“常见内容结构是什么”，而不是完全凭少量热门样本下判断。

1.6 重要边界与偏差

这份研究有几个必须诚实说明的边界：

• 公开仓库偏差：能看到的样本偏向开源团队、基础设施项目、AI 早期采用者。
• 生态偏差：Claude Code、Codex、Copilot 三个生态的公开样本更多，其他工具相对少。
• 因果证据有限：我们能看到很多“相关性强”的模式，但“某写法必然提升成功率”的因果链条，公开证据仍有限。
• 场景偏差：工程仓库型证据最强，通用任务型、研究型、自动化型更多依赖机制推断与类比归纳。

因此，下面的结论里，我会把“强结论”和“谨慎推断”分开写。

2. 高价值样本地图

2.1 最值得先看的样本

如果你只想先看最有代表性的几份，建议按这个顺序：

1. openai/openai-agents-python/AGENTS.md
2. openai/codex/AGENTS.md
3. langgenius/dify/AGENTS.md + api/AGENTS.md + web/AGENTS.md
4. n8n-io/n8n/AGENTS.md + packages/testing/playwright/AGENTS.md
5. ansible/ansible/AGENTS.md
6. rerun-io/rerun/AGENTS.md

这六组样本基本覆盖了：

• 根文档如何写
• 目录级局部文档如何写
• 高约束仓库怎么表达禁区和验证
• 大型仓库如何做分层
• 多语言/多子系统项目如何做路由

2.2 样本地图

3. 统一总规范：真正有效的 Agent 文档应该怎么写

下面这部分是总纲。每条都尽量给出“规范表述、为什么有效、证据来源、常见误区、短例子”。

3.1 总规范表

3.2 统一原则展开

1. 核心目标原则

根文档最适合承载四类信息：

• agent 先看哪里
• agent 必须遵守什么
• agent 必须运行什么
• agent 什么时候算完成

凡是不直接服务这四件事的内容，都要很谨慎地判断是否常驻。

2. 信息选择原则

应该优先写进常驻 Agent 文档的内容：

• 高频且稳定的命令
• 项目特有、代码里不容易推断出的约定
• 新人和 agent 都容易踩坑的地方
• 风险高、代价高、重复出现过的问题
• 关键入口路径、目录地图、依赖关系
• 完成定义、验收顺序、输出要求

不应该优先写进常驻文档的内容：

• 大段背景介绍
• 会快速过期的流程细节
• 一次性任务说明
• 低频知识百科
• 大量“好好写代码、注意质量”这类泛要求

3. 结构原则

跨样本最稳定的高价值结构通常长这样：

1. 这个仓库/子系统是什么
2. 先读哪里
3. 常用命令
4. 关键约束/禁区
5. 测试与完成定义
6. 指向外部文档或局部文档

这也是实证研究里看到的浅层层级结构背后的合理形态：单一 H1，少量 H2/H3，强调扫描效率。

4. 常驻内容与外部文档分工原则

最稳的分工是：

• 根文档：全局高频规则、路由、禁区、完成定义
• 局部文档：子目录独有规则、专业化流程、局部测试/架构说明
• 外部 docs / runbooks / skills / scripts / PLANS：复杂流程、长步骤、低频但重要的专门知识

这一点有多方支撑：

• Anthropic 文档 明确建议多步流程或局部规则拆到 skills 或 path-scoped rules。
• GitHub Skills 文档 明确建议“简单常驻规则进 instructions，复杂专门任务进 skills”。
• OpenAI 的 PLANS.md 实践 明确展示了复杂长流程应拆成外部 living doc。

5. 规则表达方式原则

好规则通常具备四个特征：

• 短
• 具体
• 有条件
• 可验证

坏规则通常有两个特征：

• 抽象
• 无法判断是否遵守

6. 长度与密度控制原则

强结论是：根文档越长越不一定越好。

• Anthropic 文档 明确建议单个 CLAUDE.md 目标控制在 200 行以内。
• Anthropic 的扩展文档 也明确重复了同一经验法则：CLAUDE.md 超过 200 行，应拆到 rules 或 skills。
• OpenAI 的工程实践复盘 明确说“大而全的 AGENTS.md 会失败”，后来改成“约 100 行左右、主要承担地图作用”的短入口文档。
• 实证研究发现 CLAUDE.md 和 copilot-instructions.md 在公开样本中普遍更长、更难读，而 AGENTS.md 相对更短。

谨慎推断是：

• 短不是目的，高密度才是目的。
• 对大仓库来说，不是把根文档写短就好，而是应该把根文档写成“高压缩索引页”。

6.1 可直接采用的长度预算

下面这组不是跨生态的“硬标准”，而是结合官方建议、公开样本中位数和工程实践后，更适合落地的预算区间：

这组预算背后的逻辑是：

• 根级常驻文档每次都会进入上下文，最应该严格控制体积。
• 目录级文档只在局部生效，可以略长，但仍应保持“当前目录够用即可”。
• SKILL.md 是按需加载，允许比根文档更长，但一旦超过 300 到 400 行，维护难度和重复概率通常会明显上升。

6.2 这些数字的证据等级

需要把“有官方依据的”与“工程上更好用的预算”区分开：

• 强证据：CLAUDE.md 控制在 200 行以内。 来源是 Anthropic 官方文档，适用于 Claude Code 生态。
• 中证据：短 AGENTS.md 更稳，约 100 行左右适合作为地图。 来源是 OpenAI 单团队工程实践复盘，代表性强，但仍属于单组织经验。
• 强证据但偏描述性：公开样本里 AGENTS.md 中位数约 335.5 词，CLAUDE.md 约 485 词，copilot-instructions.md 约 535 词，而且更长文件更难读。 来源是实证研究，但它给的是词数和可读性，不直接给“最佳行数上限”。
• 谨慎推断：根文档 80-150 行、局部文档 40-120 行、SKILL.md 80-220 行，是为了把上面三类证据转成更实用的写作预算。 这部分是研究归纳后的建议，不应伪装成官方硬规范。

6.3 什么时候必须拆

即使还没超过行数警戒线，只要出现下面任一情况，也应该优先拆分：

• 根文档开始承载大量低频长流程
• 同一文档里出现多个子系统的详细规则
• 读者必须滚动很久才能找到当前任务相关内容
• 文档内充满“如果是 A… 如果是 B… 如果是 C…”的分支说明
• 文档已经明显变成 reference manual，而不是入口控制面

7. 路由原则

有效文档会主动减少 agent 的错误搜索成本：

• 根文档按目录/子系统路由
• 告诉 agent 修改某类文件前先读哪里
• 告诉 agent 某些文档是 source of truth

这是大仓库里最容易被低估、但收益极高的一类写法。

8. 边界与禁区设计原则

以下内容很适合明确写死：

• 禁止编辑的生成文件
• 不可绕过的 CI / 审批 / 合规要求
• 不可直接手工操作的部署路径
• 某些目录只读或高风险
• 某类改动必须先计划、先确认、先比对兼容边界

像 ansible/ansible 的 licensing rules、openai/codex 的生成文件和测试约束，都是这类高价值边界。

9. 完成定义设计原则

Agent 文档中最容易缺失、但最关键的一项，是把“完成”说清楚。

高质量完成定义通常包括：

• 需要跑哪些命令
• 命令顺序
• 哪些情况可以跳过
• 需要更新哪些测试/文档/快照
• 需要给出什么交付证据

10. 可执行性原则

所谓“可执行”，至少意味着：

• agent 拿到文档后，不需要大量猜测
• 关键命令可直接运行
• 关键路径可直接定位
• 是否完成可以由命令、输出、文件状态或行为观察判断

11. 可维护性原则

有效文档必须能持续更新，否则会很快变成噪音。实证研究最有价值的发现之一是：这些文件在真实仓库里往往是频繁小步更新的，而不是一写完就不动。

因此，真正可维护的写法往往是：

• 根文档短
• 局部细则下沉
• 每条规则都能解释“为什么还存在”
• 明确区分稳定规则与临时说明

12. 何时拆分为子文档或局部文档

以下任一情况出现，就应该考虑拆分：

• 某规则只对一个目录或一类文件生效
• 某流程超过主文档应有的信息密度
• 某子系统有自己独特的工具链/测试链/架构约束
• 主文档开始出现频繁的 if/else 说明
• 读主文档的人必须滚很久才能找到和当前任务相关的信息

4. 场景化子规范

4.1 工程仓库型 Agent 文档规范

这是证据最强、也最值得重点展开的场景。

4.1.1 仓库级常驻规则怎么写

仓库根文档建议优先包含这些模块：

1. 项目一句话地图
2. 目录/子系统路由
3. 必用命令与工具链
4. 禁区与关键约束
5. 完成定义与验证顺序
6. 外部文档入口

推荐写法：

• api/、web/、packages/testing/ 这类结构明确的仓库，根文档只做总览与路由
• 关键命令尽量用 repo root 可直接运行的形式
• 对“何时用哪个命令”写清条件

不推荐写法：

• 把每个包、每层架构、每项规范都平铺写在根文档
• 只给命令，不说什么时候用
• 只说“看 README / 看 docs”，不说先看哪一个

4.1.2 目录级局部规则怎么写

目录级局部文档最适合写：

• 该目录特有的测试命令
• 该目录特有的架构约束
• 该目录特有的高风险坑点
• 该目录自己的 source of truth 文档

有效方式：

• 根文档先明确“改这里先读这里”
• 局部文档只讲本地差异，不重复根文档的大部分内容
• 局部文档可以更专业、更细，但仍要围绕执行

4.1.3 路由如何设计

推荐路由模式：

• 按目录路由：api/、web/、docs/
• 按任务路由：改 runtime、改 docs、改 snapshots、改 generated code
• 按风险路由：改公共 API、改 schema、改部署、改安全敏感区

写法上，最有效的是一句话就把人带到位：

• “修改 api/ 下代码前，先读 api/AGENTS.md”
• “涉及 overlay 组件时，以 ./docs/overlay-migration.md 为准”
• “大于一小时的复杂实现先用 PLANS.md”

4.1.4 测试/构建/验证要求怎么表达

建议表达成：

• 改什么时跑什么
• 按什么顺序跑
• 哪些情况可以不用跑全量
• 失败后怎么处理

例如：

• “改 Python runtime 代码：make format -> make lint -> make typecheck -> make tests”
• “改 docs-only 内容：可跳过全量测试，但要跑文档校验”

4.1.5 对 agent 修改代码的约束如何表达

高价值约束通常包括：

• 不要改生成文件
• 不要手工部署或绕过既有流程
• 公共接口如何处理兼容性
• 哪类改动必须补测试/快照/文档
• 哪些工具/目录是首选而不是自己另起一套

4.1.6 何时写到 AGENTS.md，何时拆到 docs/workflows/scripts

适合写到 AGENTS.md：

• 高频、稳定、短规则
• 关键入口、常用命令、禁区、完成定义

适合拆出去：

• 超过十几步的流程
• 复杂部署/回滚/事故处理
• 需要脚本才能稳定执行的操作
• 某个子系统专属的详细架构说明

4.1.7 如何兼顾人类可读性

兼顾方式不是“写成面向人类的长文”，而是：

• 标题清晰
• 路由明显
• 规则短句化
• 文档之间职责分明

换句话说，让人类读得懂的最佳方式，通常也是让 agent 更容易执行的方式。

4.2 通用任务型 Agent 文档规范

这类文档不以仓库代码修改为中心，而以任务执行风格为中心。

与总规范一致的部分：

• 仍然需要边界、完成定义、输出格式、升级条件

与工程仓库型不同的部分：

• 更强调角色、目标、输出格式、澄清策略、拒绝条件
• 较少涉及构建命令、目录地图、测试链

最容易犯的错误：

• 角色设定过重，执行约束过弱
• 写很多“你是顶级专家”，但不定义产出格式和证据标准
• 没有说明何时该问、何时该直接做

最适合的组织方式：

1. 角色与任务目标
2. 输入假设与澄清策略
3. 输出结构
4. 边界与禁区
5. 质量标准

4.3 研究/分析型 Agent 文档规范

这类文档的核心，不是代码修改，而是证据质量控制。

与总规范一致的部分：

• 仍然需要路由、边界、完成定义

与其他类型不同的部分：

• 必须明确资料优先级
• 必须明确证据分级
• 必须明确哪些结论可以推断、哪些不能
• 必须明确输出中的不确定性标注方式

最容易犯的错误：

• 只堆资料，不做判断
• 只做观点总结，不追溯原始样本
• 把传播很广当成证据很强
• 不区分“机制说明”和“有效性结论”

最适合的组织方式：

1. 研究目标
2. 样本与信息源范围
3. 证据分级标准
4. 方法与偏差说明
5. 输出结构
6. 结论边界

4.4 自动化/工作流型 Agent 文档规范

这类文档最重视的是可重复运行与失败处理。

与总规范一致的部分：

• 仍然要简洁、可执行、可验证

与其他类型不同的部分：

• 需要明确触发条件
• 需要明确前置条件
• 需要明确副作用与回滚
• 需要明确 idempotency
• 需要明确“什么时候跳过而不执行”

最容易犯的错误：

• 只说做什么，不说什么时候不该做
• 不写失败重试与回滚
• 不写输入、输出、产物位置
• 把人工判断步骤和机器步骤混在一起

最适合的组织方式：

1. 触发条件
2. 输入与前置条件
3. 执行动作
4. 产物与通知
5. 失败处理
6. 回滚/跳过规则

5. 有效与无效写法对照

最容易被过度包装的“伪最佳实践”

1. “根文档越完整越好” 实际上大仓库里更常见的高质量做法是根文档保持短而密，再路由出去。
2. “所有 AI 工具都应该共用一份超大统一文档” 更稳的做法通常是：一个 canonical 文档，加别名、import、symlink，必要时加少量工具特定补充。
3. “把所有流程都写进去，就不需要 scripts/skills/runbooks 了” 现实里恰恰相反。越复杂的流程越应该脱离根文档。
4. “只要加很多规则，agent 就会更稳定” 文档是上下文，不是硬约束。规则多但冲突、模糊、过长，反而会降低遵循度。

6. 模板与示例

下面给出的是可直接改写的短模板，刻意保持“短、准、稳、可执行”。

6.1 工程仓库型基础模板

# AGENTS.md## Repo Map- Backend: `api/`- Frontend: `web/`- Shared docs: `docs/`## Read First- Editing backend code: read `api/AGENTS.md`- Editing frontend code: read `web/AGENTS.md`## Commands- Install: `uv sync`- Lint: `make lint`- Typecheck: `make typecheck`- Tests: `make test`## Rules- Do not edit generated files directly.- Prefer modifying existing files over creating new abstractions.- Add or update tests for behavior changes.## Done- Relevant lint/typecheck/tests pass.- User-facing changes include docs or examples when needed.

6.2 工程仓库型进阶模板

# AGENTS.md## Project Map- `api/`: Python backend. Read `api/AGENTS.md` before changing runtime code.- `web/`: Frontend. Read `web/AGENTS.md` before changing UI, tests, or overlay components.- `docs/`: Human-facing docs and runbooks.## Global Commands- Format: `make format`- Lint: `make lint`- Typecheck: `make typecheck`- Tests: `make test`## Boundaries- Do not edit generated files marked `DO NOT EDIT`.- Do not bypass CI or deployment scripts.- Changes to public APIs require compatibility review and tests.## Completion Rules- Runtime code: run `format -> lint -> typecheck -> tests`- Docs-only changes: run doc validation only- UI-visible changes: update snapshots/examples when applicable## Escalate Before Changing- Public API signatures- Schema / migration shape- Build or deployment pipeline behavior## External Docs- Multi-hour or multi-step work: use `PLANS.md`- Deployment / rollback: `docs/ops/deploy.md`

6.3 通用任务型模板

# Agent Instructions## RoleYou are responsible for solving the task directly, not just describing an approach.## Working Rules- Make reasonable assumptions unless the risk is high.- If a wrong choice is expensive, ask one concise clarifying question.- Prefer concrete outputs over generic advice.## Output- Start with the result.- Keep explanations short unless the user asks for depth.- When unsure, mark uncertainty explicitly.## Boundaries- Do not invent facts.- Do not hide tradeoffs.- Do not present guesses as conclusions.

6.4 研究/分析型模板

# Research Instructions## GoalProduce a source-grounded analysis, not a summary of popular opinions.## Source Priority1. Original samples and primary sources2. Author explanations and postmortems3. Community discussion4. Official docs for mechanism boundaries## Evidence Rules- Label each major conclusion as strong, medium, or weak evidence.- Mark inference separately from direct evidence.- If evidence is insufficient, say so explicitly.## Output- Methods and scope- Sample map- Findings- Counterexamples- Practical recommendations

6.5 自动化/工作流型模板

# Workflow Instructions## TriggerRun when a new release tag is created.## Preconditions- Release notes exist- CI is green- Required secrets are available## Actions1. Build artifacts2. Run release validation3. Publish artifacts4. Post release summary## Failure Handling- If validation fails, stop before publish.- If publish partially succeeds, run rollback guide `docs/ops/release-rollback.md`.## Output- Release URL- Artifact checksums- Validation summary

7. 评估清单与评分框架

7.1 快速体检 Checklist

一份 Agent 文档，如果下面 10 条里做不到 7 条以上，通常就还不算好用：

• 能在 1 到 2 分钟内扫出“先看哪里、先跑什么”
• 有明确的项目地图或任务地图
• 至少给出一组可直接运行的命令
• 明确写出禁区或高风险边界
• 明确写出完成定义
• 区分了常驻规则与外部文档
• 对大仓库使用了路由或局部分层
• 内容以项目特有信息为主，而不是泛化鸡汤
• 和实际工具链一致，没有明显过期
• 能解释为什么这条规则值得长期存在

7.2 系统评分框架

建议按 100 分评估：

评分参考

• 90-100：高可用，适合作为团队常驻规范
• 75-89：总体有效，但还可以进一步压缩与分层
• 60-74：有帮助，但噪音偏多或执行性不足
• 60 以下：更像展示型文档，不像操作型文档

7.3 深度评估时重点看什么

深度评估不要只看“格式全不全”，更要看这些问题：

1. agent 是否会因为这份文档更少走弯路
2. agent 是否更容易判断何时该停、何时该问、何时算完成
3. 文档是否减少了错误搜索、错误修改、错误完工判断
4. 文档是否把真正高代价的坑点覆盖到了
5. 文档是否能在 2 到 4 周后仍保持可维护

8. 持续迭代方法

8.1 新项目第一版怎么建

第一版不要追求完整，先做最小可用版：

1. 写一句话项目地图
2. 列出最常用的安装、测试、验证命令
3. 写 3 到 5 条高价值禁区
4. 写清“什么算完成”
5. 如果是多子系统仓库，先把路由埋好

第一版目标不是“无所不包”，而是让 agent 第一次进仓库时不至于迷路、乱跑、误判完成。

8.2 哪些信号说明文档需要更新

这些信号一出现，就应该考虑更新：

• agent 在相似地方连续犯同一种错
• reviewer 重复提出同一种评论
• 同一个“先看哪个文件/先跑哪个命令”的问题反复出现
• 团队成员口头解释的内容总在重复
• 文档指向的命令/路径已经变了
• 局部系统已经复杂到根文档很难容纳

8.3 哪些 agent 常见失误值得沉淀进文档

最值得沉淀的不是所有失误，而是这三类：

• 重复出现的
• 代价高的
• 代码里不容易自行推断的

例如：

• 总是改错目录
• 总是忘记更新 snapshot / docs / registry / metadata
• 总是误判“部署成功”或“测试通过”
• 总是去碰生成文件
• 总是用错本仓库工具链

8.4 哪些内容应该升级为常驻规则

建议用一个简单门槛：

• 连续出现两次以上
• 对质量/稳定性/协作效率有实质影响
• 未来仍大概率长期有效

同时满足这三点，再升级为常驻规则。

8.5 哪些内容应该从文档里移走

以下内容适合移走：

• 只适用于一次任务的说明
• 太长的手工流程
• 已经由脚本或 CI 强制保证的重复说明
• 已过期的历史背景
• 和主文档职责重复的局部细节

8.6 如何避免文档越写越大、越写越杂

推荐三个硬办法：

1. 新增一条常驻规则前，先问：这是高频、稳定、项目特有吗？
2. 根文档超过一个合理密度阈值，就拆目录级文档或外部 runbook
3. 每次新增规则时，顺手删掉一条已经过时或重复的

很实用的团队习惯是：

• 根文档只收“重复价值高”的规则
• 临时说明先放任务文档
• 复发后再决定是否晋升到根文档

8.7 如何定期回顾并保持有效性

推荐双节奏：

• 轻回顾：每 1 到 2 周，看最近 agent/reviewer 反复纠正了什么
• 深回顾：每 1 到 2 个月，用第 7 节的评分框架重新打分

深回顾时重点看：

• 文档有没有变长但没更有用
• 局部文档是否该拆
• 哪些规则其实应该变成脚本/CI/hook
• 哪些规则已经没有存在价值

9. 最终结论：最值得立即采纳的实践

下面是按优先级排序的“先落地清单”。

9.1 优先采用的 10 条实践

1. 根文档只写高频、稳定、项目特有的信息。 这是所有有效性的基础。没有这个筛选，文档很快会变噪音。
2. 先写精确命令、路径、入口文件，再写原则。 agent 最先需要的是操作锚点，不是抽象价值观。
3. 在根文档里优先做路由。 对多目录、多子系统仓库来说，这一步的收益经常比多写十条规则还大。
4. 明确写出禁区和不可绕过项。 包括生成文件、兼容性边界、部署流程、合规要求、CI 规则。
5. 明确写出完成定义和验证顺序。 很多低质量交付，根源不是实现差，而是完工判断差。
6. 把复杂流程拆出去。 根文档保留入口，长流程交给 runbook、skill、script、PLANS.md。
7. 对局部复杂子系统使用目录级文档。 根文档负责总览，局部文档负责专业细则。
8. 把重复事故和重复 review 评论沉淀成规则。 这比事先想象一堆“完美规范”有效得多。
9. 不要把文档当硬约束。 真正危险的事情应交给脚本、CI、权限和策略层保证。
10. 把 Agent 文档当成持续演化的操作配置。 它不是一次性写作任务，而是仓库协作系统的一部分。

9.2 先别急着写的东西

• 过长的项目背景
• 完整架构教材
• 一次性任务说明
• 低频操作手册
• 已经被 formatter/linter/CI 自动约束的重复说明
• 纯展示性“最佳实践大全”

9.3 最应该避免的错误

• 把所有内容都堆进一个根文档
• 规则写得很抽象，看起来很专业，但无法执行
• 不写完成定义
• 不写禁区
• 不区分常驻规则与外部流程
• 文档更新滞后于真实工具链
• 把单一高手的个人风格误当成通用规范

附：本研究最关键的证据点

为了方便回看，这里把最关键的证据点再压缩成一页：

• 实证研究：2,303 份 agent context files，显示这些文件普遍是活的、会持续更新的操作型文档，而不是一次性说明。
• 同一研究显示：开发者最常写的是实现细节、架构、构建/运行命令，而不是宏大背景；安全与性能要求在样本中反而偏少，这说明它们不是“自然会被写进去”的，若项目高风险，需要主动补。
• Anthropic 文档：CLAUDE.md 是上下文，不是硬 enforcement；长了会消耗上下文并降低遵循度；多步流程和局部规则应拆分。
• GitHub 文档 与 Skills 文档：repo-wide instructions、path-specific instructions、skills 有明确分工。
• AGENTS.md 规范站：最近文件优先、嵌套文档、跨工具兼容，这为“根路由 + 局部规则”提供了简单统一的语义。
• OpenAI 的 PLANS.md 实践：复杂长流程应拆成外部 living doc，而不是硬塞进根文档。
• 真实仓库样本、真实仓库样本、真实仓库样本、真实仓库样本 共同指向同一个事实：真正有用的 Agent 文档，核心不是“多”，而是“精确、分层、可验证”。

结论边界

最后再强调一次边界：

• 对工程仓库型文档，本报告的结论可信度最高。
• 对通用任务型、研究型、自动化型，结论更多来自机制类比与跨样本归纳，适合先按此框架落地，再结合自己的任务数据迭代。
• 对“最佳长度”“最佳格式”这类问题，不应追求唯一标准。比格式更重要的是：信息密度、可执行性、分层设计、验证闭环。