团队推 AI 编程·先写项目宪法·AGENTS.md

01为什么是 AGENTS.md，不是 README

README 是给人看的，AGENTS.md 是给 AI 看的。两者写法完全不同：README 讲"这个项目是什么"，AGENTS.md 讲"在这个项目里 AI 该怎么干活"。

没有 AGENTS.md 时，AI 会从训练数据里猜你团队的规矩——结果就是 10 个人各自的 AI 写出 9 种风格：有人用 class，有人用函数；有人 commit 信息写中文，有人写英文；有人 import 排序，有人不排。技术债不是 AI 制造的，是没立规矩就让 AI 上岗制造的。

AGENTS.md 通常放仓库根目录，主流 AI 编程工具（Cursor、Claude Code、Codex）都会自动读取。它不是文档，是可执行的约束——AI 读了会照着做。

02AGENTS.md 体检表：你的项目及格没

下面是 AGENTS.md 应有的 8 个条目。勾选你的项目宪法里有没有，提交看及格没。

03写宪法的三条原则

有了条目清单，还要会写。三条原则让宪法真正被 AI 执行，而不是摆设：

• 具体到能判断对错。"用清晰的命名"是废话，"变量名用 camelCase，禁止单字母（循环变量除外）"才是宪法。AI 不会猜你的"清晰"是什么意思。
• 写禁区比写鼓励更重要。告诉 AI"不要碰 auth 目录、不要装新依赖、不要直接改 migration 文件"，比告诉它"要写好代码"有效十倍。禁区是硬约束。
• 配示例，不只配规则。给一个"好的 commit"和"坏的 commit"的例子，比写 200 字规则管用。AI 学示例比学规则快。

04带走这套清单