AI Agent / 系统课时
编写 CLAUDE.md
编写 CLAUDE.md
本课将项目中反复出现的架构信息、常用命令和开发规范写入 CLAUDE.md。完成后,每次在该项目启动 Claude Code,都能获得一份简洁、可维护的协作说明。
学习目标
- 选择适合写入
CLAUDE.md的稳定信息 - 编写包含架构、命令、规范和边界的项目说明
- 验证文件是否被当前会话正确加载
只记录长期有效的信息
CLAUDE.md 适合记录每次会话都可能用到的事实,例如模块职责、构建命令、代码风格、测试要求和禁止修改的区域。一次性任务、临时故障日志和大段业务文档不应全部塞入其中,否则会持续占用上下文并稀释关键规则。
项目级文件通常放在仓库根目录的 CLAUDE.md,也可以放在 .claude/CLAUDE.md。团队共享内容应提交到版本控制;仅个人使用且与当前项目相关的说明应放入 CLAUDE.local.md,并确保不被提交。
编写一个最小可用文件
下面是一个适合 Java 服务项目的示例。它只记录会直接影响开发决策的信息。
# 项目协作说明
## 架构
- `app-api`:HTTP 接口与请求校验
- `app-service`:业务编排与事务边界
- `app-infrastructure`:数据库、消息队列和外部服务适配
- 依赖方向只能从接口层指向服务层,再指向基础设施抽象
## 常用命令
- 编译:`./mvnw -q -DskipTests compile`
- 单元测试:`./mvnw test`
- 静态检查:`./mvnw verify`
## 编码规范
- 使用 Java 21
- 新增公共方法必须补充单元测试
- 不在 Controller 中编写业务规则
- 优先复用现有异常类型和统一响应结构
## 修改边界
- 不修改 `generated/` 下的生成文件
- 不提交真实密钥、令牌或生产地址
- 数据库结构变更必须新增迁移脚本,不直接改历史脚本这是配置内容示例,不会直接产生控制台输出。保存后,新会话会按其所在层级加载;当前会话可通过上下文命令核对。
验证是否生效
在 Claude Code 会话中运行 /context,检查记忆文件列表中是否出现目标 CLAUDE.md。
/context预期结果
Context usage: <CURRENT_USAGE>
Memory files:
- <PROJECT_ROOT>/CLAUDE.md
<OTHER_CONTEXT_ITEMS>显示内容会随版本和项目变化,关键是目标路径确实出现在记忆文件列表。若没有出现,应检查文件名大小写、保存位置、当前工作目录和文件是否位于可加载层级。
写得具体而不是写口号
“保持高质量代码”无法指导具体行为;“新增公共方法必须补充单元测试”则能影响执行。命令应使用项目真实入口,例如优先记录 Wrapper 命令而不是依赖开发者全局安装的工具。
规则之间不要冲突。若根目录和子目录存在多个 CLAUDE.md,它们通常会共同进入上下文,而不是简单覆盖。子目录可记录局部规则,但应避免复制整份根规则。
持续维护
当 Claude 在多个会话中重复犯同一种错误,或代码审查发现某条项目事实经常被遗漏,可以把简洁规则补入文件。相反,已经失效的命令和架构说明要及时删除。
CLAUDE.md 是上下文说明,不是强制执行器。必须绝对阻止的动作,应使用权限规则或 Hook;需要自动运行的检查,也应使用构建、CI 或 Hook,而不是只写一句提醒。