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 21 | head -30,statusMessage:Checking Rust...}]},{matcher:Edit,pattern:*.lua,hooks:[{type:command,command:luajit -b $FILE /dev/null 21 | 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/通过同步脚本分发不同项目之间就不会互相污染了。常见反模式