上下文与 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 读取该子目录的文件时才会注入，不影响其他模块的上下文开销。