一个文件让AI-Coding效率翻倍-AGENTS-实践指南

一句话概括

通过AGENTS.md文件将项目的结构、规矩、命令、验证方式写成AI能读懂的格式，配合仓库聚合、参考项目引入、启动脚本封装和自动化检查，形成一套”打开即理解、改完即验证”的AI Coding开发体验。

AGENTS.md 的第一原则是渐进式披露——它是一张地图，不是一本手册。什么都重要的时候，什么都不重要。如果把所有内容都塞进 AGENTS.md，它会变成一个 5000 行的巨型文件，AI 的注意力被稀释，真正关键的规则反而容易被忽略。

痛点总结：这些痛点的共同根源是：项目的知识和规范存在于人的脑子里，而不是存在于 AI 能读到的地方。AGENTS.md 要解决的就是这个问题——把项目的结构、规矩、命令、验证方式写成 AI 能读懂的格式，放在仓库里。

规则要有执行力。AGENTS.md 中写”禁止跨层依赖”，如果没有 lint 脚本来检查，AI 和人都会违反。规则的优先级：能自动化检查的 > 写在 AGENTS.md 中的 > 口头约定的。

源码永远不会过时，它就是最准确的文档。AI 不会写私域组件的代码时，可以直接读源码里的 TypeScript 定义和实现；需要对接网关内核时，可以直接查看路由和插件的实际代码。