规则越多, Agent 反而更容易跑偏 该留该删? 一套方法理清 CLAUDE.md 和 AGENTS.md 先收藏整理项目时直接照着改如果你长期使用 Claude Code、Codex 或其他编程 Agent有一件事的回报率非常高把项目里的长期指令写好。在 Claude Code 里这个入口叫 CLAUDE.md在 Codex 里它叫 AGENTS.md。它们不是同一个文件也不能简单理解成“换了个名字”但解决的是同一类问题在 Agent 开始工作前先告诉它这个项目有哪些长期有效、不能靠读代码猜出来的约定。写好之后你不必每次开新对话都重新解释这个项目为什么不能直接改数据库、价格应该从哪里更新、改完支付流程要检查哪些页面、什么条件才算完成。但这里也有一个很常见的误区很多人把它写成了项目百科全书。教程只解决三个问题哪些内容真的值得写进去一条规则应该放在哪一层文件越来越长以后怎么持续维护最后我会用一份 /init 草稿做完整示范哪些删除哪些下沉到子目录哪些移到 Skill最后的文件长什么样。先搞清楚它们到底是什么你可以把 CLAUDE.md 和 AGENTS.md 理解成“Agent 开工前要读的项目约定”。它们适合保存会反复影响工作的长期信息比如这个项目必须遵守的业务规则团队固定的开发与验证方式修改一处时容易漏掉的联动关系完成任务前必须达到的验收标准遇到特定问题时应该去哪里找权威资料它们不适合保存随手就能从代码里看到的事实也不应该被当成强制安全机制。这些文件会进入 Agent 的上下文但它们仍然是“指令”不是程序级约束。模型可能误解、忽略或在规则冲突时选错。如果某件事绝对不能发生例如密钥不能提交、生产数据库不能被误删就应该用权限、Hook、测试、Lint 或 CI 来强制拦截而不是只写一句“禁止这样做”。需要 Agent 理解并判断的写进指令文件绝对不能违反的用程序机制兜底。CLAUDE.md 和 AGENTS.md不要混为一谈两者概念相似但原生加载方式不同。Claude Code 还支持项目根目录下的 CLAUDE.local.md适合保存只属于你、又不想提交给团队的项目偏好。记得把它加入 .gitignore。Codex 则支持 AGENTS.override.md。在同一层目录里只要存在非空的 AGENTS.override.mdCodex 就会优先使用它而不是这一层的 AGENTS.md。它更像一个明确的覆盖文件。局部规则应该放在对应目录但还要确认当前工具会在这次任务中加载该目录的规则。例如一个仓库同时包含 React 前端和 Python 后端textproject/ ├── AGENTS.md # 全项目共同规则 ├── frontend/ │ └── AGENTS.md # 只管前端 └── backend/ └── AGENTS.md # 只管后端Claude Code 也可以用类似的嵌套方式放置 CLAUDE.md。如果某条规则只和前端有关就不要塞在项目根目录里让后端任务每次也跟着读。两种工具的触发方式不同。Claude Code 读取子目录文件时会按需加载嵌套的 CLAUDE.mdCodex 则按本次运行的当前工作目录构建 AGENTS.md 加载链。要让 frontend/AGENTS.md 生效应从 frontend/ 启动任务或把 Codex 的工作目录设到该目录。从仓库根目录启动 Codex并不会因为它后来修改了前端文件就自动追加这份嵌套规则。第一份文件怎么建最省事的起点是 /init。进入项目目录并启动对应工具后text/initClaude Code 会生成一份初始 CLAUDE.mdCodex CLI 也可以用 /init 生成起始的 AGENTS.md。自动生成的版本通常会包含项目用途、技术栈、目录结构、启动命令、测试命令和代码规范。它很适合作为草稿但不适合不加检查地直接使用。Agent 能读代码。如果框架名称就在 package.json目录结构抬眼就能看到测试命令已经写在 README那么把这些内容再复制一遍价值很低。它不仅占用上下文还会制造第二份事实来源。半年后代码改了、指令文件没改原本的“帮助”就会变成误导。所以/init 之后不要立刻开始加内容。先做减法。做减法每一条都问三个问题检查自动生成的内容或者清理一份已经很长的旧文件时对每一条规则依次问1. Agent 能不能很快从项目里找到能找到就优先删掉。技术栈、普通目录结构、已经写在 README 里的命令通常都属于这一类。真正值得保留的是无法仅凭代码可靠判断的隐性知识例如数据的唯一来源、历史兼容字段的真实含义或者指定的沙箱测试账号。2. 大多数任务都会用到吗不是就往更近的目录放或者改成按需加载的规则。例如视口检查只和前端有关就应该放进 frontend/ 下的指令文件而不是让后端任务也处理它。Claude Code 还支持 .claude/rules/ 下带 paths 的路径规则。规则只在匹配到相应文件时加载适合按文件类型或目录精确生效。3. 三个月后它大概率还成立吗不稳定的信息不要伪装成长期规则。“本周临时继续使用旧 API”更适合放在任务说明、Issue 或临时计划里“所有对客价格必须含税”才适合进入长期指令。如果确实需要保留临时约束至少写清楚失效条件而不是留一句没有期限的“暂时”。经过这三问/init 生成的内容通常会被删掉不少。这不是损失。指令文件的价值不取决于长度而取决于剩下的每一条是否真的能改变 Agent 的行为。做加法用五个问题提取隐性知识减法做完接下来才轮到加法。很多人卡在这里是因为一上来就纠结该分几个章节。先别管格式回答下面五个问题内容自然会出来。1. 这个项目有什么绝对不能搞错的业务规则例如所有对客价格必须含税。Agent 单靠读组件未必知道这是业务要求漏掉一次就会直接影响用户。2. 有没有固定的处理入口例如商品价格必须先改运营数据源再由同步任务写入网站。直接改网页里的数字下次同步就会被覆盖。3. 改完一个地方还有哪些地方必须联动例如会员价格调整后首页、结账页、FAQ 和通知邮件都要更新。这类关系散落在不同目录里最容易漏。4. 做到什么程度才算完成不要只写“记得测试”要写成可以验证的完成条件检查哪些视口、跑哪条命令、走完哪段业务流程。5. 遇到不确定的问题去哪里找答案指令文件不必装下所有知识只要指出品牌、退款政策等权威资料在哪里以及资料互相冲突时该怎么办。从 /init 草稿到可用文件完整走一遍假设我们在整理一个电商项目。/init 先从项目里生成了三条技术信息md# Project Guide - 项目使用 React、TypeScript 和 Tailwind CSS。 - 前端代码位于 src/测试位于 tests/。 - 使用 npm test 运行测试。团队过去踩坑后又陆续往文件里补了这些内容md- 所有面向用户的价格必须含税。 - 商品价格以 docs/pricing-source.md 记录的数据源为准不要直接修改前端常量。 - 修改会员价格时同步更新首页、结账页、FAQ 和续费邮件。 - 修改页面后检查 375px 和 1440px 两种视口。 - 修改购买流程后使用沙箱账号完成一次从下单到回调成功的完整流程。 - 发布前按照 12 步清单依次检查、构建和部署。 - 禁止把 API Key 提交到仓库。现在技术事实和隐性知识混在了一起。不要一上来润色先逐条分流整理后根目录 AGENTS.md 只剩md# 项目约定 ## 业务规则 - 所有面向用户展示的价格必须含税。 - 修改会员价格或权益时同时检查首页价格卡、结账页、FAQ 与续费通知模板。 ## 数据来源 - 商品价格以 docs/pricing-source.md 记录的数据源为准不要直接修改前端常量。 ## 完成标准 - 修改购买流程后使用沙箱账号完成一次从下单到回调成功的完整流程。 ## 安全 - 不要提交密钥仓库的密钥扫描与 CI 检查必须通过。前端自己的 frontend/AGENTS.md 只放局部规则。对 Codex记得从 frontend/ 启动任务或把工作目录设到这里md# 前端规则 - 修改响应式页面后至少检查 375px 与 1440px 两种视口。如果使用 Claude Code把相同内容分别放进对应层级的 CLAUDE.md 即可。若两种工具都用后面会讲怎么避免维护两份。最后做两次小型行为测试先让 Agent 调整会员价格看它是否主动覆盖四个联动位置再让它修改购买回调看它是否完成沙箱流程或明确说明为什么没做。测试任务一次只触发一两条规则更容易判断是哪条规则生效。让 Agent 复述文件内容证明不了这些规则真的改变了行为。内容该放哪一张表判断写指令文件最实用的能力不是文笔而是分流。发布的 12 步清单属于 Skill只有发布时才加载“API Key 不能提交”可以保留提醒但还要用密钥扫描工具、权限、Hook 或 CI 兜底。一份可直接复制的最小模板下面这份模板故意很短。不要为了填满章节而填内容没有就删掉。md# 项目工作约定 ## 必须遵守的项目约定 - [写 Agent 无法从代码直接推断的业务或架构约束] ## 固定工作方式 - [写唯一数据源、固定修改入口或必须遵循的顺序] ## 联动修改 - 修改 [A] 时同时检查 [B、C、D]。 ## 完成标准 - 完成后运行 [验证命令]。 - 涉及 [某类变更] 时额外验证 [具体场景]。 - 结束任务前逐项核对完成标准未完成的项目必须明确说明。 ## 权威资料 - 遇到 [某类问题]读取 [文件路径]。 - 如果代码、本文档与权威资料冲突先报告冲突不要自行猜测。不要写“请高质量完成”“仔细思考”“遵循最佳实践”这种无法验证的话。它们听起来正确却没有给 Agent 任何项目特有的信息。同时使用 Claude Code 和 Codex只维护一份如果团队同时使用两种工具维护两份内容相同的文件迟早会漂移。一种省维护的做法是把 AGENTS.md 设为公共规则的唯一事实来源再让 Claude Code 导入它。这尤其适合团队已经使用 Codex 或其他读取 AGENTS.md 的工具时。项目结构textproject/ ├── AGENTS.md └── CLAUDE.mdCLAUDE.md 第一行写mdAGENTS.md如果还有只适用于 Claude Code 的内容可以继续写在下面mdAGENTS.md ## Claude Code 专用 - [只适用于 Claude Code 的规则]这样团队只维护 AGENTS.md 的公共内容。Claude Code 读取这份 CLAUDE.md 时会导入 AGENTS.mdCodex 则原生读取它。也可以让 CLAUDE.md 成为指向 AGENTS.md 的符号链接但跨平台和 Windows 权限会带来额外麻烦。对大多数团队来说AGENTS.md 更直观。注意导入只是避免重复维护不会节省上下文。被导入的内容仍然会在启动时加载所以唯一事实来源也必须保持精简。写完以后先验证它真的生效很多问题不是规则写得差而是文件根本没有被加载。在 Claude Code 中运行 /context查看 Memory files 里是否出现目标文件用 /memory 查看和编辑各层级的记忆文件在 Codex 中可以让它复述当前看到的项目规则作为辅助检查。不要只相信复述结果最终仍要用具体任务验证行为。加载来源只证明 Agent 看到了文件不证明它会照做。用前面案例里的方式给它一个精确触发规则的小任务真正的验证对象是行为不是复述。维护别只增加也要修剪我自己的 CLAUDE.md 也走过这条路一开始用 /init 建立后来 Claude 每犯一次错我就补一条规则。当时每一条都有理由几个月后再看里面已经同时出现重复规则、过期流程和彼此冲突的要求。一份好的指令文件更像花园不是档案馆。维护只有两个动作新增与修剪。什么时候新增不要因为一次偶发失误就立刻加规则。更好的触发条件是同类错误重复出现同一条评审意见反复被提出某个隐性前提一旦漏掉代价很高某套固定流程已经重复执行多次Claude Code 的 /insights 可以生成本机近期会话的 HTML 报告帮助你查看常见失败点和使用模式。它适合寻找线索但报告建议仍然需要人工判断不能整批复制进 CLAUDE.md。对 Codex可以在同类错误第二次发生后让它回顾两次失败的共同原因并提出一条最小规则。先看规则是否真的具有普遍性再决定是否写入。什么时候删除至少检查四类内容代码或流程已经变化规则与真实项目不一致两条规则表达同一件事可以合并规则与其他层级、文档或工具配置冲突Agent 已经能稳定从项目中发现不值得继续常驻Claude Code v2.1.206 及以上版本的 /doctor可以检查已提交的 CLAUDE.md建议删去可从代码推导出的目录、依赖和架构概述保留陷阱、原因和非默认约定。工具建议仍然只是起点最终要以项目事实为准。你可以采用这样的维护节奏平时只记录重复出现的问题每次重要流程或架构变化后检查相关规则例如每月或每个版本周期做一次合并、删除和冲突检查工具或模型明显升级后用真实任务重新验证旧规则而不是默认它们永远有效附赠一段可以直接使用的“渐剪提示词”原视频最后提到的本质上是一段用来审计和修剪 CLAUDE.md 的提示词并不是必须安装的 Skill。它需要执行的次数不算高先保留成提示词反而更方便进入项目根目录启动 Claude Code 或 Codex把下面整段复制进去即可。这版提示词也支持 AGENTS.md默认只做审计不会直接改文件。你先看逐条建议和候选稿确认没有误删项目知识后再让 Agent 执行修改。text你现在是这个项目的长期指令审计员。请审计并精简项目中的 CLAUDE.md、AGENTS.md 及相关规则文件。 目标不是追求最短而是在不丢失关键业务知识、团队约定和安全边界的前提下得到一组短小、准确、没有冲突并且能真正改变 Agent 行为的长期指令。 ## 权限边界 - 本轮默认只读审计可以读取项目文件、配置和官方文档但不要修改、移动或删除任何项目文件。 - 先输出完整审计报告与候选稿。只有我明确确认后才能修改原文件。 - 不要执行 git commit、push、reset、checkout 等写操作。 - 不要为了缩短文件而改变原规则的业务含义。 - 不确定的信息标记为“待确认”不要猜测或自行补全。 ## 第一步确认环境与加载范围 1. 判断当前使用的是 Claude Code、Codex还是两者共用的项目。 2. 确认当前模型与版本如果环境没有提供就写“无法确认”不要猜。 3. 找出本次任务实际可能加载的全部长期指令文件包括但不限于 - CLAUDE.md - CLAUDE.local.md - .claude/CLAUDE.md - .claude/rules/**/*.md - AGENTS.md - AGENTS.override.md 4. 说明每个文件的作用范围、加载顺序以及哪些嵌套文件本次不会加载。 5. 如果项目同时使用 CLAUDE.md 和 AGENTS.md检查它们是否重复、冲突或已经通过导入建立单一事实来源。 ## 第二步核对当前官方实践 如果能够联网只查对应工具的官方资料 - Claude CodeAnthropic 官方文档 - CodexOpenAI 官方文档 重点核对 - 指令文件当前的发现与加载规则 - 官方对长度、结构、具体性和冲突的建议 - 当前模型的官方提示词指南 - 哪些内容更适合放进嵌套规则、Skill、Hook、权限、测试或 CI 记录实际查阅的页面标题和链接。不要引用搜索摘要、社区文章或凭记忆概括。若无法联网明确写出“官方实践未在线核验”然后继续完成项目事实审计。 ## 第三步从项目中核验每条规则 读取必要的代码、README、配置、脚本和项目文档判断每条指令是否与当前项目一致。只读取足以完成判断的材料不要无目的扫描整个仓库。 对每条规则检查以下问题 1. Agent 能否从代码、配置、目录或 README 中快速发现 2. 它是否属于 Agent 无法仅凭项目可靠判断的隐性知识 3. 它是否会影响大多数任务还是只影响某个目录、文件类型或特定流程 4. 它现在是否仍然成立项目中有没有相反证据 5. 它是否与其他指令重复或冲突 6. 它是否足够具体可以执行并验证 7. 它是自然语言提醒还是必须由程序强制保证的底线 8. 删除或移动它是否可能让 Agent 丢失关键背景 不要仅凭“模型现在更强”就删除规则。只有项目证据、官方实践或真实行为测试支持时才能建议删除。 ## 第四步给每条规则分类 每条规则只能给出一个主要处理结论 - 保留重要、稳定、难以自行发现而且作用范围正确。 - 改写应该保留但目前含糊、过长、不可验证或存在歧义。 - 合并与其他规则表达同一件事。 - 下沉只影响特定目录或文件应移到嵌套 CLAUDE.md、AGENTS.md 或路径规则。 - 移到文档属于大段背景知识或权威规范主指令只保留何时读取、去哪里读取。 - 移到 Skill属于很长、可重复、只在特定任务中触发的工作流。 - 交给程序兜底属于绝对不能违反的限制应由 Hook、权限、测试、代码检查或 CI 强制执行指令中可以保留一句提醒。 - 删除可快速自行发现、已经过期、纯属重复或者是“仔细思考”“遵循最佳实践”一类无法验证的空泛要求。 - 待确认现有证据不足必须由项目负责人决定。 每个结论必须提供理由和证据。不要只说“建议精简”。 ## 第五步按以下格式输出 ### A. 审计摘要 - 找到哪些指令文件 - 本次实际加载哪些文件 - 当前总行数 - 保留、改写、合并、迁移、删除、待确认各有多少条 - 最严重的三个问题 ### B. 官方核验 - 当前工具与模型 - 查阅的官方页面及链接 - 哪些现有写法已经不符合当前官方实践 - 哪些判断因为无法联网或无法确认模型而保留不确定性 ### C. 逐条审计表 表格至少包含 | 文件与位置 | 原规则摘要 | 结论 | 项目证据 | 原因 | 建议去向或改写 | 位置尽量精确到标题或行号。存在冲突时同时列出冲突规则的位置。 ### D. 迁移清单 分别列出建议移到以下位置的内容 - 嵌套指令或路径规则 - 独立项目文档 - Skill - Hook、权限、测试、代码检查或 CI 只说明应该迁移什么和为什么不要在本轮创建这些文件。 ### E. 完整候选稿 给出精简后的完整 CLAUDE.md 或 AGENTS.md不要只给 diff。 要求 - 保留原文中仍有价值的具体信息 - 使用清晰的 Markdown 标题和短条目 - 同一件事只说一次 - 规则必须具体、可执行、可验证 - 不要加入没有项目证据的新规则 - 如果两种工具共用规则明确唯一事实来源以及导入方式 ### F. 待确认问题 只列出会实质影响删改结果的问题。每个问题说明不同答案会导致哪条规则被保留、移动或删除。 ### G. 验证方案 设计 2—4 个真实的小任务每个任务只触发一到两条关键规则用来比较修改前后的实际行为。不要用“复述你读取了哪些规则”代替行为验证。 ## 完成条件 只有同时满足以下条件才算完成 - 每条现有规则都有明确去留结论 - 所有删除和迁移建议都有项目证据 - 已指出重复、冲突、过期和无法验证的内容 - 候选稿可以直接复制使用 - 没有修改任何文件 输出完毕后停止等待我确认。不要主动执行候选稿。第一次运行时我建议不要在提示词后面补一句“直接帮我改掉”。先看审计表尤其检查“删除”和“待确认”两栏。Agent 可以发现重复和过期内容但它无法替你决定没有写进代码的业务现实。确认报告没有误判后再发送text按照刚才确认的候选稿执行修改。保留一份修改前副本不要执行任何 git 写操作。修改后重新检查加载范围、重复、冲突和 Markdown 格式并汇报实际改动与尚未处理的迁移项目。如果这段提示词以后需要频繁运行再把它封装成 Skill。是否值得做成 Skill不看流程有多长只看它是不是已经成为一个反复发生、输入和输出都相对稳定的工作流。最后用这份清单检查你的文件定稿前检查这六件事[ ] 删除了能从代码、配置和 README 快速发现的事实[ ] 根目录只保留大多数任务都会用到的规则[ ] 局部规则和长流程已经移到对应目录或 Skill[ ] 高风险禁令已经有权限、Hook、测试或 CI 兜底[ ] 每条要求都具体、可执行、可验证[ ] 没有重复、冲突或已经过期的规则并已用具体任务验证行为好的 CLAUDE.md 或 AGENTS.md不是项目资料的总和而是 Agent 无法自行发现、却会持续影响正确结果的最小规则集。它不会真正“写完”。代码会变团队流程会变Agent 的能力也会变。你要做的不是不断往里加而是让它始终只保留此刻仍然值得占用上下文的内容。规则越多, Agent 反而更容易跑偏 该留该删? 一套方法理清 CLAUDE.md 和 AGENTS.md 先收藏整理项目时直接照着改