Claude Code使用：如何写一个好的 CLAUDE.md
CLAUDE.md 像是你和 Claude 之间的协作契约，不是团队文档，也不是知识库，里面只放那些每次会话都得成立的事。
一开始甚至可以什么都不写。先用起来，等你发现自己老是在重复同一件事，再把它补进去。加法也不复杂，输入 # 可以把当前对话里的内容直接追加进 CLAUDE.md，或者直接告诉 Claude「把这条加到项目的 CLAUDE.md 里」，它会知道该改哪个文件。
应该放什么
- 怎么 build、怎么 test、怎么跑（最核心）
- 关键目录结构与模块边界
- 代码风格和命名约束
- 那些不明显的环境坑
- 绝对不能干的事（NEVER 列表）
- 压缩时必须保留的信息（Compact Instructions）
不该放什么
- 大段背景介绍
- 完整 API 文档
- 空泛原则，如"写高质量代码"
- Claude 通过读仓库即可推断的显然信息
- 大量背景资料和低频任务知识（这些放到 Skills）
高质量模板
markdown
# 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，只对部分文件生效的放 rules，只在某类任务中需要的放 Skills。
让 Claude 维护自己的 CLAUDE.md
我最喜欢的一个技巧：每次纠正 Claude 的错误后，让它自己更新 CLAUDE.md：
“Update your CLAUDE.md so you don’t make that mistake again.”
Claude 在给自己补这类规则时其实还挺好用，用久了确实越来越少犯同样的错。不过也要定期 review，时间一长总会有些条目慢慢过时，当初有用的限制现在未必还适合，这件事后面第 14 节有个更系统的做法。
环境透明比你想象中重要
Claude Code 调用的都是真实的 shell、git、package manager 和本地配置。这里面只要有一层不透明，它就只能开始猜，一猜可靠性就掉。这不是 Claude Code 特有的问题，很多 agent 都一样。
所以我后来很快就在 terminal 里加了个 doctor 命令，把环境状态、依赖和配置情况先统一收上来，输出一份结构化的健康报告。Claude Code 开始做事前先跑一次 doctor，确实能省掉很多"环境没搞清楚就开干"的问题。
另外我还发现，假如 CLI 本身就有 init、config、reset 这类语义清楚的子命令，Claude Code 用起来会稳不少，比让它自己去猜配置文件怎么摆要靠谱。先把状态收敛住，再暴露编辑入口，顺序一反过来就很容易乱。
混合语言项目的 Hooks 实践
两套语言、两套检查，其实挺适合用 Hooks 按文件类型分别触发：
json
{"hooks":{"PostToolUse":[{"matcher":"Edit","pattern":"*.rs","hooks":[{"type":"command","command":"cargo check 2>&1 | head -30","statusMessage":"Checking Rust..."}]},{"matcher":"Edit","pattern":"*.lua","hooks":[{"type":"command","command":"luajit -b $FILE /dev/null 2>&1 | head -10","statusMessage":"Checking Lua syntax..."}]}]}}每次编辑完立刻知道有没有编译错误，比"跑了一堆才发现最开始就挂了"舒服得多。
完整的工程化布局参考
假如有同学想给自己项目配一套比较完整的 Claude Code 工程布局，可以参考这个结构，不用全做，按需裁剪：
Project/ ├── CLAUDE.md ├── .claude/ │ ├── rules/ │ │ ├── core.md │ │ ├── config.md │ │ └── release.md │ ├── skills/ │ │ ├── runtime-diagnosis/ # 统一收集日志、状态和依赖 │ │ ├── config-migration/ # 配置迁移回滚防污 │ │ ├── release-check/ # 发布前校验、smoke test │ │ └── incident-triage/ # 线上故障分诊 │ ├── agents/ │ │ ├── reviewer.md │ │ └── explorer.md │ └── settings.json └── docs/ └── ai/ ├── architecture.md └── release-runbook.md全局约束（CLAUDE.md）、路径约束（rules）、工作流（skills）和架构细节各归各位，Claude Code 跑起来会稳很多。假如你同时维护多个项目，可以把稳定的个人基线放在 ~/.claude/，各项目的差异放在项目级 .claude/，通过同步脚本分发，不同项目之间就不会互相污染了。