用分层 README 约束 AI Coding
AI 总结
文章建议在项目根目录和各级子目录各放一份 README,作为面向 AI 的目录索引,只记录直系内容、职责、边界、入口与命令及变更提示。作者还给出修改前必须阅读相关 README 的提示规则,以及检查缺失 README 的零依赖 Node.js 脚本。在其自建的 14 个目录演示中,9 份 README 的覆盖率为 64.3%,补齐其余 5 份后达到 100%。
深度见解
这套方法为 AI 编程工具管理仓库上下文提供了可直接落地的结构和检查机制,但减少无关读取与错误修改的效果尚未被量化验证。
结论:在项目根目录和每一层子目录各放一份 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)