AI 编程项目规则：AGENTS.md、CLAUDE.md、Cursor Rules 与 Spec
了解 AGENTS.md、CLAUDE.md、Cursor Rules、MCP、spec 和验证关卡如何分工——让 Agent 保持有用，而不是替你决定发布。
当仓库里写清楚该怎么干活时，AI 编程工具表现会更好。这份说明通常体现为 AGENTS.md、CLAUDE.md、Cursor Rules、MCP 配置、spec，以及验证关卡。
这些文件是指令和约定，不能替代人工审查，也不能替代一次真正跑绿的构建。
直接答案
| 载体 | 主要作用 |
|---|---|
AGENTS.md / CLAUDE.md / Cursor Rules | 告诉 Agent 项目约定、边界和推荐命令 |
| Spec / 任务简报 | 定义一次改动的“完成”是什么样子 |
| MCP / 工具配置 | 控制 Agent 能调用哪些外部工具 |
| 验证关卡 | 用测试、构建、lint 和审查清单证明改动是可信的 |
规则要短、要能落地执行。没人维护的长篇大论，最后只会变成被忽略的噪音。
非技术构建者可以先看 Vibe coding 也别失控。发布前的检查动作，用 工作流检查清单。
什么时候这篇指南对你有用
- 你的 Agent 老是改错文件夹，或者自己发明新的代码模式。
- 团队对哪份说明文件才是权威版本有争议。
- 你想启用 MCP，但不想给出无限制的网络或仓库权限。
- 你需要分清“Agent 指引”和“合并前必须满足的要求”这两件事。
在 AI 编程插件目录 可以浏览相关的插件和技能。
说明文件：划边界，不是变魔法
AGENTS.md
通常被当作仓库级的 Agent 简报：技术栈、目录结构、必须执行的命令、禁止的操作，以及指向更细文档的链接。
好的内容：
- 包管理器和所需的 Node/Java/Python 版本
- 如何运行测试和 lint
- Agent 应该避开的目录
- PR 或 commit 的命名方式
不好的内容：
- 从营销物料复制粘贴来的产品介绍
- 密钥和生产环境地址
- 没人维护、互相矛盾的规则
CLAUDE.md
通常用来给 Claude 相关工具提供项目指引。把它当作 AGENTS.md 一样对待：保持更新、具体、简短。如果两个文件同时存在，要明确共享规则以哪份为准，或者刻意保持两者同步。
Cursor Rules
Cursor Rules 一般是编辑器/Agent 范围的指令（项目规则或用户规则）。适合用来写：
- 代码风格和框架约定
- “在声称完成之前，必须先跑 X”
- 需要格外小心的路径（鉴权、账单、数据库迁移）
不要把关键的安全策略只藏在同事看不到的个人用户规则里。
Spec 与任务切片
Spec 回答的是要做什么、怎么算验收通过。规则回答的是 Agent 在做这件事时应该怎么表现。
一份有用的迷你 spec 通常包括：
- 用户能感知到的结果
- 明确不做的部分
- 大概会改到哪些文件或区域
- 测试或人工检查步骤
- 如果风险较高，附上回滚说明
没有 spec 的 Agent 会自己发明范围。没有 spec 的人类，只能事后争论。
MCP 与工具访问
MCP（以及类似的工具桥接方案）让 Agent 可以调用外部系统。这既强大，也危险。
启用工具之前：
- 优先使用只读权限
- 尽可能对主机和命令做白名单
- 永远不要把生产密钥粘贴进被提交到 git 的 MCP 配置里
- 对有实质影响的改动，记录用了哪些工具
MCP 配置管理的是能力边界，不是产品文档。
验证关卡
规则可以说“运行测试”。关卡要求给出证据：
npm test/npm run build（或对应技术栈的等价命令）- 适用场景下的 lint 和类型检查
- 检查 diff 里是否混入密钥或出现异常的文件改动
- 使用 AI 代码审查清单 和 上线检查清单 之类的清单
也可以参考 AI 编程 Agent 需要验证关卡。
关卡没跑绿，就不算“完成”。
一个实用的落地顺序
- 先写一页纸的
AGENTS.md（或等价文件），列出命令和禁止改动的区域。 - 只在需要工具特定的补充说明时，才加 Cursor Rules /
CLAUDE.md，避免多份文件互相打架。 - 任何非小改动都要求配一份简短的 spec。
- 收窄范围地启用 MCP 工具。
- 让合并依赖验证关卡的结果，而不是 Agent 自己说“我觉得可以”。
局限
- 文件命名和产品功能一直在变，请以 Cursor、Claude Code、Codex 等工具的当前文档为准。
- 规则文件解决不了产品归属不清的问题。
- 规则堆得太长会被跳过——优先链接到会持续更新的文档，而不是把所有内容都粘进去。
FAQ
是不是每种文件类型都要有？
不需要。先有一份权威的简报，再为真实任务配 spec 就够了。等产品真的需要时，再加工具特定的文件。
密钥应该放在哪里？
放在环境配置和密钥管理服务里——不要放进规则文件、prompt，也不要放进被提交到仓库的 MCP 配置。