Codex 怎么详细科学地用 `CLAUDE.md` / `AGENTS.md` 固化规则
本文聚焦一个非常关键的长期能力：不是只让 Codex 这一次做对，而是通过
CLAUDE.md/AGENTS.md把项目规则、团队习惯、边界、验证方式和高风险约束长期固化下来。这样做的目的，是让 Codex 从“偶尔配合得不错”，升级成“长期稳定、越来越贴合项目”的协作成员。
1. 文档目标
这份文档解决的是下面几个长期协作问题：
- 为什么每次都要重新解释项目规则
- 为什么同样的需求，不同人问 Codex 结果差异很大
- 怎么把团队已有经验沉淀成可执行规则
- 怎么把这些规则写进
CLAUDE.md/AGENTS.md - 怎样让规则既详细，又不空泛，还能长期维护
读完后，你应该能够：
- 理解什么时候该用
CLAUDE.md，什么时候该用AGENTS.md - 识别哪些规则值得固化
- 生成更贴合真实项目的规则文件
- 把项目结构、边界、Git、测试、验证等要求固化进仓库
2. 为什么要固化规则
如果不固化规则，Codex 每次都像一个“刚加入项目的新同学”。
常见现象：
- 每次都要重新解释目录结构
- 每次都要重新强调“不要大改”
- 每次都要重新补“这个模块别动”
- 团队成员和 AI 的工作方式不一致
而把规则固化之后，会带来几个明显收益：
- Codex 更快进入项目语境
- 输出更稳定
- 团队成员之间提问方式更一致
- 高风险错误更少
- 新成员上手更快
一句话理解：
规则文件的目的，不是写给文档看，而是写给真实协作和长期复用。
3.CLAUDE.md和AGENTS.md分别适合什么
虽然两者都可以承载规则，但使用侧重点略有不同。
3.1AGENTS.md
更适合：
- 项目级长期规则
- 团队共用的默认协作要求
- 模块边界、Git、验证、禁改项
3.2CLAUDE.md
更适合：
- 个人或团队额外协作说明
- 某类任务的特殊注意事项
- 对 AI 行为方式的补充偏好
3.3 实际建议
如果只选一个，优先把项目级长期规则写进AGENTS.md。
如果还有更多补充偏好，再用CLAUDE.md承载附加说明。
4. 什么规则值得固化
不是所有内容都值得写进规则文件。
值得固化的内容
- 项目结构和模块职责
- 长期不变的分层规则
- 常见高风险区域
- 默认修改边界
- Git 协作规则
- 测试和验证要求
- 明确禁止事项
不适合固化的内容
- 一次性 bug 细节
- 当前需求独有的临时要求
- 很快就会过期的局部现象
一句话判断：
高频出现、长期有效、团队通用的内容，最值得固化。
5. 科学固化规则的核心原则
一个好的规则文件，不只是“多写一点”，而是要满足这些原则。
5.1 可执行
规则必须能指导行动，而不是停留在口号层。
例如：
- 差：注意代码质量
- 好：Mapper / XML 改动后必须检查分页和动态条件
5.2 可验证
规则最好能被检查，而不是纯主观判断。
例如：
- 修改后必须给验证步骤
- 高风险改动前必须保留基线快照
5.3 可长期使用
写进去的内容应尽量不依赖一次性情境。
5.4 有边界
要说清：
- 什么该做
- 什么不该做
- 什么高风险
5.5 不空泛
不要只写：
- 注意风险
- 保持整洁
- 尽量规范
这些话几乎没有执行价值。
6. 一份高质量规则文件应包含什么
最推荐的结构通常包括：
7. 最推荐的规则固化流程
8. 第一步：不要凭空写规则，要先从真实任务里提炼
最差的写法，是坐下来空想一份规则文件。
更好的方式是从真实协作里提炼：
- 哪些要求你每次都要重复说
- 哪些错误 Codex 经常重复犯
- 哪些模块每次都容易误改
- 哪些验证要求每次都离不开
典型提炼来源
- 高质量 Prompt
- 常见 bug 修复过程
- 小步迭代和计划输出过程
- Git 协作和回滚经验
- 测试和回归清单
9. 第二步：先写“项目级长期规则”，不要一开始就写太细碎
优先写这些层次：
- 项目结构说明
- 模块职责
- 默认工作方式
- 修改边界
- 高风险规则
- Git 规则
- 验证规则
为什么先写这些
因为这些最通用、最稳定、最值得长期复用。
10. 第三步：让规则尽量贴近真实项目
好的规则文件一定要“贴地”。
不好的写法
保持代码整洁。 遵守最佳实践。 注意安全性。更好的写法
- Controller 只做参数接收和返回封装，不写复杂业务。 - Service 负责业务编排和流程控制。 - Mapper / XML 改动后必须重点检查动态条件和分页逻辑。 - 涉及事务边界改动时，必须说明验证方式和回滚思路。11. 第四步：明确“默认工作方式”
这是很多团队最容易漏掉的部分。
规则文件不只要写代码规则，还应该写 AI 默认怎么工作。
建议写入
- 先理解再执行
- 复杂任务先出计划
- 优先最小改动
- 不做无关重构
- 修改后必须给验证步骤
12. 第五步：明确“高风险场景特殊规则”
高风险任务最值得额外写规则。
例如：
- 数据库结构改动
- SQL 动态条件改动
- 事务边界改动
- 权限逻辑改动
- 支付逻辑改动
推荐写法
- 涉及数据库结构、事务边界、权限控制、支付逻辑、公共基础组件时： - 必须先说明影响范围 - 必须优先最小改动 - 必须给验证方式 - 必须说明回滚思路13. 第六步：把 Git 协作和验证要求一起写进去
如果只写代码规范，不写 Git 和验证，规则是不完整的。
建议同时固化：
- 分支规则
- commit 粒度规则
- 合并前检查
- 回滚规则
- 修改后验证规则
14. 第七步：让规则文件既能读，又能执行
一份好的规则文件，应该让 Codex 和团队成员都能直接照着做。
所以建议：
- 结构清晰
- 标题明确
- 规则短句化
- 避免大段抽象描述
15. 最推荐的 AGENTS.md 结构模板
# AGENTS.md ## 项目说明 ## 模块与目录职责 ## AI 工作原则 ## 修改边界与约束 ## 高风险场景规则 ## Git 协作规则 ## 测试与验证要求 ## 禁止事项16. 一段可直接生成规则草案的提示词
请基于这个项目的结构、模块、调用链、高风险区域和团队协作方式，生成一份适用于本项目的 AGENTS.md / CLAUDE.md 规则草案。 要求： 1. 只提炼长期有效规则，不写一次性临时现象 2. 内容贴近真实项目，不空泛 3. 必须覆盖： - 项目说明 - 模块职责 - AI 工作方式 - 修改边界 - 高风险场景 - Git 协作规则 - 测试与验证要求 - 禁止事项17. Java / Spring Boot 项目实战实例
场景
一个 Spring Boot + MyBatis 项目，团队希望让 Codex 更稳定地参与开发。
推荐固化方式
应优先写入：
Controller -> Service -> Mapper -> XML的分层职责- SQL / Mapper XML 动态条件与分页风险
- 事务边界改动规则
- Git commit、分支与回滚要求
- 修改后验证与回归要求
示例规则片段
## 分层职责 - Controller 只做参数接收、权限入口和返回封装。 - Service 负责业务编排与流程控制。 - Mapper / XML 负责数据查询与持久化。 ## 风险规则 - 涉及 Mapper / XML 改动时，必须重点检查动态条件和分页逻辑。 - 涉及事务边界改动时，必须先说明验证方式和回滚思路。 ## 默认工作方式 - 复杂任务先出计划，不直接大改。 - 默认优先最小改动，不做无关重构。 - 修改后必须给验证步骤和回归建议。18. 团队协作实战实例
场景
团队中多人会用 Codex，但每个人问法不同、输出结果差异很大。
推荐做法
- 先整理过去高频任务中的重复规则
- 再产出第一版
AGENTS.md - 团队共同 review
- 在真实需求里试运行
- 再补充遗漏规则
图示
19. 常见误区
19.1 误区一：规则写得太空泛
问题：
- 无法指导真实协作
19.2 误区二：把一次性需求细节写进规则文件
问题：
- 很快失效
19.3 误区三：只写代码规范，不写 Git 和验证
问题：
- 规则不完整
19.4 误区四：只写规则，不做团队评审
问题：
- 规则可能不贴近真实习惯
19.5 误区五：规则写完不维护
问题：
- 很快与真实项目脱节
20. 注意事项
- 优先固化长期有效规则
- 规则必须具体、可执行
- 高风险区域要单独写
- 默认工作方式也要写进规则文件
- Git 与验证要求不能缺位
- 规则文件必须团队共同 review
21. 高质量提示词模板
21.1 规则固化模板
请基于当前项目，生成一份详细、科学、可执行的 AGENTS.md / CLAUDE.md 规则草案。 要求： 1. 只提炼长期有效规则 2. 不要空泛 3. 要覆盖项目结构、工作方式、边界、风险、Git、验证和禁止事项21.2 规则提炼模板
请基于我们前面多个高频任务中的目标、约束、上下文和验证要求，总结一份适合长期固化的项目规则。 请区分： 1. 适合长期写入 AGENTS.md 的内容 2. 只适合本次任务使用的临时要求22. 团队落地建议
如果你想把这套方式真正落地到团队里，建议这样做：
- 先从一个核心项目试点
- 固化第一版
AGENTS.md - 再根据需要补充
CLAUDE.md - 把高频踩坑案例转成规则
- 每个版本周期回顾一次是否需要更新
23. 一句话总结
科学地用CLAUDE.md/AGENTS.md固化规则，本质上是在把团队口头经验、重复提醒和隐形习惯，转成项目级、可执行、可长期复用的 AI 协作基础设施。
24. 快速上手清单
- 先收集高频重复规则
- 再筛出长期有效内容
- 再按结构写成规则草案
- 再团队评审
- 最后正式入库并持续维护