你的 CLAUDE.md 可能太长了（这就是它不起作用的原因）

这是一个在采用 AI 编程智能体的团队中不断上演的模式：一位开发者发现 Claude 违反了某条规则，于是他们在 CLAUDE.md 中添加了一个更清晰的版本。Claude 违反了另一条不同的规则，于是他们也把那条加上。几周后，这个文件达到了 400 行，而 Claude 忽略的规则比以往任何时候都多。解决方案反而让问题变得更糟。

发生这种情况是因为指令文件的一个基本属性，而大多数开发者从未将其内化：超过一定规模后，添加更多指令会导致模型遵循的指令变少。 正确编写指令文件与其说是追求完整性，不如说是进行无情的筛选 —— 知道该包含什么、该删除什么，以及如何构建其余部分。

为什么指令文件会存在

像 Claude Code 这样的 AI 编程智能体是无状态的。每个会话开始时，它们都没有先前会话的记忆，不了解你的项目惯例，也不了解你团队的偏好。CLAUDE.md 文件（或围绕其他工具构建的智能体系统中的 AGENTS.md）是弥补这一差距的机制 —— 它在每次对话开始时被读取，为模型提供无法仅从代码中推断出的持久上下文。

这听起来很简单，但在智能体处理这些文件的方式中存在一个关键限制。Claude Code 的系统提示词已经包含了大约 50 条关于智能体应如何表现的内置指令。对前沿模型的研究表明，在合规性开始下降之前，它们能够可靠地遵循大约 150 到 200 条指令。简单的算术：如果系统默认使用了 50 条，那么在开始失去遵循度之前，你还有大约 100-150 条的预算。

现实中大多数 CLAUDE.md 文件很容易就超出了这个预算。数据库模式解释、每个环境变量的列表、公司的通用编码哲学、仅适用于某个服务而不适用于另一个服务的规则 —— 这些内容累积得很快。

还有第二个限制，虽然不太明显但同样重要。Claude Code 附带了一个系统提醒，明确告诉模型：“此上下文可能与你的任务相关，也可能不相关。除非与你的任务高度相关，否则你不应回应此上下文。” 这不是 Bug 或疏忽。它是故意的 —— 一个将每条指令都视为始终适用的模型，其效用会大打折扣。但这意味着那些仅在某些时候相关的指令经常会被忽略，即使你希望它们被应用。

指令溢出问题

上下文腐烂（Context rot）是一个已被记录的现象：随着上下文窗口的填满，模型输出质量会显著下降。这种影响在达到技术上的 Token 限制之前就会显现。对于编程智能体来说，失败模式尤其隐蔽 —— 模型不会崩溃或报错。它只是开始降低埋藏在上下文深处的指令的优先级，生成看起来合理但微妙地违反了你费心建立的惯例的代码。

如果你曾遇到过尽管 CLAUDE.md 明确规定使用 ES 模块，但 Claude 仍自信地使用 CommonJS 的 require()，那么你已经经历过这种情况了。规则就在那里，只是被挤出去了。

典型的反应 —— 添加更多规则，或强调现有规则 —— 会让情况变得更糟。你添加的每条指令都会挤占原有指令的预算。一个 500 行的 CLAUDE.md 并不能给模型提供 500 行的指导。它给模型提供的是 500 行的噪声，模型会从中选择它认为与当前任务最相关的任何内容。

到底什么该出现在指令文件中

判断某样东西是否属于 CLAUDE.md 的测试标准非常严格：删除这一行是否会导致 Claude 犯下它原本不会犯的错误？

如果答案是“否” —— 如果 Claude 无论如何都会做正确的事 —— 那么这一行就该删掉。如果答案是“有时” —— 如果指令仅适用于某些任务 —— 那么它也不应该出现在根文件中。

什么通过了测试：

• 模型无法通过阅读代码发现的命令：你特定的测试运行器调用、单体仓库（monorepo）的准确构建命令、开发服务器运行的端口
• 偏离语言默认值的代码风格规则：如果你在习惯使用空格的语言中使用了 Tab，请说明；如果你使用的是标准风格，请跳过它
• 测试偏好：运行单个测试文件，而不是整个测试套件；在此代码库中，比起 Mock 更倾向于集成测试
• 从结构上不明显的仓库惯例：分支命名、PR 描述要求、提交消息格式
• 已知陷阱：必需的环境变量、不明显的内部服务依赖、如果跳过会悄无声息失败的初始化步骤
• 与框架分歧的架构决策：你刻意打破模型原本会遵循的惯例的地方

什么没通过测试且应该被移除：

• 任何可以从代码中推导出的内容：如果模型可以读取文件并推断出来，就不要在 CLAUDE.md 中解释它
• 标准语言惯例：不要告诉 Claude 编写可读的代码或使用有意义的变量名
• Linter 强制执行的代码风格规则：“永远不要让 LLM 去做 Linter 的工作” —— 如果 Prettier 或 ESLint 能捕获它，请将其从指令文件中移除，并将其作为 Hook 运行
• 特定任务的上下文：当 Claude 在修复 CSS Bug 时，数据库模式详情是无关紧要的
• 解释和教程：指令文件是配置，而不是文档

对于大多数项目来说，一份精心策划的 CLAUDE.md 应该在 40-80 行之间。100 行以下是一个合理的上限。如果你的文件更长，这是一个信号，表明出了问题 —— 不是你需要更多行，而是你需要将内容推送到其他地方。

渐进式披露：正确的架构

解决“指令多到放不下”问题的正确方案不是写一个更长的文件，而是一个不同的架构。渐进式披露（Progressive disclosure）意味着将特定任务的指南存储在单独的文件中，模型可以根据需要加载这些文件，从而使根指令文件保持为一个简洁的索引。

一个典型的结构如下所示：

CLAUDE.md                        ← 根指令文件，少于 80 行
agent_docs/
  building_the_project.md        ← 在构建或运行时调用
  running_tests.md               ← 在编写或运行测试时调用
  code_conventions.md            ← 在编写新代码时调用
  service_architecture.md        ← 在思考服务架构时调用
  database_schema.md             ← 仅在处理数据相关任务时调用

根文件 CLAUDE.md 通过名称引用这些文件，但不嵌入它们的内容。当 Claude 开始一个与构建相关的任务时，它会加载 building_the_project.md。当它在修复 UI 错误时，该文件根本不会出现在上下文（context）中。

这种架构同时解决了两个问题。根指令文件保持足够紧凑，使得其中的每一行都具有分量。特定任务的指南虽然存在且可用，但只有在实际相关时才会消耗上下文。

Claude Code 通过导入语法（@path/to/file）和技能系统（skills system）来支持这一点，该系统可以按需加载特定领域的指南。无论你是显式使用这些功能，还是依赖模型的判断来提取引用的文件，同样的模式都适用。

生态系统：CLAUDE.md、AGENTS.md 及其他

CLAUDE.md 是 Claude Code 特有的。更广泛的生态系统已经趋向于将 AGENTS.md 作为一种格式中立的替代方案。截至 2026 年初，已有超过 18 种工具原生解析 AGENTS.md，包括 GitHub Copilot、Cursor、Windsurf、Zed、Google Jules、Devin 和 Aider——而 Claude Code 是一个明显的例外，它仍在使用自己的格式。

对 2,500 多个使用 AGENTS.md 的仓库进行的分析发现，表现最好的文件具有一致的结构：涵盖六个核心领域，命令放置在靠前的位置，并且比起解释更倾向于使用示例。一个展示预期风格的具体代码片段，其效果始终优于三段描述文字。

表现良好的文件字数中位数在 300 到 350 字左右——短到可以在两分钟内读完，长到足以涵盖基础要点。超过 500 字的文件收益递减。超过 1,000 字的文件与智能体的表现呈负相关。

在表现顶尖的仓库中出现的一种模式是，采用三级边界框架来定义智能体应该做和不该做的事情：

• 务必执行（Always do）：安全、受鼓励的操作，智能体无需询问即可执行
• 先询问（Ask first）：具有副作用或现实后果、需要确认的操作
• 禁止执行（Never do）：硬性限制，并简要说明原因

这种明确的分类很有帮助，因为它承认了“绝不提交密钥”和“在推送到 main 分支前询问”是不同类型的限制——前者是硬性的安全规则，后者是工作流偏好。将它们混在扁平的列表中会削弱两者的重要性。

像对待代码一样对待你的指令文件

大多数臃肿的 CLAUDE.md 文件背后的运营本能是“文档文化”：如果出了问题，就把它记录下来，以免再次发生。对于指令文件来说，这是错误的。仅仅因为 Claude 曾经做错过某事就增加一条规则，并不意味着这条规则应该永久留在文件中——这意味着你应该诊断 Claude 为什么 会这样做。

如果 Claude 因为文件太长而忽略了某条规则，那么增加另一条规则并不能解决根本问题。如果 Claude 因为缺少钩子（hook）而犯错，那么修复方案应该是增加一个钩子，而不是一条指令。如果 Claude 因为提示词模糊而做错事，那么修复方案应该是优化提示词。

指令文件的修剪方式应该与修剪死代码（dead code）相同。在评审时可以问以下问题：

• 如果不加这条指令，Claude 也会遵守这条规则吗？如果是，删除它。
• 这条规则是否仅适用于某些任务？如果是，将其移至专门的文件中。
• 是否可以用确定性工具（deterministic tool）来强制执行？如果是，使用工具。
• 在过去的一个月里，Claude 违反过这条规则吗？如果没有，考虑它是否仍然相关。

行之有效的工作流程是：保持精简，观察 Claude 在哪里犯错，只有当规则能够防止真正的失败时才添加规则。一个从实际失败中自然增长的指令文件，往往比一个为了涵盖所有情况而预先编写的文件既短又有效。

还有一个战术层面的注意事项：注意你把最重要的规则放在文件中的什么位置。模型具有近因效应（recency bias）——出现在长上下文末尾的指令往往权重更高。对于一条总是被遗漏的关键规则，尝试将其移动到文件末尾，而不是添加强调标记。

随时间产生的复利价值

一个好的指令文件会产生复利。每一条经过妥善选择并被遵守的规则，都是你再也不必去纠正的错误。每一条被修剪掉的无用规则，都是为那些重要的规则收回的上下文预算。

那些从 AI 编程助手（AI coding agents）中获益最多的团队，会将他们的指令文件视为高价值的配置，需要像对待生产代码一样精心维护。他们会定期评审，在项目变更时更新，并通过观察更改后智能体的行为是否真的发生了转变来进行测试。

而那些获益最少的团队则将其视为文档——默认全面，从不修剪，任其增长，直到模型无法再可靠地读取它们。

讽刺的是，经过妥善选择的少量指令反而能产生更高的合规性。让 Claude 遵守你规则的途径并不是编写更多的规则，而是无情地筛选哪些规则才真正值得被写下来。