打造完美的 CLAUDE.md：Claude Code 提效全指南

在 Claude Code 启动时，它的系统提示词已经占据了大约 50 条指令。研究表明，大语言模型（LLM）在指令总数达到 150 到 200 条时，遵循指令的能力就开始下降。这意味着你只有约 100 到 150 条指令的“额度”，来向 Claude 解释你的项目规则。

CLAUDE.md 就是用来填补这些额度的核心文件。它是一个位于项目根目录的 Markdown 文件，Claude Code 在每次对话开始时都会自动读取它。这让 Claude 具备了持续的项目上下文，无需你反复叮嘱。

然而，如果这个文件过于臃肿，它不仅会浪费 Token，还会干扰核心规则的执行。本文将讨论如何构建一个“字字珠玑”的 CLAUDE.md，以及如何随项目演进而维护它。

什么是 CLAUDE.md？

CLAUDE.md 存放的是项目的“常驻指令”，涵盖了 Claude 需要了解的方方面面：

技术栈细节
测试运行方式
编码规范与约定
不可触碰的禁区

没有它，每个会话都像是在开盲盒。你会发现自己一直在解释相同的背景，纠正相同的错误。

在 Claude Code 的上下文中，有几类文件共同分担了记忆任务：

系统	维护者	作用	加载时机
`CLAUDE.md`	开发者	定义项目规则、规范和约束	每次会话开始（全量加载）
`MEMORY.md`	Claude	记录 Claude 在会话中发现的模式和事实	每次会话开始（前 200 行）
Skills	开发者	针对特定工作流的领域知识	按需加载
Hooks	开发者	触发点执行的脚本（如 pre-commit）	特定触发点

运行 /init 命令会自动分析你的代码库并生成一个初始的 CLAUDE.md。这是一个不错的起点，但要让它真正好用，必须经过人工打磨。

文件优先级与位置

CLAUDE.md 的加载遵循从全局到具体的优先级顺序，更具体的文件会覆盖宽泛的规则：

管理策略（全局）：位于系统级目录（如 macOS 的 /Library/Application Support/ClaudeCode/），适用于机器上所有用户。
用户级别：~/.claude/CLAUDE.md，适用于你本机的所有项目，适合存放个人偏好。
项目级别：根目录下的 ./CLAUDE.md，这是最常用的，应随 Git 提交。
子目录级别：./subdir/CLAUDE.md，仅当 Claude 处理该目录下的文件时按需加载。

如果你有不希望提交到版本控制系统的个人偏好，可以创建 CLAUDE.local.md 并将其加入 .gitignore。

CLAUDE.md 应该包含什么？

一个高效的 CLAUDE.md 通常分为三层逻辑：项目是什么、为什么这么做、Claude 应该怎么做。

高信号的项目概览

开头用一两行说明项目目标和具体的技术栈版本。虽然 Claude 能通过分析代码推断，但直接告诉它“我们使用的是 Next.js 15 而非 14”，能省去很多麻烦。

提供一个清晰的目录结构图，只列出关键层级：

src/
  data/        # 数据处理流水线
  models/      # 模型定义与训练逻辑
  api/         # 基于 FastAPI 的服务端点
  tests/       # 与源码同位置的测试文件 (test_*.py)

将常用命令放在代码块中。Claude 会优先执行代码块内的命令，而对正文中的描述则可能采取“即兴发挥”的态度。

架构意图与约束

如果你的项目出于某种原因选择了 SQLite 而非 Postgres，或者 API 遵循特定的分层模式，请务必写清楚。

单纯说“严禁强制推送（Force Push）”效果有限。如果解释为“严禁强制推送，因为这会重写共享历史，导致协作环境不可逆的损坏”，Claude 就能理解其背后的逻辑，从而在执行类似 git reset --hard 的操作时也会更加谨慎。

操作指南

这部分主要解决那些无法从代码中直接推断出的约定。比如 Conventional Commits 规范、特定的分支命名模式，或是某些必须在构建前运行的特殊脚本。

不要在文件中塞入语言本身的常识。例如，不需要告诉 Claude 在现代 JS 中使用 async/await，这些属于“背景噪音”，会挤占更有价值的指令额度。

编写实战：精简与聚焦

编写有效的指令

具体性大于意图。 “编写整洁的代码”是废话，“使用 2 空格缩进，不使用分号，使用单引号”才是指令。

对每一行指令进行压力测试：“如果删掉这一行，Claude 会出错吗？” 如果答案是否定的，那就删掉它。目标是将文件控制在 60 到 200 行之间。文件越短，指令的遵循度越高。

应该剔除的内容

代码风格偏好：缩进、导入排序等应交给 ESLint 或 Prettier。用昂贵的指令额度去做 Linter 能免费完成的事，是非常不划算的。
冗长的文档：不要粘贴完整的 API 文档，提供链接或告知文件名即可。
负面约束：避免只说“不要做什么”。正确做法是“不要使用 X，请改用 Y”。

示例对比：从臃肿到精炼

优化前：包含大量“编写高质量代码”、“遵循最佳实践”等空洞建议。
优化后：只保留具体的构建命令、特定的测试框架调用方式，以及项目中特有的陷阱（如“先启动 Redis 容器再运行测试”）。

团队协作与规模化管理

当项目涉及多人协作或属于单体大仓（Monorepo）时，单一的 CLAUDE.md 会变得难以维护。

模块化规则

可以将规则拆分到 .claude/rules/ 目录下，按主题命名（如 testing.md, api-design.md）。Claude 会递归发现这些文件。

你甚至可以使用路径感知的加载方式。在规则文件顶部添加 YAML Frontmatter：

---
paths:
  - "src/api/**/*.ts"
---
# 这里是 API 相关的特定约定

这样，当 Claude 在处理前端文件时，就不会被后端的数据库迁移规则干扰。

引用而非嵌入

对于大型架构文档，不要直接嵌入，而是告诉 Claude：“关于迁移流程，请参考 docs/migrations.md”。Claude 在需要时会主动阅读，而不是在每次会话开始时强制加载。

持续维护：避免规则腐化

项目在演进，规则也会过时。两个信号说明你的 CLAUDE.md 需要维护了：

Claude 为忽视已有的指令道歉：说明该指令表达模糊，需要重写。
Claude 在多个会话中重复犯错：说明文件太长，指令被模型过滤掉了，需要精简。

一种低成本的维护习惯是每隔几周对 Claude 说：“审查当前的 CLAUDE.md 并提出改进建议”。它能发现指令间的冲突或逻辑重叠。

总结

CLAUDE.md 是 Claude Code 项目中权重最高的文件。它不应该是一个随手抓取的垃圾桶，而应该是一份精炼的项目路线图。

最好的行动方案是：现在就运行 /init 生成一个基准版本，然后果断删掉那些显而易见的废话，只保留那些真正能防止 Claude “翻车”的关键信息。保持在 60 行以内是一个极佳的起点。

关于

关注我获取更多资讯

📢 公众号

💬 个人号