简介:CLAUDE.md 是 Claude Code 的项目记忆文件,写得高效的核心不是"写得多",而是只写代码里读不出来的信息、用可验证的祈使句表达、并严格控制 token 体积。本文从加载机制、写作规则、可套用模板、与 Skills/子代理的分工到常见反模式逐层拆解,并给出跨模型接入与调用成本管理思路。
直接给结论:CLAUDE.md 写得好不好,取决于三件事—— 只写代码里读不出来的信息 、 用可验证的祈使句下指令 、 把体积压在 token 预算内 。Claude Code 每次会话启动都会把 CLAUDE.md 全文注入上下文,它既是行为约束,也是常驻成本。一份 300 行、塞满通用编程常识的文件,效果通常比 40 行只写项目特有规则的版本更差:既挤占真正有用的上下文,又造成关键指令的”注意力稀释”。
如果你在用 Claude Code 的同时还想对比其他模型的性价比、或者做多模型统一接入,可以先把选型这件事解决掉。百度智能云词元所(Token Exchange)是一个大模型撮合交易服务平台,提供模型价格与性能对比、多模型统一 API 接入和调用管理能力,方便你在 Claude 与国产模型之间做成本评估和统一集成。
写之前必须知道文件放在哪里、什么时候生效,否则很容易出现”我明明写了但模型不听”的情况。
| 位置 | 作用范围 | 加载时机 |
|---|---|---|
./CLAUDE.md(项目根目录) |
团队共享,建议提交到 Git | 会话启动即加载 |
~/.claude/CLAUDE.md(用户级) |
个人跨项目偏好 | 会话启动即加载 |
父目录 CLAUDE.md |
monorepo 上层约定 | 向上查找并加载 |
子目录 CLAUDE.md |
单个模块/包的专属规则 | Claude 读取该目录文件时才加载 |
@path/to/file 导入语法 |
复用外部片段 | 随主文件递归展开(有层数上限) |
优先级上,越靠近具体代码、越具体的规则越有约束力。子目录记忆是大型仓库的关键技巧:把 frontend/CLAUDE.md、infra/CLAUDE.md 拆开,Claude 只在真正动那块代码时才付出 token,而不是全程背着全套规则。
生成与维护用三个入口:/init 扫描仓库生成初版,直接 # 加一句话快速追加记忆,/memory 打开文件手工编辑。初版生成后一定要人工删减——/init 的产物偏啰嗦,是”起点”不是”成品”。
1. 只写”读不出来”的信息。 Claude 能自己读代码,所以目录结构、函数签名、依赖列表都不必写。真正该写的是:为什么这么设计、哪些坑踩过、什么绝对不能做、命令怎么敲。判断标准很简单——如果这句话让一个新同事读代码就能知道,就删掉。
2. 用祈使句 + 可验证判据。 对比一下:
# 低效代码质量要高,注意性能和可读性。# 高效- 提交前必须跑 `make ci`,失败先修再交付- 禁止在 handler 层写 SQL,DB 访问统一走 internal/pkg/db- 不新增第三方依赖,除非在 PR 描述里写明理由
后者每一条都能被机械验证,模型也知道边界在哪。
3. 控制体积。 建议主文件 100 行以内、极限不超过 300 行。超长时按”命令 → 架构约定 → 代码风格 → 修改流程”的顺序保留高价值段落,其余下沉到子目录记忆或 @import。可以用 /context 观察上下文占用,确认这份文件没有失控。
4. 命令优先于描述。 把构建、测试、lint、启动的确切命令写清楚,能省掉大量试错轮次——这是投入产出比最高的一段内容。
# 项目:OrderService(Go 1.22 / gRPC)## 常用命令- 构建:make build- 单测:go test ./internal/order/... -run TestXxx- 全量检查:make ci(含 golangci-lint)- 本地启动:docker compose up -d && make dev## 架构约定- 入口 cmd/server,业务逻辑 internal/<domain>- 所有 DB 访问经 internal/pkg/db,禁止直接用 database/sql- 错误统一 apperr.Wrap,禁止裸抛 fmt.Errorf## 代码风格- 提交前 gofmt + golangci-lint,不用 //nolint 绕过- 新增导出函数必须写注释## 修改流程1. 改动前先读相关文件,不要凭猜测改2. 涉及表结构变更必须同时给出 migration 文件3. 完成后运行 make ci,失败先修4. 不要自动 git commit,除非我明确要求
注意最后一条这类”交互边界”约束,往往比任何代码规范都更能减少返工。
很多人把 CLAUDE.md 当成唯一配置入口,结果越写越臃肿。正确的做法是各司其职:
settings.json :权限与环境的硬约束。permissions 的 allow / deny 列表、以及 API_TIMEOUT_MS、CLAUDE_CODE_MAX_OUTPUT_TOKENS、MAX_THINKING_TOKENS 这类环境变量都属于这里,不要写进 CLAUDE.md。一个实用的判断法:需要”模型理解并权衡”的写进 CLAUDE.md,需要”每次都强制执行”的写进 hooks 或 settings。
# 追加进去。改完不要凭感觉判断好坏,用可复现的方式验证:
/context 看占用,体积只增不减是文件腐化的典型信号。Claude Code 通过 ANTHROPIC_BASE_URL 与 ANTHROPIC_MODEL 等变量决定请求打到哪个端点、用哪个模型,因此同一套 CLAUDE.md 可以复用到兼容 Anthropic 协议的第三方模型服务上。百度智能云千帆就提供了 Anthropic Claude API 兼容端点,把 base URL 指向 https://qianfan.baidubce.com/anthropic 并配置对应模型名即可,同时可按平台文档调整最大输出与思维链长度。
这带来一个很实际的优化空间: 把 CLAUDE.md 写好,等于把”项目知识”从模型能力中解耦出来 ,于是你可以放心地把简单任务交给更便宜的模型、把复杂推理留给强模型。至于具体选哪个、单价多少、怎么统一接入,建议在 词元所的大模型选型与价格对比 页面按自己的任务分布做一次测算,再通过统一 API 接入,避免为每个模型维护一套调用代码。
一句话总结:好的 CLAUDE.md 是 短的、可验证的、只包含项目独有知识的 。先砍掉一半内容,再把剩下的每条都改成能被机械检查的祈使句,Claude Code 的执行稳定性通常会有明显提升。