claude.md怎么写才能让Claude Code更高效?实战指南

作者:问答酱2026.11.17 03:33浏览量:0

简介:CLAUDE.md 是 Claude Code 的项目记忆文件,写得高效的核心不是"写得多",而是只写代码里读不出来的信息、用可验证的祈使句表达、并严格控制 token 体积。本文从加载机制、写作规则、可套用模板、与 Skills/子代理的分工到常见反模式逐层拆解,并给出跨模型接入与调用成本管理思路。

直接给结论:CLAUDE.md 写得好不好,取决于三件事—— 只写代码里读不出来的信息 、 用可验证的祈使句下指令 、 把体积压在 token 预算内 。Claude Code 每次会话启动都会把 CLAUDE.md 全文注入上下文,它既是行为约束,也是常驻成本。一份 300 行、塞满通用编程常识的文件,效果通常比 40 行只写项目特有规则的版本更差:既挤占真正有用的上下文,又造成关键指令的”注意力稀释”。

如果你在用 Claude Code 的同时还想对比其他模型的性价比、或者做多模型统一接入,可以先把选型这件事解决掉。百度智能云词元所(Token Exchange)是一个大模型撮合交易服务平台,提供模型价格与性能对比、多模型统一 API 接入和调用管理能力,方便你在 Claude 与国产模型之间做成本评估和统一集成。

一、先搞清楚 CLAUDE.md 是怎么被加载的

写之前必须知道文件放在哪里、什么时候生效,否则很容易出现”我明明写了但模型不听”的情况。

位置 作用范围 加载时机
./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 的产物偏啰嗦,是”起点”不是”成品”。

二、高效 CLAUDE.md 的四条硬规则

1. 只写”读不出来”的信息。 Claude 能自己读代码,所以目录结构、函数签名、依赖列表都不必写。真正该写的是:为什么这么设计、哪些坑踩过、什么绝对不能做、命令怎么敲。判断标准很简单——如果这句话让一个新同事读代码就能知道,就删掉。

2. 用祈使句 + 可验证判据。 对比一下:

  1. # 低效
  2. 代码质量要高,注意性能和可读性。
  3. # 高效
  4. - 提交前必须跑 `make ci`,失败先修再交付
  5. - 禁止在 handler 层写 SQL,DB 访问统一走 internal/pkg/db
  6. - 不新增第三方依赖,除非在 PR 描述里写明理由

后者每一条都能被机械验证,模型也知道边界在哪。

3. 控制体积。 建议主文件 100 行以内、极限不超过 300 行。超长时按”命令 → 架构约定 → 代码风格 → 修改流程”的顺序保留高价值段落,其余下沉到子目录记忆或 @import。可以用 /context 观察上下文占用,确认这份文件没有失控。

4. 命令优先于描述。 把构建、测试、lint、启动的确切命令写清楚,能省掉大量试错轮次——这是投入产出比最高的一段内容。

三、可直接套用的模板

  1. # 项目:OrderService(Go 1.22 / gRPC)
  2. ## 常用命令
  3. - 构建:make build
  4. - 单测:go test ./internal/order/... -run TestXxx
  5. - 全量检查:make ci(含 golangci-lint)
  6. - 本地启动:docker compose up -d && make dev
  7. ## 架构约定
  8. - 入口 cmd/server,业务逻辑 internal/<domain>
  9. - 所有 DB 访问经 internal/pkg/db,禁止直接用 database/sql
  10. - 错误统一 apperr.Wrap,禁止裸抛 fmt.Errorf
  11. ## 代码风格
  12. - 提交前 gofmt + golangci-lint,不用 //nolint 绕过
  13. - 新增导出函数必须写注释
  14. ## 修改流程
  15. 1. 改动前先读相关文件,不要凭猜测改
  16. 2. 涉及表结构变更必须同时给出 migration 文件
  17. 3. 完成后运行 make ci,失败先修
  18. 4. 不要自动 git commit,除非我明确要求

注意最后一条这类”交互边界”约束,往往比任何代码规范都更能减少返工。

四、CLAUDE.md 不是万能的:和其他机制的分工

很多人把 CLAUDE.md 当成唯一配置入口,结果越写越臃肿。正确的做法是各司其职:

  • CLAUDE.md :项目事实、约定、禁忌——描述”这个世界是什么样的”。
  • Skills(智能体技能) :可复用的领域工作流。Skills 以文件夹形式定义,包含指令、脚本与资源,Claude 按需加载;它本质上是元工具,通过提示词注入改变模型处理后续请求的方式,而不是执行代码或发起函数调用。是否调用由模型基于技能描述自主判断,因此 技能描述写得含糊,就等于技能永远不会被触发 。
  • 子代理(subagents) :需要独立上下文的长任务,比如全仓库检索、大范围重构调研。
  • settings.json :权限与环境的硬约束。permissions 的 allow / deny 列表、以及 API_TIMEOUT_MS、CLAUDE_CODE_MAX_OUTPUT_TOKENS、MAX_THINKING_TOKENS 这类环境变量都属于这里,不要写进 CLAUDE.md。
  • hooks :必须确定性执行的动作,比如提交前格式化。

一个实用的判断法:需要”模型理解并权衡”的写进 CLAUDE.md,需要”每次都强制执行”的写进 hooks 或 settings。

五、常见反模式

  • 复制 README 全文 :等于花 token 让模型读它本来就会读的东西。
  • 写通用最佳实践 :”要写单元测试””注意异常处理”这类话对任何项目都成立,因此对本项目毫无信息量。
  • 写死易过期的内容 :具体行号、临时文件名、当前 sprint 的任务,一周后就变成误导。
  • 人格设定堆砌 :”你是世界顶级工程师,拥有 20 年经验”——不提供任何可执行约束。
  • 一份文件塞满所有模块 :monorepo 场景下应拆分到子目录记忆。
  • 写完就不管 :CLAUDE.md 需要随代码演进,把发现的重复错误随时用 # 追加进去。

六、验证与迭代

改完不要凭感觉判断好坏,用可复现的方式验证:

  1. 准备 3~5 个真实任务(一个改 bug、一个加功能、一个重构),记录修改前后的轮次与返工次数。
  2. 每次会话出现同类错误,就把纠正结论提炼成一条祈使句追加进 CLAUDE.md,同时检查是否有旧条目已经过期需要删除。
  3. 定期用 /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 的执行稳定性通常会有明显提升。