Claude Code 记忆系统与 CLAUDE.md

核心问题：AI 的"失忆症"

与 Claude 协作常见痛点：

技术栈遗忘：上次用 Fastify + TypeScript，新对话又用 Express + JavaScript
规范丢失：代码风格、团队约定每次需要重新说明
背景缺失：项目背景、业务需求无法跨会话传递

解决方案：CLAUDE.md

CLAUDE.md 是给 Claude 的"项目入职手册"——每次对话都会自动阅读

四层记忆架构（由高到低）

优先级	层级	位置	内容	加载时机
1	用户级	`~/.claude/CLAUDE.md`	个人偏好、沟通语言、代码风格	始终
2	项目级	`./CLAUDE.md`	项目架构、技术栈、团队规范	始终
3	项目规则级	`.claude/rules/*.md`	按文件类型加载的规范	匹配时
4	本地级	`./CLAUDE.local.md`	本地环境、调试技巧、敏感信息	始终

优先级：用户 → 项目 → 项目规则 → 本地，低层级可覆盖高层级

用户级示例

位置：~/.claude/CLAUDE.md

# 个人偏好

## 沟通方式
- 使用中文回复
- 代码注释使用中文
- 解释简洁直接，不要过多铺垫

## 通用代码风格
- 缩进使用 2 空格
- 优先使用 async/await
- 变量命名使用 camelCase
- 常量命名使用 UPPER_SNAKE_CASE

## Java 开发规范
- 框架: Spring Boot 2.7
- 构建工具: Maven
- 日志: 使用 Lombok @Slf4j，只允许 info/error
- 异常: 业务异常使用自定义 BusinessException
- 工具类: Apache Commons Lang3, Guava

## 输出要求
- 每次回答后打印当前上下文占用，百分比表示

项目规则级示例

提示

paths:

"src/test/**/*.java"
"**/*Test.java"
"**/*Tests.java"

Java 测试规范

命名规范

单元测试: XxxTest.java
集成测试: XxxIntegrationTest.java
测试类放在 src/test/java/ 同包目录下

结构

使用 Given-When-Then 模式：

@SpringBootTest
class OrderServiceTest {

    @Autowired
    private OrderService orderService;

    @Test
    void shouldCreateOrderWhenStockAvailable() {
        // Given: 准备测试数据
        Product product = Product.builder()
            .stock(10)
            .build();

        // When: 执行测试方法
        Order order = orderService.createOrder(product.getId(), 1);

        // Then: 验证结果
        assertThat(order.getStatus()).isEqualTo(OrderStatus.CREATED);
    }
}

覆盖率要求

业务逻辑: > 80%
工具类: > 90%
Controller 层: 可适当降低

常用注解

@SpringBootTest: 集成测试
@WebMvcTest: Controller 测试
@MockBean: Mock 依赖
@DataJpaTest: JPA 测试

编写高效 CLAUDE.md 的四大原则

1. Less is More

每一行都会消耗上下文，冗余不是无害的
保持精简是必须，不是建议

2. 具体优于泛泛

❌ 无效写法：

# 项目规范
请写出高质量的代码。使用有意义的变量名。遵循最佳实践。

Claude Code 本来就知道这些，只会白白占用上下文空间。

✅ 有效写法：

# 项目规范
## Java
- 禁止 `Object`，使用具体类型或 `void`
- 方法参数 > 3 个时，使用 `@Builder` 构建参数对象
- 业务对象使用 Lombok @Data，DTO 使用手动 getter/setter

判断标准：如果不写 Claude 也能做对，就不要写

3. 关键三问题 WHY / WHAT / HOW

WHY - 为什么要这样做？（让 Claude 理解决策逻辑）
WHAT - 具体要做什么、不做什么？（边界定义）
HOW - 按什么步骤去做？（明确路径+参考示例）

WHY 示例：

## 为什么使用 MyBatis-Plus？
- 减少样板代码，CRUD 一行搞定
- 内置分页插件，无需手动写分页
- 自动填充创建时间/更新时间

WHAT 示例：

## 数据库操作规范
- 禁止在 Service 层直接写 SQL，使用 Mapper
- 复杂查询封装在 `src/main/java/.../mapper/xml/`
- 禁止使用 `*` 查询，明确列出返回字段
- 统一使用 `updateById` 而非 `update`

HOW 示例：

## 创建新 Service
在 `src/main/java/.../service/` 创建接口
在 `src/main/java/.../service/impl/` 创建实现类
使用 `@Service` 注解
示例参考: `UserService.java`

4. 渐进式披露

CLAUDE.md 只定义默认决策，不承载全部知识
非核心内容用引用而非复制

## 核心规范
[精简内容]

## 详细参考
- API: @docs/api.md
- 数据库: @docs/database.md

CLAUDE.md 保持轻量，启动成本低。
当 Claude 需要进一步的细节信息时，可以按需读取引用文件

实战演练

场景一：新项目初始化

# Step 1: 创建 CLAUDE.md
touch CLAUDE.md

# Step 2: 创建本地记忆
touch CLAUDE.local.md
echo "CLAUDE.local.md" >> .gitignore

场景二：CLAUDE.md 瘦身三步法

精简 - 识别每次对话都需要的核心内容
拆分 - 详情移到独立文件，用 @docs/xxx.md 引用
条件规则 - 拆分到 .claude/rules/，设置 paths 条件

场景三：记忆管理命令

/memory              # 查看当前加载的所有记忆
/memory edit         # 编辑项目级 CLAUDE.md
/memory edit user    # 编辑用户级记忆
/memory edit local   # 编辑本地级记忆

可以直接让 claude code 修改记忆

  你：我们的项目使用 MyBatis-Plus，不要用 JPA
  Claude：明白，我会在 CLAUDE.md 中添加 MyBatis-Plus 使用规范，并标注禁止使用 JPA

  你：每次创建新 Controller 后，都要添加对应的 DTO 类放在 dto 包下
  Claude：收到，我会在 CLAUDE.md 中添加 DTO 同步创建的规范

  ---

Auto Memory（自动记忆）

Claude Code 会在 ~/.claude/projects/<project-id>/memory/ 自动生成 Auto Memory，记录项目中学习到的模式、调试经验与结构认知。

CLAUDE.md = "系统被告知什么"
Auto Memory = "系统在实践中学到什么"

最佳实践

每次纠正后更新：告诉 Claude"更新你的 CLAUDE.md，这样你就不会再犯这个错误了"
验证模型是否记住：规范末尾加标记词（如 [ok!]），观察响应
不要写入：
- 模型本身就能做对的内容（如缩进 2 空格）
- 过于泛泛的要求
CLAUDE.local.md 用途：
- 本地环境配置
- 当前工作备注
- 敏感信息（测试账号等）
- 定期更新的关键讨论点

小结

记忆系统的本质：把隐性的经验、默认的判断、反复纠正的规则，提前固化成结构

CLAUDE.md 是层次化的，每次对话自动加载
只存放"每次都必须知道的内容"
过多/层级混乱 → Claude 变慢/不稳定

核心问题：AI 的"失忆症"​

解决方案：CLAUDE.md​

四层记忆架构（由高到低）​

用户级示例​

项目规则级示例​

Java 测试规范

命名规范​

结构​

覆盖率要求​

常用注解​

编写高效 CLAUDE.md 的四大原则​

1. Less is More​

2. 具体优于泛泛​

3. 关键三问题 WHY / WHAT / HOW​

4. 渐进式披露​

实战演练​

场景一：新项目初始化​

场景二：CLAUDE.md 瘦身三步法​

场景三：记忆管理命令​

Auto Memory（自动记忆）​

最佳实践​

小结​