上下文与 CLAUDE.md

这一课你将能做到

1. 用 /init 生成项目级 CLAUDE.md，并写出「命令、风格、禁忌」三类高价值内容
2. 理解企业级 → 用户级 → 项目级 → 子目录级四层记忆的加载规则，正确放置团队规范与个人偏好
3. 用 # 快速记忆、@ 导入文件、子目录 CLAUDE.md 三种手段按需注入上下文，避免上下文膨胀

为什么要学

每次新会话都要重复「我们用 pnpm」「测试跑 mvn test」「不要动 generated 目录」？这说明你在手动搬运本该自动加载的上下文。CLAUDE.md 就是 Claude Code 的「项目记忆」：每次会话自动注入，让它在开口干活前就知道你的规范。官方经验里，一份好的 CLAUDE.md 对输出质量的提升立竿见影，也是团队内推广 agent 的第一步——规范进文件，而不是进群聊。

人话：CLAUDE.md 是你写给「新同事」的入职手册。写得越可执行（命令、示例、禁忌），这位同事上手越快；写成企业文化和长篇散文，它只会翻个白眼。

先建立图像

四层记忆，从全局到局部：

┌─ 企业策略级（IT 统一下发，管理所有员工）
│   └─ 用户级 ~/.claude/CLAUDE.md（你的个人偏好，跨项目生效）
│       └─ 项目级 <项目根>/CLAUDE.md（进 git，全团队共享）★ 最常用
│           └─ 子目录级 <子目录>/CLAUDE.md（读到该目录文件时按需加载）

项目级 CLAUDE.md 的典型骨架：

# 项目：订单中心（Spring Boot 3 + MySQL 8）

## 常用命令
- 构建：mvn clean package -DskipTests
- 单测：mvn test -pl order-service
- 本地起服务：docker compose up -d

## 代码风格
- 遵循 Alibaba Java 规约；DTO 用 record；禁止在 Controller 写业务逻辑

## 禁忌
- 不要修改 target/ 与 *.generated.java
- 数据库变更必须走 flyway 脚本，禁止直接改表

跟着做

步骤 1：用 /init 生成第一版

在项目根目录启动会话，输入：

/init

它会扫描项目（构建脚本、目录结构、README），自动生成 CLAUDE.md 初稿。别直接收货，接着做第 2 步。

步骤 2：人工修订——只留三类内容

按「新同事入职手册」标准修订，优先保留：

1. 可执行命令：构建、测试、lint 的确切命令（它自己猜命令最浪费 token）。
2. 隐性约定：分支命名、commit 格式、哪些目录是生成物不许动。
3. 禁忌清单：踩过的坑，如「接口返回统一用 Result 包装」。

删掉：项目背景故事、空泛要求（"代码要优雅"）、超过一屏的内容。

步骤 3：用 # 快速追加记忆

会话中随时输入（注意以 # 开头）：

# 单测统一用 JUnit5 + AssertJ，不要用 JUnit4

它会把这条写入 CLAUDE.md（弹出选择写入哪个层级），长期生效。

步骤 4：用 @ 导入外部文档

CLAUDE.md 支持 import 语法，把大文档拆出去按需引用：

详细接口规范见 @docs/api-conventions.md
个人环境说明见 ~/.claude/my-env.md

@ 后跟相对或绝对路径，加载时递归展开（有最大深度保护）。

步骤 5：给大仓库加子目录记忆

在 order-service/ 下放一个专属 CLAUDE.md：

# order-service
- 订单状态机定义在 OrderStatus.java，改状态流转必须先看它
- 本模块单测：mvn test -pl order-service

只有当 Claude 读取该子目录的文件时才会注入，不影响其他模块的上下文开销。

步骤 6：验证生效

/clear 后问：这个项目的单测命令是什么？禁忌有哪些？

它应直接引用 CLAUDE.md 内容作答。随时用 /memory 编辑各级记忆文件。

讲清楚要点

1. 越具体越好，越短越好：✅「commit message 用 conventional commits，如 feat(order): 支持批量导出」；❌「提交信息要规范」。可执行、可验证的条目才有价值。
2. 项目级进 git，个人偏好进用户级：团队共性规范放 <项目>/CLAUDE.md 共享；个人习惯（如「回答用中文」）放 ~/.claude/CLAUDE.md，别强加给同事。
3. 子目录记忆是按需加载的：不是启动即注入，而是工作到相关目录时才生效——大仓库分治的关键机制。
4. CLAUDE.local.md 已不推荐：早年的个人本地记忆文件方案已被官方标记为弃用，个人差异用「用户级文件 + @ 导入」表达。
5. 记忆是提示词不是配置：它影响模型行为但不是硬约束。硬约束（禁止执行某命令）要用权限规则与 Hooks 实现，两套机制互补。

你可能会懵的地方

• CLAUDE.md 和 README 有什么区别？ README 写给人看，偏介绍；CLAUDE.md 写给模型看，偏操作——命令、规则、禁忌。可以部分复用内容，但组织方式不同：模型需要的是可执行指令。

• 四层同时存在时听谁的？ 各层都会加载、内容叠加；冲突时更靠近项目的层级在实践中更具优先性（项目级覆盖用户级惯例）。同时加载意味着每层都会占用上下文，层级越多越要克制。

• CLAUDE.md 多大合适？ 经验值：一屏以内（几十行）为佳。超长会导致每次请求都携带大量固定 token，还稀释重点。大文档用 @ 拆分按需导入。

• 能让 Claude 帮我维护 CLAUDE.md 吗？ 能，这是官方推荐用法：纠正它某次错误后，说「把这条教训写进 CLAUDE.md」；或定期说「根据最近的会话，优化 CLAUDE.md」。

• Monorepo 怎么组织？ 根目录放全局规范（构建、通用禁忌），每个服务/包目录放自己的 CLAUDE.md（模块命令、模块约定），靠按需加载保持上下文干净。

错法对照

错法	问题	正解
把 README、需求文档全文塞进去	上下文爆炸，重点稀释	只留操作型条目，其余 @ 导入
写「代码要优雅、注释要完善」	模型无从执行	写具体规约与示例
团队规范只存在自己脑子里	每个会话重复口头约定	提炼进项目级 CLAUDE.md 提交 git
把密钥、内网地址写进 CLAUDE.md	随每次请求发送，且可能随 git 泄露	敏感信息用环境变量与本地文件
出了问题怪模型笨	多半是它不知道规矩	先问：CLAUDE.md 里写了吗？

卡点急救

1. 记忆没生效：确认文件在正确层级与路径；/memory 打开检查；新会话才加载，改完用 /clear 重启上下文验证。
2. 上下文频繁爆满：CLAUDE.md 过大或 @ 导入了巨型文档；瘦身 + 子目录分治。
3. 它经常违反某条规范：措辞改为命令式并给反例；仍无效说明是硬约束问题，改用权限规则或 Hooks 兜底。

面试常问

• 如何设计项目的 CLAUDE.md？ 原则：操作型内容优先（命令/约定/禁忌）、篇幅克制、可执行可验证、团队共性进项目级、个人偏好进用户级、大仓库用子目录按需加载，并用 @ 导入管理长文档。它是持续演进的活文档。

• 什么是上下文工程（context engineering）？ 相对 prompt engineering 的进阶概念：不只是单条提问怎么写，而是系统性地决定「模型在每次请求时能看到什么」——记忆文件、工具返回、检索内容、历史压缩策略。Claude Code 的 CLAUDE.md 层级、子目录按需加载、/compact 都是上下文工程的具体实现。

• CLAUDE.md 与权限/Hooks 的边界？ CLAUDE.md 是软约束（引导模型倾向），权限系统与 Hooks 是硬约束（机制上禁止/强制）。规范类写记忆，安全类上硬约束，二者配合。

自测三问

1. 四层记忆分别放在什么路径？各自解决什么问题？
2. 哪三类内容最值得写进 CLAUDE.md？哪类内容该删？
3. 子目录级 CLAUDE.md 何时被加载？这对大仓库意味着什么？

小结一句话

CLAUDE.md 是项目记忆的分层体系：命令、约定、禁忌写进项目级，偏好进用户级，大仓库靠子目录按需加载——写好它，等于给每个新会话配了一位读过入职手册的工程师。

延伸

• 记忆管理官方文档
• 下一课：权限与安全——用 allow/ask/deny 规则与权限模式为 agent 划定边界，敢放权、不失控。