AI Agent / 系统课时

编写 CLAUDE.md

编写 CLAUDE.md

本课将项目中反复出现的架构信息、常用命令和开发规范写入 CLAUDE.md。完成后,每次在该项目启动 Claude Code,都能获得一份简洁、可维护的协作说明。

学习目标

  • 选择适合写入 CLAUDE.md 的稳定信息
  • 编写包含架构、命令、规范和边界的项目说明
  • 验证文件是否被当前会话正确加载

只记录长期有效的信息

CLAUDE.md 适合记录每次会话都可能用到的事实,例如模块职责、构建命令、代码风格、测试要求和禁止修改的区域。一次性任务、临时故障日志和大段业务文档不应全部塞入其中,否则会持续占用上下文并稀释关键规则。

项目级文件通常放在仓库根目录的 CLAUDE.md,也可以放在 .claude/CLAUDE.md。团队共享内容应提交到版本控制;仅个人使用且与当前项目相关的说明应放入 CLAUDE.local.md,并确保不被提交。

编写一个最小可用文件

下面是一个适合 Java 服务项目的示例。它只记录会直接影响开发决策的信息。

markdown
# 项目协作说明

## 架构

- `app-api`:HTTP 接口与请求校验
- `app-service`:业务编排与事务边界
- `app-infrastructure`:数据库、消息队列和外部服务适配
- 依赖方向只能从接口层指向服务层,再指向基础设施抽象

## 常用命令

- 编译:`./mvnw -q -DskipTests compile`
- 单元测试:`./mvnw test`
- 静态检查:`./mvnw verify`

## 编码规范

- 使用 Java 21
- 新增公共方法必须补充单元测试
- 不在 Controller 中编写业务规则
- 优先复用现有异常类型和统一响应结构

## 修改边界

- 不修改 `generated/` 下的生成文件
- 不提交真实密钥、令牌或生产地址
- 数据库结构变更必须新增迁移脚本,不直接改历史脚本

这是配置内容示例,不会直接产生控制台输出。保存后,新会话会按其所在层级加载;当前会话可通过上下文命令核对。

验证是否生效

在 Claude Code 会话中运行 /context,检查记忆文件列表中是否出现目标 CLAUDE.md。

text
/context

预期结果

text
Context usage: <CURRENT_USAGE>
Memory files:
- <PROJECT_ROOT>/CLAUDE.md
<OTHER_CONTEXT_ITEMS>

显示内容会随版本和项目变化,关键是目标路径确实出现在记忆文件列表。若没有出现,应检查文件名大小写、保存位置、当前工作目录和文件是否位于可加载层级。

写得具体而不是写口号

“保持高质量代码”无法指导具体行为;“新增公共方法必须补充单元测试”则能影响执行。命令应使用项目真实入口,例如优先记录 Wrapper 命令而不是依赖开发者全局安装的工具。

规则之间不要冲突。若根目录和子目录存在多个 CLAUDE.md,它们通常会共同进入上下文,而不是简单覆盖。子目录可记录局部规则,但应避免复制整份根规则。

持续维护

当 Claude 在多个会话中重复犯同一种错误,或代码审查发现某条项目事实经常被遗漏,可以把简洁规则补入文件。相反,已经失效的命令和架构说明要及时删除。

CLAUDE.md 是上下文说明,不是强制执行器。必须绝对阻止的动作,应使用权限规则或 Hook;需要自动运行的检查,也应使用构建、CI 或 Hook,而不是只写一句提醒。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

编写 CLAUDE.md

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通