参考资料

• Claude Code 文档
• Claude Code 安全

Claude Code（05） - CLAUDE.md 与记忆分级：给项目立规矩

读完后，你应能完成以下任务：

• 绘制“Claude Code（05） - CLAUDE.md 与记忆分级：给项目立规矩 / 为什么需要 CLAUDE.md”的关键对象与数据流，解释“回想第 03 章那个痛点：你们项目「API handler 都放 src/api/handlers/」「改完业务逻辑必须跑 pnpm test」——这些规则每次对话都重复说太累，”，并用源码位置、日志或 Trace 标注证据。
• 为“Claude Code（05） - CLAUDE.md 与记忆分级：给项目立规矩 / 放在哪、长什么样”设计正常与异常输入，验证“最常见的是放在项目根目录，文件名就叫 CLAUDE.md。”，输出首个偏差位置与回归测试结果。
• 实现“Claude Code（05） - CLAUDE.md 与记忆分级：给项目立规矩 / 记忆分级：不同规则放不同层”的最小代码或配置，检验“不是所有规则都该塞进项目根的 CLAUDE.md。”，输出命令、结果与 Diff，并说明不适用边界。

本章目标：用 CLAUDE.md 沉淀项目约定，理解记忆分级，把规则写成「可检查、可执行」。

---

一、为什么需要 CLAUDE.md

回想第 03 章那个痛点：你们项目「API handler 都放 src/api/handlers/」「改完业务逻辑必须跑 pnpm test」——这些规则每次对话都重复说太累， 忘了说它就不知道。

CLAUDE.md 就是解药：**把长期有效的项目规则写进这个文件， Claude Code 每次启动会自动加载， 当成「常驻上下文」。 **

一句话记住：临时指令写在对话里，长期规则写进 CLAUDE.md。

---

二、放在哪、长什么样

最常见的是放在项目根目录，文件名就叫 CLAUDE.md。 启动 Claude Code 时它会自动读取。 一个朴素但好用的例子：

# 项目说明
这是一个用 TypeScript + Express 写的订单服务。

# 目录约定
- API handler 统一放在 `src/api/handlers/`
- 数据模型放在 `src/models/`

# 构建与测试
- 安装依赖：`pnpm install`
- 跑测试：`pnpm test`（改完业务逻辑必须跑）
- 类型检查：`pnpm typecheck`

# 代码规范
- 所有新增 TypeScript 文件使用 2 空格缩进
- React 页面组件不超过 300 行，超过就拆 hooks 或子组件

它不需要华丽，准确 + 可执行最重要。

---

三、记忆分级：不同规则放不同层

不是所有规则都该塞进项目根的 CLAUDE.md。 按「作用范围」分级管理，更清晰也更好维护：

层级	放什么	典型例子
项目级	团队统一、随仓库走的规范	目录结构、测试命令、PR 流程
用户级	你个人的偏好，跨项目通用	「回答用中文」「注释写详细点」
本地级	只在你这台机器/这个检出生效，不提交	本机端口、个人临时配置

• 项目级：项目根 CLAUDE.md，提交进 git，全团队共享。
• 用户级：你的全局配置（~/.claude/CLAUDE.md），所有项目都生效。
• 本地级：不进版本库的本地文件，放机器相关、不该共享的内容。

还可以更细：把规则拆成多个文件（rules/code-style.md、rules/testing.md…），在 CLAUDE.md 里用 @path/to/file 导入，按需组合。

---

四、关键原则：写成「可检查、可执行」的规则

这是 CLAUDE.md 质量的分水岭。对比一下：

❌ 空泛、没法执行（它不知道怎么落地）：

- 保持代码整洁
- 做好测试
- 注意 API 设计

✅ 具体、可检查（它能照着做、你能验证）：

- 所有新增 TypeScript 文件使用 2 空格缩进
- 修改业务逻辑后必须运行 `pnpm test`
- API handler 统一放在 `src/api/handlers/`
- React 页面组件不超过 300 行，超过则拆分

判断标准：这条规则能不能被「检查对错」？ 能，就是好规则。

---

五、用导入和规则包实现跨项目复用

很多规范是跨仓库共享的（公司安全策略、前端规范）。 每个仓库重抄一遍既累又容易不一致。 Claude Code 支持：

• 在 CLAUDE.md 里用 @path/to/import 导入其他规则文件，内容会递归展开；
• 通过符号链接（symlink） 共享 .claude/rules/ 下的规则，链接会被正常解析。

于是你可以把规范做成可复用的规则包：

company-security-rules     # 公司安全策略
frontend-react-rules       # 前端 React 规范
backend-api-rules          # 后端 API 规范

每个项目只 @ 引用需要的模块。 好处：**集中维护、统一更新，多个仓库说同一套「工程语言」。 **

---

六、常见错误

错误 1：写成一篇散文 大段「我们追求优雅、注重质量……」对它没用。 要的是条目化、可执行的规则。

错误 2：什么都往项目级塞 「回答用中文」是你的个人偏好，应放用户级； 塞进项目 CLAUDE.md 会强加给所有队友。

错误 3：规则过时不更新 测试命令从 npm test 改成 pnpm test 了， CLAUDE.md 没改 → 它按旧的来。 **把 CLAUDE.md 当代码一样维护。 **

错误 4：太长太杂 几百行的 CLAUDE.md 它抓不住重点。 拆成多文件 + @ 导入，按需加载。

---

七、最佳实践

1. 从小开始，按需补充：先写最关键的几条（构建命令、目录约定），用着用着发现「又得重复说了」就补一条。
2. 每条都能被检查：写完自问「这条怎么验证对错」。
3. 分级归位：团队规范→项目级，个人偏好→用户级，机器相关→本地级。
4. 让 Claude 帮你写：可以直接说「读一遍这个项目，帮我起草一份 CLAUDE.md」，再人工校对。
5. 当代码一样维护：约定变了，第一时间更新它。

---

八、动手实践：Demo 05 · CLAUDE.md 模板与记忆分级

本 Demo 给你一份可直接抄改的 CLAUDE.md 模板， 以及一个用 @ 导入拆分规则的示例结构。

8.1 文件说明

• CLAUDE.md.example：项目根级模板，复制成 CLAUDE.md 改改就能用。
• rules/：拆分的规则文件，演示用 @ 导入复用。
  • code-style.md、testing.md

8.2 怎么用

1. 把 CLAUDE.md.example 复制为你项目根的 CLAUDE.md，按注释改成你项目的实际情况。
2. 体会「可检查、可执行」的写法：对照里面每条规则，问自己「这条能验证对错吗」。
3. 进阶：把规则拆进 rules/，在 CLAUDE.md 里用 @rules/xxx.md 导入。

8.3 也可以让 Claude 帮你生成

读一遍这个项目，帮我起草一份 CLAUDE.md，规则要可检查、可执行。

8.4 配套实践材料

以下材料已并入正文，便于阅读时直接对照和练习。

rules/code-style.md

# 代码风格规则
- 新增 TypeScript 文件使用 2 空格缩进
- 变量命名用小驼峰，常量用全大写下划线
- 单个函数不超过 50 行，超过则拆分

rules/testing.md

# 测试规则
- 每个公共函数至少 1 个正常用例 + 1 个边界用例
- 改动业务逻辑后必须运行 `pnpm test`
- 测试文件与源文件同名，后缀 `.test.ts`

九、总结

• 放在哪、长什么样：最常见的是放在项目根目录，文件名就叫 CLAUDE.md。
• 记忆分级：不同规则放不同层：不是所有规则都该塞进项目根的 CLAUDE.md。
• 关键原则：写成「可检查、可执行」的规则：这是 CLAUDE.md 质量的分水岭。
• 用导入和规则包实现跨项目复用：很多规范是跨仓库共享的（公司安全策略、前端规范）。
• 常见错误：要的是条目化、可执行的规则。
• 最佳实践：从小开始，按需补充：先写最关键的几条（构建命令、目录约定），用着用着发现「又得重复说了」就补一条。 -> 每条都能被检查：写完自问「这条怎么验证对错」。 -> 分级归位：团队规范→项目级，个人偏好→用户级，机器相关→本地级。 -> 让 Claude 帮你写：可以直接说「读一遍这个项目，帮我起草一份 CLAUDE.md」，再人工校对。