技术 · 熟练
一份文件喂饱所有 AI，上下文就爆了
硬约束始终加载，详细参考按需再读
AGENTS.md 的常见写法是把所有东西都塞进根目录那一个文件 —— 写到两千行，AI 每次开工先吃掉一大截窗口，真正要紧的硬约束反而被淹了。这一页补的是结构那一层：根文件只留硬性约束 + 关键约定摘要 + 文档维护规则 + 索引，控制在 ≤300 行、始终加载；详细参考（分模块约定 / 组件说明 / 排障）放同级 `docs/`，由 AI 按需再读。另一件新变化也要写进流程：从 2026-09-18 起 Claude Code v2.1.277 起原生支持 AGENTS.md —— 仓库里没有 CLAUDE.md 时会回落读它（暂时不含 Bedrock / Vertex / Foundry）。关键动作只有一个：把「每次都要遵守的」和「用到才看的」分开，前者短而硬，后者长而全。
方法 · 一图看懂
1
划两层 — 把现有说明按「每次开工都必须知道」与「用到才查」分开，前者进根文件，后者进 `docs/`
2
压根文件 — 根文件只留四块：硬性约束 · 关键约定摘要 · 文档维护规则 · `docs/` 索引，控制在 ≤300 行
3
给索引写清「什么时候读」 — 索引里每一行都写用途与触发场景，让 AI 判断得出该不该去读
4
该省的省掉 — 从代码本身就能读出来的（函数签名、完整依赖列表）与'期望中的样子'一律不写，⛔ 只描述项目现在是什么样
5
跟着改动走 — 结构性改动与文档同一次提交；另定期让 AI 拿代码核一遍，⛔ 过期的说明比没有更误导
原理 · 为什么有效
两层架构有效，是因为它对准了 agent 真实的工作方式：上下文窗口是有限的，而项目的说明是无限的。
① 硬约束必须每次在位 —— 命名、目录归属、不许碰的目录这类规则，错过一次就产出不可用的东西；它们必须在小而常驻的那一层。
② 详细参考必须按需 —— 组件文档、排障手册这类内容，多数任务根本用不到；常驻只会占窗口、稀释注意力。
③ 索引让「按需」可被执行 —— 只要索引里写清「什么时候读」，AI 就能自己判断；不写触发场景，它要么全读（浪费）要么不读（瞎猜）。
④ 语料要描述现状而不是愿望 —— agent 会照着写的东西建，读到愿望就会在愿望上施工。
⚠️ 边界（如实说明）：AGENTS.md 没有必填字段，也不需要特定语法，所以「写得对不对」没有自动检查 —— 这一页给的是判据与结构，仍然需要你自己核一遍内容是否与代码一致。
适用场景
① 仓库里已有 AGENTS.md / CLAUDE.md，但已经长到几百上千行；
② 团队同时用多个编码工具，想只维护一份说明；
③ 单仓库里多个子包，各包约定不同；
④ 之前写过的说明「AI 读了但没照做」 —— 往往是详细内容把硬约束埋住了。
⛔ 不适用：没有任何文档基础、项目本身还没定型的情况（先让项目稳定下来再补说明，否则写完就过期）。
自测 · 5 问
根文件现在多少行？超过 300 行 ⇒ 先做减，再谈别的优化。
根文件里，能不能一眼数出「每次都必须遵守」的硬约束有几条？数不出 ⇒ 它们被详细内容埋住了。
`docs/` 索引里每一行都写了「什么时候该读」吗？只写文件名 ⇒ AI 判断不出该不该读。
说明里有没有写「我们希望以后改成……」这类愿望？有 ⇒ 删掉，agent 会在愿望上施工。
上一次拿代码核对说明是什么时候？记不得 ⇒ 今天就安排一次，过期的说明比没有更误导。
怎么上手 · 验证步骤
第一次做，建议按这个顺序走，一次不超过一小时：
① 打开现有说明，给每一行贴一个标签：硬约束 / 约定摘要 / 详细参考 / 可推断 / 愿望；
② 把「详细参考」整段剪到 `docs/` 下的对应文件（按模块分，不按时间分）；
③ 「可推断」和「愿望」直接删；
④ 保留的在根文件里重排成四块，并为 `docs/` 建索引（每行写用途 + 触发场景）；
⑤ 写完做一次验证：让 AI 只拿根文件回答「这个项目新组件该放哪、测试怎么跑」，答得出说明结构成立。
跑完第一轮后自检一件事：新开一个会话，只给 AI 根文件，问三个新人入职式的问题（约定放哪 / 怎么跑测试 / 哪些目录不能碰）。答不出 ⇒ 说明硬约束还不在根文件里，回去补；答得出 ⇒ 再看 `docs/` 索引是否真的被按需读取（观察它有没有为了一个小改动去读整份组件文档）。这一步只核这一个问题，⛔ 不顺手去改内容风格。