我已经测试过几十种 Claude Code 配置。
真正能改变我的输出质量的，只有一个东西：一个名为 CLAUDE.md 的 60 行文件。
记得收藏本文 🔖
下面我将详细说明它的工作原理、为什么大多数人完全错过了它，以及你现在就可以直接复用的完整模板。
没人告诉你的关于 Claude Code 的事
在你的第一个提示词之前。在你写第一行代码之前。在你的会话中发生任何事情之前。
Claude 会读取一个文件。就一个。
CLAUDE.md。
它会将这个文件视为整个会话的绝对真理。不是建议。不是众多上下文之一。而是作为定义它将要做出的每一个决策的最终简报。
这就是为什么这个文件是整个 Claude Code 体系中被严重低估的变量。
大多数人根本没有这个文件。而那些有的人，也犯了两个错误之一：要么文件内容空洞无物，要么就是写了 300 行的"做一个经验丰富、一步一步思考的高级工程师"。
这两种情况都没用。原因各不相同。
为什么大多数 CLAUDE.md 文件不起作用：真正的 3 个原因
原因 1：太长
Claude 在每个会话中能可靠地遵循大约 150 到 200 条指令。这是一个结构性限制，不是态度问题。
问题在于：Claude Code 的内部系统提示已经包含大约 50 条指令。这意味着在你的 CLAUDE.md 实际拥有的 100 到 150 个指令槽位之后，Claude 就会开始丢弃指令了。
如果你的文件有 200 行，Claude 不是故意忽略你的规则。它只是机械地忘记了。你不是有合规问题。你是有注意力预算问题。
原因 2：内容质量差
大多数 CLAUDE.md 文件里填满了 Claude 自己就能推断出来的东西，或者那些无法以可衡量的方式改变其行为的东西。
"像一个高级工程师一样行事。" → Claude 已经知道这是什么意思，而且它不会锚定任何具体行为。"一步步思考。" → 这就在它的训练数据里。你在浪费一行。"编写干净且可维护的代码。" → 没有具体标准。Claude 不知道在你特定的上下文中"干净"是什么意思。
每一行不能阻止某个具体、实际错误的内容，都是在从真正重要的指令那里"偷"行。测试方法很简单：如果你删掉这一行，Claude 会不会在某个具体事情上犯错？如果答案是否定的，那这行就不该存在。
原因 3：没有层级
大多数人忽略了 Claude Code 中有三个层级的指令，而他们把所有的东西都塞进了同一个地方。
~/.claude/CLAUDE.md → 全局（适用于你所有的项目）
.claude/CLAUDE.md → 项目（与团队共享，在 git 中）
./CLAUDE.local.md → 本地（个人覆盖，被 gitignore）
全局层级用于你会在每个项目中重复的规则。项目层级用于与你项目技术和团队相关的具体上下文。本地层级用于你的个人偏好，不需要与别人共享。
正确使用这三个层级才能让每个文件保持简短、专注和真正有效。把所有东西塞进一个文件，就像建造一个漏斗，用噪音淹没你的重要规则。
构成一个有效 CLAUDE.md 的 5 个部分
在仔细研究了数十个实际生产环境中的 CLAUDE.md 文件——包括开源项目、官方 Anthropic 文档、社区最佳实践仓库——之后，我发现所有有效的文件都有以下 5 个共同部分：
第 1 部分：关键命令
Claude 在每个会话开始时，都不知道如何构建你的项目、运行你的测试、或修复 lint 错误。它会猜测。而它的猜测会浪费你很多轮次的交互。
直接告诉它要输入什么：
Commands
- Build：
npm run build - Dev：
npm run dev - Test single file：
npm test -- path/to/file - Full test：
npm test - Lint + fix：
npm run lint：fix - Type check：
npx tsc --noEmit
简短。精确。可以直接使用。
没有这部分，Claude 可能会尝试 npm test，而你的项目实际跑的是 pnpm vitest。它可能会花三轮来调试一个根本不会工作的命令问题。这三轮本可以用于真正的工作。
第 2 部分：架构地图
Claude 在每个会话开始时，对你代码库的了解为零。零。它不知道你的业务逻辑在哪里。它不知道你的组件应该是无状态的。它不知道你的 API 路由不应该包含业务逻辑。
给它一个地图：
Architecture
- src/lib/services/ → 所有业务逻辑
- src/components/ → 仅限无状态 UI 组件
- src/lib/store/ → 全局状态 (Zustand)
- src/app/api/ → API 路由，这里不要放业务逻辑
- 仅通过 Server Actions 或 API 路由访问数据库
不要详尽列出你的目录树结构。只需要让 Claude 知道东西放在哪里，更重要的是，东西不应该放在哪里。
这个区别……哪里放，哪里不该放……正是防止最常见架构错误的关键。
第 3 部分：硬性规则
这是整个文件中最重要的部分。没有例外。
这里的每一条规则都必须回答一个单一问题："如果我删掉这一行，Claude 会不会犯一个具体的错误？"
如果是 → 规则保留。如果不是 → 它就不该在这里。
高价值规则的例子：
Rules
- 绝对不要提交 .env 文件或密钥
- 所有异步调用必须用 try/catch 包裹
- 仅使用函数式组件，零类组件
- 强制提交前缀： feat：, fix：, docs：, refactor：, chore：
- 每个 PR 在合并前必须通过
npm run verify - 仅静态导出，无 SSR（部署在 S3 上）
- 重要：每次代码修改后运行类型检查
关于这个列表，需要注意两点。
首先，否定规则和肯定规则一样重要。"绝对不要提交 .env 文件"这条规则，只有等到 Claude 某天真的做了这件事，你才会觉得它显而易见。写上去。
其次，像 IMPORTANT 或 YOU MUST 这样的强调标记确实有效。
这不是道听途说。Anthropic 在他们的文档中确认过：在一条规则前加上 IMPORTANT 或 YOU MUST，可以显著提高 Claude 对该规则的遵从度。
要谨慎使用：只把它们留给那些一旦被忽略会产生最严重后果的规则。
这部分保持在 15 条规则以内。超过这个数，你就稀释了对重要规则的注意力。
第 4 部分：工作流偏好
你肯定遇到过这种情况。你让 Claude 修复一行代码。它重写了三个文件，重命名了你的函数，还重构了一个跟你的请求完全无关的类。
这部分就是为了防止这种情况：
Workflow
- 在开始复杂任务前，先问清楚问题
- 做最小改动，不要重构不相关的代码
- 每次更改后运行测试，修复失败后再继续
- 每个逻辑变更创建单独的提交，不要做一个巨型提交
- 在两个方法之间不确定时，解释两者并让我选择
这里的每一行都对应一个具体的痛点。那个改了 47 个文件的巨型提交。那个未经请求的完全重写。那个 Claude 本该问你却自己做出的架构决策。
第 5 部分：不应该放进 CLAUDE.md 的东西
这部分和其他部分一样重要。甚至可能更重要。
Do NOT include： ### 不要包含：
- 性格指令（"做一个高级工程师"）
- 你的 linter 已经能处理的格式化规则
- 将整个文档导入每个会话的 @ 导入
- 重复的规则（如果全局文件说了"运行测试"，项目文件就不要重复）
- 任何 Claude 通过自动记忆自己学到的东西
最后一点被严重低估了。
Claude 在 ~/.claude/projects/<project>/memory/ 中维护着自己的笔记。在会话中运行 /memory 可以看到它已经学到了关于你项目的哪些信息。经过几次会话后，你经常会发现 Claude 已经记录了你本来打算手动写入 CLAUDE.md 的信息。
不要把你有限的指令浪费在 Claude 已经自己记住的事情上。
完整的 60 行以内模板，随时可用
删除那些不适用于你项目的部分。目标不是填满所有内容。目标是只保留那些能切实改变 Claude 行为的内容。
对我的输出影响最大的那些行：具体成果
在测试了数十种配置之后，以下是带来最明显差异的五条规则：
重要：每次代码修改后运行类型检查 → 防止 Claude 交付带有类型错误的代码（如果不明确提示检查，它自己不会检测到）。
做最小改动，不要重构不相关的代码 → 防止对整个文件进行未经请求的完全重写。
每个逻辑变更创建单独的提交，不要做一个巨型提交 → 防止产生无法阅读、包含 47 个混杂文件的巨型提交。
在两个方法之间不确定时，解释两者并让我选择 → 防止 Claude 独自做出本应由你决定的架构决策。
仅静态导出，无 SSR → 防止 Claude 向部署在 S3 上的静态项目中添加服务器端代码。
这五条规则的共同点是：每一条都防止了一个具体的、频繁出现的、且调试成本高昂的错误。
这就是检验你 CLAUDE.md 中每一行内容的终极标准。
根本错误及其普遍的原因
人们把自己的 CLAUDE.md 当作愿望清单或者性格提示词。
"要资深。""要全面。""像专家一样思考。"
这不是简报。这是魔法思维。
你的 CLAUDE.md 应该是一个技术文档，而不是励志演讲。技术栈、命令、架构、具体规则、工作流。其他一切都是噪音，和那些真正重要的指令争夺注意力。
保持文件在 80 行以内。每当 Claude 犯了一个你本可以预防的错误时，就修订它。
最重要的是：理解这个文件会随着时间推移变成什么。
一个好的 CLAUDE.md，在第一个月就能为你节省每次会话的时间。到第三个月，它已经足够精确地捕捉了你的规范和项目技术栈，让 Claude 几乎像一个团队成员一样工作。
到第六个月，它包含了 Claude 在这个项目上犯过的每一个错误，并自动防止它们再次发生。
这个文件会增值。它会随着每一次修正而改进。它会逐渐成为你写过的最好的项目入职简报。
不是为 Claude 写的。是为你自己。
