09 - CLAUDE.md 写法

协作契约，不是文档

CLAUDE.md 更像是你和 Claude 之间的协作契约，不是团队文档，也不是知识库。里面只放那些每次会话都得成立的事。

一开始甚至可以什么都不写。先用起来，等你发现自己老是在重复同一件事，再把它补进去。输入 # 可以把当前对话里的内容直接追加进 CLAUDE.md。

应该写的

• 怎么 build、怎么 test、怎么跑（最核心）
• 关键目录结构与模块边界
• 代码风格和命名约束
• 那些不明显的环境坑
• 绝对不能干的事（NEVER 列表）
• 压缩时必须保留的信息（Compact Instructions）

不应该写的

• 大段背景介绍
• 完整 API 文档
• 空泛原则，如”写高质量代码”
• Claude 通过读仓库即可推断的显然信息
• 大量背景资料和低频任务知识（这些放到 Skills）

模板

# Project Contract
 
## Build And Test
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test`
- Typecheck: `pnpm typecheck`
- Lint: `pnpm lint`
 
## Architecture Boundaries
- HTTP handlers live in `src/http/handlers/`
- Domain logic lives in `src/domain/`
- Do not put persistence logic in handlers
- Shared types live in `src/contracts/`
 
## Coding Conventions
- Prefer pure functions in domain layer
- Do not introduce new global state without explicit justification
- Reuse existing error types from `src/errors/`
 
## Safety Rails
### NEVER
- Modify `.env`, lockfiles, or CI secrets without explicit approval
- Remove feature flags without searching all call sites
- Commit without running tests
 
### ALWAYS
- Show diff before committing
- Update CHANGELOG for user-facing changes
 
## Verification
- Backend changes: `make test` + `make lint`
- API changes: update contract tests under `tests/contracts/`
- UI changes: capture before/after screenshots
 
## Compact Instructions
Preserve:
1. Architecture decisions (NEVER summarize)
2. Modified files and key changes
3. Current verification status (pass/fail commands)
4. Open risks, TODOs, rollback notes

分层策略

层级	放什么	文件位置
每次都要知道的	核心构建命令、架构边界、安全护栏	CLAUDE.md
只对部分文件生效的	语言规则、目录规则	.claude/rules/*.md
只在某类任务中需要的	工作流、领域知识	.claude/skills/

迭代优化技巧

每次纠正 Claude 的错误后，让它自己更新 CLAUDE.md：

“Update your CLAUDE.md so you don’t make that mistake again.”

Claude 在给自己补这类规则时挺好用，用久了确实越来越少犯同样的错。不过也要定期 review，时间一长总会有些条目慢慢过时。

用 /insight 让 Claude 分析当前会话，提炼出哪些内容值得沉淀到 CLAUDE.md——它会指出”这个约定你们反复提到，但没有写进契约”之类的盲点。

---

Prev: 08 - 验证体系与命令速查 | Next: 10 - 实战经验与工程布局