每次打开Claude Code，都要重新交代一遍项目用什么技术栈、代码风格怎么定、哪些坑不能踩——这不是在干活，是在重复做入职培训。CLAUDE.md要解决的，正是这个问题。
一、CLAUDE.md是什么？
CLAUDE.md是一个纯Markdown文件，Claude Code在每个会话开始时自动读取。它被注入到system prompt中，让Claude在开口前就知道项目的技术栈、代码风格、架构约束、常见坑点和红线。
通俗理解：CLAUDE.md就是你给AI编程助手写的“入职手册”。不写也能用，但相当于招了一个能力很强但完全不了解项目的新人，每次沟通都要从头交代背景。
二、文件放在哪？
Claude Code支持多级CLAUDE.md，按加载顺序从广到窄排列：
位置 | 作用范围 | 是否提交Git |
~/.claude/CLAUDE.md | 所有项目，个人全局偏好 | 否 |
./CLAUDE.md 或 ./.claude/CLAUDE.md | 当前项目，团队共享 | 是 |
./CLAUDE.local.md | 当前项目，仅自己 | 自动gitignore |
.claude/rules/*.md | 按文件路径按需加载 | 是 |
最佳实践：./CLAUDE.md提交到仓库，团队共享技术规范；CLAUDE.local.md放个人偏好（比如你用uv而队友用pip），会被自动gitignore；Monorepo项目根目录放全局配置，子目录放按需加载的模块规则。
子目录的CLAUDE.md不会在会话开始时加载，而是当Claude读取该子目录中的文件时才按需加载。
三、写什么？推荐结构和实战模板
目标是200行以内，每行都在每个请求中加载，所以每行都应值得其成本。CLAUDE.md没有固定格式，但通常包含这几块：
1. Commands —— Claude无法从代码推断的命令
- `uv run pytest -m "not slow"` — 跳过慢速测试 - `uv run alembic upgrade head` — 数据库迁移 - `docker compose up -d redis postgres` — 本地依赖服务
2. Code Style —— 与默认行为不同的风格约定
- 所有函数签名必须带类型注解 - 用pathlib处理路径，禁止os.path和字符串拼接 - 日志统一用structlog，禁止print - async/await优先，除非确定是纯CPU密集操作
3. Architecture —— 关键架构约束
- src/domain/ — 领域模型和数据实体 - src/services/ — 业务逻辑层，不依赖FastAPI - src/api/ — FastAPI路由，只做参数校验和响应序列化 - 所有数据库操作通过repository模式
4. Rules —— 红线，用强调词
- NEVER 提交包含密码、API密钥的代码 - ALWAYS 新建service函数先写pytest测试 - ALWAYS 外部API调用设置timeout参数
5. Gotchas —— 代码里看不出来的坑
- 配置从YAML加载，不是JSON - 时区统一用UTC
四、怎么快速开始？用/init命令
输入/init，Claude会自动分析代码库——读取package文件、现有文档、配置文件、代码结构——然后生成一份CLAUDE.md草稿。审查后删掉不准确的内容，提交即可。整个过程大约5分钟，但永久受益。
五、两个容易被忽略的细节
1. CLAUDE.md ≠ 自动记忆
CLAUDE.md和自动记忆（Auto Memory）是两套互补系统。CLAUDE.md由你编写，用于编码标准、工作流、项目架构等固定规则；自动记忆由Claude根据你的更正和偏好自己写笔记，用于构建命令、调试见解、Claude发现的偏好。两者都在每次会话开始时加载。
2. 成本：大部分时候是缓存读取
会话中的第一个请求支付文件的完整输入令牌价格；约五分钟内的后续请求命中缓存，按低得多的缓存读取率计费。一个200行的CLAUDE.md每个会话支付一次完整令牌，加上任何足够长的空闲间隙后一次，而不是每条消息一次。保持精简仍然值得，但不需为控制每条消息支出而过度限制行数。
六、什么时候该往CLAUDE.md里加东西？
官方给了四个判断标准：
- Claude第二次犯同样的错误
- 代码审查发现Claude应该知道但不知道的内容
- 你在聊天中输入了和上次会话相同的更正或澄清
- 新队友需要同样的上下文才能高效工作
把CLAUDE.md当成项目的“关键配置”来对待——团队review、版本控制、与代码同步更新-。每行都在每个会话中加载，所以保持精简，超过200行考虑拆分到.claude/rules/目录下按需加载。
CLAUDE.md解决的不是“AI能不能写代码”的问题，而是“AI能不能按你的方式写代码”的问题。前者靠模型，后者靠上下文。而上下文，靠的就是这份文件。
