Layered READMEs Give AI Coding Agents a Repository Map
The article recommends placing one README in every project directory to serve as an AI-oriented index, with entries limited to direct contents, ownership, boundaries, entry points, commands, and change notes. It also provides prompt rules that require agents to read the relevant README before editing and a zero-dependency Node.js checker for missing coverage. In a self-reported demonstration of 14 directories, nine README files produced 64.3% coverage, rising to 100% after the remaining five were added.
The proposal gives teams a concrete, tool-enforceable way to organize repository context for AI coding agents, although the claimed reduction in irrelevant reads and incorrect edits was not measured.
结论:在项目根目录和每一层子目录各放一份 README,只写「本层有什么、谁负责、什么不该放这儿」,再在提示工程里要求 AI 动手前先读它——这是投入产出比最高的一条 AI Coding 约定。 它不改代码、不引框架、不装插件,只花写文档的时间,换回的是 AI 少读十个无关文件、少改错一个模块。下面是规则、模板、一段可直接抄进 rules 的提示词,以及一个我自己跑过的 README 缺口检查器。
目录
- 结论先说:README 是给 AI 看的目录索引(Index, Not Doc)
- AI 为什么爱改错文件:上下文里缺一张「哪块归谁」的地图(Why AI Misses)
- 三条硬规则:一层一份、只写直系、先读后改(Three Rules)
- 一份 README 写什么:五个字段的固定模板(Template)
- 提示工程怎么写:把「先读」变成硬约束(Prompt Rules)
- 一次可复算的实测:14 个目录、9 份 README、64.3%(Measurement)
- 完整可运行代码:README 缺口检查器(Runnable Checker)
- README 与 AGENTS.md、CLAUDE.md 的分工(Boundaries)
- 症状、原因、解法对照表(Symptom → Cause → Fix)
- 落地顺序:先根、再三层、最后卡 CI(Rollout Order)