本文聚焦一个非常关键的长期能力不是只让 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. 一份高质量规则文件应包含什么最推荐的结构通常包括项目说明模块与目录职责AI 工作方式修改边界与约束高风险场景规则Git 协作规则测试与验证要求禁止事项7. 最推荐的规则固化流程1. 先观察高频任务2. 总结重复出现的规则3. 区分长期规则与临时要求4. 写成结构化规则草案5. 团队评审与补充6. 正式写入 AGENTS.md / CLAUDE.md7. 在真实任务中验证并持续更新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在真实需求里试运行再补充遗漏规则图示高频任务经验提炼重复规则生成 AGENTS.md / CLAUDE.md 草案团队评审项目内试运行补充与修正长期维护19. 常见误区19.1 误区一规则写得太空泛问题无法指导真实协作19.2 误区二把一次性需求细节写进规则文件问题很快失效19.3 误区三只写代码规范不写 Git 和验证问题规则不完整19.4 误区四只写规则不做团队评审问题规则可能不贴近真实习惯19.5 误区五规则写完不维护问题很快与真实项目脱节20. 注意事项优先固化长期有效规则规则必须具体、可执行高风险区域要单独写默认工作方式也要写进规则文件Git 与验证要求不能缺位规则文件必须团队共同 review21. 高质量提示词模板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. 快速上手清单先收集高频重复规则再筛出长期有效内容再按结构写成规则草案再团队评审最后正式入库并持续维护