别每次都重新提醒 AI：我怎么用 CLAUDE.md 和 AGENTS.md 沉淀项目规则

最近我越来越少在每次对话开头写一大段“你要注意什么”。

不是因为 AI 终于能自动记住项目了，而是我把很多反复提醒它的东西，写进了项目里的规则文件。

一开始我只是觉得这样省事。后来连续在几个项目里跑下来，才发现这件事比“省几句 prompt”更重要。

它解决的不是一次回答质量，而是一个项目长期使用 AI CLI 时的稳定性。

比如写公众号文章，我不希望每次都重新提醒它：不要写成官方教程，不要营销腔，不要暴露内部路径，不要把产品能力写成可复刻教程。

比如做小程序页面，我不希望每次都重新提醒它：先看现有组件，按钮优先复用统一组件，页面要适配微信小程序，设计稿不能只凭截图大概还原。

比如做桌面工具项目，我不希望每次都重新提醒它：前端、后端、系统能力的边界在哪里，哪些命令可以验证，哪些风险操作必须先问人。

这些内容如果一直留在聊天窗口里，就会有两个问题。

第一，换会话之后容易丢。

第二，长对话里容易被新的上下文冲淡。

所以我后来开始把它们放到 CLAUDE.md、AGENTS.md、.claude/rules/、.codex/rules/ 这类文件里。它们表面上只是几份 Markdown，实际作用更像是项目里的 AI 工作协议。

这些文件不是同一种东西

我最开始也会把这些文件混在一起看。

好像只要是给 AI 看的规则，就都能扔进去。后来项目多了之后，我发现必须先拆清楚：哪些是项目总入口，哪些是工具专用规则，哪些是任务专项流程，哪些其实是权限或命令规则。

我现在大概按这几层理解。

CLAUDE.md 是 Claude Code 进入项目时的总入口。

我会把项目背景、技术栈、常用命令、目录职责、沟通方式、不可破坏的边界放进去。它不适合写得太散，因为它是入口文件。Claude 每次处理这个仓库时，应该先知道这个项目是什么、怎么跑、什么不能乱动。

AGENTS.md 是给 Codex 或其他 Agent 看的项目总入口。

它和 CLAUDE.md 可以有大量重叠内容，但我不会简单理解成“复制一份”。因为不同工具的工作习惯不一样。Codex 更偏文件、命令、diff、验证和权限边界；Claude Code 在长文本、长上下文和写作协作里更常被我当主笔。所以同一套项目规则，到不同工具里会有不同侧重点。

.claude/rules/ 更像 Claude 侧的规则库。

比如写文章的语气、公众号图文版的排版检查、某类业务流程的处理方式，都可以拆到这里。这样根目录的 CLAUDE.md 不至于越来越长。

.codex/rules/ 在我自己的项目里也会放 Codex 侧的规则文档，比如审稿标准、工程规范、协作流程。

但这里要特别说清楚：Codex 官方也有 command approval rules，用来控制命令是否可以在沙箱外运行。这个和我项目里用 Markdown 写的“工作规则文档”不是同一个东西。

所以如果写文章或者给团队讲，一定不要把两者混在一起说。

我会把自己的 Markdown 规则理解成“项目约定”，把官方 rules 理解成“命令审批和权限控制”。一个约束 AI 怎么理解和执行任务，一个约束命令能不能被放行。

我真正需要规则文件，是从反复踩坑开始的

规则文件不是我一开始就设计好的。

它是被项目逼出来的。

最早的信号很简单：同一个错误出现第二次。

比如写文章时，我已经说过很多次要像真实开发者复盘，但它还是容易写成方法论模板。段落很整齐，观点也对，但读起来不像人写的。尤其是“核心目标”“一句话先行”“转化钩子”这类痕迹，一眼就能看出是 AI 文档腔。

后来我把这类口吻要求沉淀成写作规则：

先写具体经历，再提炼方法。
产品提及必须来自个人实践，不写广告式定位。
技术结论要有边界，不把经验写成绝对规律。

这类规则如果每次临时说，很容易漏。写进规则文件后，起草和审稿都能复用。

另一个信号是：AI 改代码时总想“顺手优化”。

我在一个小程序项目里遇到过类似问题。任务本来只是改一个页面状态，它会顺手动到组件结构、样式组织，甚至试图把旧代码按自己理解重新整理一遍。代码不一定不能跑，但改动范围已经超出需求了。

后来项目规则里就必须写清楚：

只改与目标直接相关的代码。
发现历史代码不符合新规则时，除非本次需求覆盖该区域，否则记录风险，不做大面积无关改造。

这句话看起来普通，但很有用。

因为 AI 很容易把“我看到了可优化点”误解成“我应该现在修掉它”。规则文件要帮它把这个边界卡住。

第三个信号是：项目里有固定流程，不能靠模型临场发挥。

比如设计稿还原。

如果只是让 AI “按照设计稿实现页面”，它可能会先写代码，再回来补说明。对普通页面也许还能接受，但如果是高保真还原，这个顺序就是错的。

后来我会把流程写得非常具体：

先分析设计稿，不先写代码。
先沉淀页面结构、尺寸、资源和状态，再制定实施计划。
实现后对照分析文档自查，再跑构建验证。

这类规则不是风格偏好，而是工作顺序。

顺序一错，后面就会越改越乱。

根目录文件适合做入口，不适合塞成百科

我一开始写 CLAUDE.md 和 AGENTS.md，很自然地会把所有东西都塞进去。

项目背景要写，技术栈要写，目录结构要写，命令要写，组件规范要写，UI 还原流程要写，风险操作也要写。

短期看很方便。

一个文件打开，什么都有。

但项目跑久了，这种写法会出现问题：入口文件越来越长，真正重要的规则反而不容易被看到。

我后来在不同项目里慢慢形成了一个拆法：

根目录的 CLAUDE.md / AGENTS.md 只保留总入口。

里面写：

• 这个项目是什么
• 技术栈是什么
• 常用命令是什么
• 主要目录怎么分工
• 处理任务前先读哪些规则
• 哪些风险操作必须先确认

更细的东西拆到 .claude/rules/ 和 .codex/rules/。

比如一个工程项目可以拆成：

.claude/rules/
  README.md
  01-collaboration-workflow.md
  02-engineering-standards.md
  03-domain-decisions.md

Codex 侧也可以有对应版本：

.codex/rules/
  README.md
  01-collaboration-workflow.md
  02-engineering-standards.md
  03-domain-decisions.md

这里最关键的是 README.md。

它不是摆设，而是入口索引。

我会在里面写清楚读取顺序：先读根目录入口，再读协作流程，再读工程规范，只有任务涉及领域边界时才读领域决策。这样规则不会一次性全塞进上下文，也不会让 AI 靠猜去找文件。

成熟一点的项目，规则文件应该从“项目百科”慢慢收敛成“入口索引 + 专项规则”。

这比单个大文件更稳。

规则要写动作，不要只写态度

很多规则写了等于没写，是因为它们太像口号。

比如：

保持代码质量。
注意安全。
遵守项目规范。
输出要专业。

这些话本身没错，但对 AI 的帮助很有限。因为它不知道怎么把它们转成动作。

我现在更愿意写成这样：

修改前先看 `git status --short`，识别用户已有改动，不回滚无关文件。
前端改动至少运行 lint；后端改动至少运行类型检查或定向测试。
无法验证时，在最终回复里说明原因和剩余风险。
涉及删除、发布、系统代理、证书、强推等操作，先请求用户确认。

这就不是态度了，是可执行步骤。

写作规则也是一样。

不要只写：

文章要像人写的。

而要写：

先写真实场景，再写方法论。
避免模板标签，比如“核心目标”“转化钩子”。
技术判断要有边界，不把个人经验写成通用定律。
公众号图文版不要长时间连续铺文字，复杂流程和收束判断处要考虑配图。

这样 Claude 起草时能用，Codex 审稿时也能用。

同一条规则最好同时包含三类信息：

第一，什么时候触发。

第二，具体怎么做。

第三，什么情况不允许。

比如高保真 UI 还原规则就应该写清楚：当任务涉及设计稿、截图、UI 重构时触发；先分析再开发；禁止只凭截图或主观判断直接写代码。

这比“认真还原设计稿”有效得多。

验证标准要写进规则里

AI 做完任务后最容易偷懒的地方，是验证。

不是它故意偷懒，而是很多规则没有告诉它：什么叫做完。

比如“修好了”不算验收标准。

“跑了相关测试，测试通过；如果测试不能跑，说明原因，并用 diff 确认修改范围没有跑偏”，这才算验收标准。

我现在会在项目规则里明确写验证矩阵。

前端项目可能是：

前端改动：运行 lint 或构建。
样式/UI 改动：检查移动端、长文本、空状态、错误状态。
设计稿还原：对照分析文档检查尺寸、颜色、资源、状态。

Rust 或后端项目可能是：

后端改动：运行 cargo check。
涉及行为变化：运行定向测试。
发布相关改动：校验产物、签名、metadata 和上传路径。

文章项目也需要验证，只是验证对象不一样：

是否像真实开发者复盘。
是否有具体技术现场。
是否有未证实的绝对结论。
是否保留了本机路径、PID、完整日志、密钥或内部实现细节。
是否有公众号图文阅读节奏。

把这些写进规则后，AI 的最终回复也会更有质量。

它不会只说“完成了”，而是会说“改了什么、验证了什么、什么没验证、剩余风险是什么”。

这才是可以继续协作的状态。

Claude 和 Codex 可以分工，不一定用同一套规则

我现在经常让 Claude 和 Codex 做不同角色。

Claude 更常作为主笔或长上下文整理者。

Codex 更常作为 reviewer，盯文件、diff、命令、权限和边界。

所以同一件事，在两个工具里的规则侧重点会不同。

写公众号文章时，我会让 Claude 侧规则更关注起草：

用第一人称写真实经历。
先让读者看到结果，再解释方法。
不要写成平台评测或官方教程。

Codex 侧规则更关注审稿：

先给 ready / not ready 判断。
检查模板感、过度工整、广告腔。
检查是否泄露内部路径、完整日志、敏感配置。
检查公众号图文节奏是否可发布。

代码项目也是一样。

Claude 侧可以更关注需求拆解、方案整理、长文档输出。

Codex 侧可以更关注改动范围、验证命令、是否触碰风险操作。

这不是说一个工具只能做一种事，而是规则要顺着工具在项目里的角色来写。

如果两个工具都用完全一样的大规则，短期简单，长期会变钝。

跨 CLI 协作时，规则还要解决交接问题

当一个项目里同时用 Claude 和 Codex，另一个问题会出现：它们怎么交接？

我不太喜欢靠聊天窗口复制粘贴。

因为任务一长，复制粘贴很容易漏版本，也很难恢复上下文。

我后来采用的是文件桥接：

.agent-bridge/
  claude-inbox/
  codex-inbox/
  shared/
  status.md

Claude 要交给 Codex 的审稿请求写成文件。

Codex 的反馈也写成文件。

长期状态写进 status.md。

这套东西本身也需要规则。

比如什么时候写 inbox，什么时候写 shared，什么结论要更新 status，哪些中间消息只是临时交接，哪些结论要沉淀进 docs 或 rules。

如果不写清楚，.agent-bridge/ 很快会变成另一个聊天垃圾堆。

我现在的处理方式是：

临时任务放 inbox。

双方都要读的产物放 shared。

长期状态放 status。

真正稳定下来的经验，再同步到 CLAUDE.md、AGENTS.md 或 rules 目录。

这样桥接目录不是替代规则文件，而是帮助规则文件持续更新。

什么时候应该更新规则

我现在判断要不要更新规则，主要看几个信号。

第一个信号：同类错误第二次出现。

一次错误可以临时纠正。第二次出现，说明它不是偶然，应该沉淀。

第二个信号：AI 每次都要问同一个问题。

比如构建命令、测试命令、目录职责、发布流程。如果这些问题每次都要问，说明项目入口没写清楚。

第三个信号：规则开始互相冲突。

比如根目录说“所有前端改动都跑构建”，但某个任务场景里构建是 watch 模式，不能按普通命令判断失败。这时就要补验证边界，不然 AI 会被规则卡住。

第四个信号：规则太长，模型抓不到重点。

这时不是继续加内容，而是拆分。入口文件只做索引，专项规则单独放。

第五个信号：出现新的高风险操作。

比如发布、证书、系统代理、删除、强推、改 CI。这些不应该只靠临时提醒，必须写进风险边界。

第六个信号：项目从单工具使用变成跨工具协作。

这时只写 CLAUDE.md 或只写 AGENTS.md 都不够。需要明确每个工具读哪里、写哪里、怎么交接、谁负责起草、谁负责审查。

规则文件不是一次写完的。

它更像代码里的测试用例。

每次踩坑，都应该问一句：这是一次性问题，还是应该沉淀成规则？

我会怎么让 CLI 帮我维护这些规则

我现在不会手动从零整理所有规则。

这件事很适合让 CLI 帮忙，但不能让它完全自动写入。

我的常用方式是：

先让 Claude 或 Codex 总结最近任务里反复出现的问题。

比如：

请根据最近三次审稿反馈，总结哪些规则应该沉淀进写作规则文件。
只给建议，不要直接改文件。

然后让另一个 CLI 审一遍：

请检查这些规则是否太宽、是否会误伤其他任务、是否包含敏感信息、是否可执行。

最后再决定写进哪里。

如果是项目总入口，就进 CLAUDE.md 或 AGENTS.md。

如果是 Claude 起草风格，就进 .claude/rules/。

如果是 Codex 审稿或验证口径，就进 .codex/rules/。

如果是长期工程决策，就进 docs/，再在规则入口里引用。

如果是命令权限或风险操作，不能和普通 Markdown 规则混在一起，要单独按工具的权限机制处理。

我还会让 CLI 做同步检查：

请对比 CLAUDE.md、AGENTS.md、.claude/rules、.codex/rules，
检查是否存在同一规则只更新了一侧、读取顺序不一致、风险边界冲突的问题。

这个检查很有价值。

因为多工具项目最容易出现的问题，就是 Claude 侧规则更新了，Codex 侧没有更新；或者根目录入口写了新规则，但 rules 的 README 没更新索引。

人很容易漏。

CLI 适合做这种重复性审查。

初始化可以很小，但要有骨架

如果一个项目还没有这些文件，我不会一上来写一大套。

最小版本可以很简单：

# AGENTS.md

## Project Context
- 这个项目是什么。
- 技术栈是什么。
- 主要目录怎么分工。

## Commands
- 开发命令。
- 构建命令。
- 测试或检查命令。

## Working Rules
- 修改前先读现有代码和用户已有改动。
- 只改与任务直接相关的文件。
- 不做无关重构。

## Verification
- 不同类型改动分别怎么验证。
- 无法验证时必须说明原因。

## Risk Boundaries
- 删除、发布、强推、证书、系统代理、外部上传等操作必须先确认。
- 密钥、真实用户数据、完整日志、内部实现细节不能写进公开内容。

CLAUDE.md 可以复用这个骨架，再加 Claude 侧的工作方式：

# CLAUDE.md

@AGENTS.md

## Claude Specific Rules
- 起草长文时先写真实场景，再提炼方法。
- 多步骤任务先给短计划，再执行。
- 需要 Codex 审查时，通过 `.agent-bridge/` 写交接文件。

如果规则开始变多，再拆目录：

.claude/rules/
  README.md
  writing.md
  collaboration.md
  engineering.md

.codex/rules/
  README.md
  review.md
  collaboration.md
  engineering.md

一开始小一点没关系。

重要的是骨架对。

不要一上来写一份 300 行大文件，然后三个月没人敢改。

规则文件真正改变的，是协作方式

现在回头看，我觉得 CLAUDE.md、AGENTS.md 和这些 rules 文件最有价值的地方，不是让 AI “更听话”。

它们真正改变的是协作方式。

没有规则文件时，我和 AI 的关系更像临时沟通：我说一段，它做一段；做错了，我再纠正。

有规则文件之后，项目本身开始有一层稳定协议：技术栈、目录职责、验证标准、风险边界、写作口吻、审稿口径，都有地方沉淀。

AI 不是每次从零理解项目。

我也不用每次从零解释自己。

当然，规则文件也不是万能的。

它不能替代人的判断，也不能保证模型永远不犯错。尤其是涉及发布、权限、安全、外部用户数据这些事情，最后仍然要有人确认。

但它能把很多低级反复纠正变少。

它能让 Claude 更稳定地起草，让 Codex 更稳定地审查，让跨 CLI 协作更容易恢复现场。

表面上，我只是在维护几份 Markdown。

实际上，我是在把每次对 AI 的纠正，变成项目里可复用、可审查、可迭代的工作协议。

这才是这些文件最值得写的原因。

干货：给大家分享一个节省Token的工具，用着还不错
https://zengate.shiyuncs.com/