告别泥球文档：AGENTS.md 最佳实践与渐进式

给 AI 写代码规则，千万别堆成“泥球”。

AGENTS.md 是写给 AI 编程助手的说明书。但文件一长，AI 反而容易跑偏。

太长的坏处：主流大模型最多只能稳定记住 200 条指令。规则重复、冲突，或者路径过时，都会挤占 AI 的注意力。它甚至会照着旧路径找错文件。

根目录只留三样：一句话项目简介。用什么包管理器（不是 npm 得特别说）。还有非标准的构建命令。别的内容全删掉。

具体规则按需加载：把 TS、测试等规范拆成独立文档。根文件只做跳转。AI 用到哪块再读哪块，省 Token 还不乱。

别写死文件路径：目录一改文档就废了。多说说业务概念和能力边界，让 AI 自己去检索。

大仓库分层管：单体仓库可以在子包里放专属说明。AI 会自动合并，每层只管自己那摊事。

重构时先挑出核心内容，再把剩下的分类拆走。