CLAUDE.md 编写指南：让你的 AI 编程助手真正懂你的项目

一、从一个场景说起

你打开 Claude Code，信心满满地敲下需求：

"帮我写一个 FastAPI 的用户认证模块"

Claude 爽快地写了几百行代码，然后你发现——它用了 Flask 而不是你项目的 FastAPI，print 而不是你统一的 logging，os.path 而不是你封装的 pathlib 工具，测试框架 pytest fixtures 的写法也和你项目风格完全不同。

你叹了口气，知道这是"从零开始"的 AI 会话的通病：Claude 没有你的项目记忆。

这就是 CLAUDE.md 存在的意义。

二、什么是 CLAUDE.md

CLAUDE.md 是 Claude Code 的项目记忆文件。每个会话启动时，它会被注入到 system prompt 中，让 Claude 在开口前就知道：

• 你用什么技术栈
• 代码风格偏好
• 架构约束
• 容易踩的坑
• 关键的红线

更重要的是，/compact（上下文压缩）之后，CLAUDE.md 会从磁盘重新加载——这意味着它是唯一能跨会话持久传递项目上下文的机制。

三、文件放在哪

Claude Code 支持多级 CLAUDE.md，按优先级由高到低：

最佳实践：

• ./CLAUDE.md 提交到仓库，团队共享技术规范
• ./CLAUDE.local.md 放个人偏好（比如你习惯用 uv 而队友用 pip），自动被 .gitignore
• Monorepo 项目：根目录 CLAUDE.md 全局加载，子目录的按需加载，省 token

四、写什么：推荐的 CLAUDE.md 结构

一个实战模板（Python 项目）

# 项目名：order-service
​
一个 FastAPI + SQLAlchemy + Redis 的订单微服务。
​
## Commands
你需要知道但 Claude 无法从 pyproject.toml 推断的命令：
- uv run pytest -m "not slow" — 跳过慢速测试
- uv run alembic upgrade head — 数据库迁移
- uv run pre-commit run --all-files — 全量代码检查
- docker compose up -d redis postgres — 本地依赖服务
​
## Code Style
和默认行为有差异的风格约定：
- 所有函数签名必须带类型注解，返回值不能省略
- 用 pathlib 处理路径，禁止 os.path 和字符串拼接
- 日志统一用 structlog，禁止 print 和 logging 模块
- async/await 优先，除非确定是纯 CPU 密集操作
​
## Architecture
关键架构约束：
- src/domain/ — 领域模型和数据实体
- src/services/ — 业务逻辑层，不依赖 FastAPI
- src/adapters/ — 外部依赖适配（数据库、缓存、消息队列）
- src/api/ — FastAPI 路由，只做参数校验和响应序列化
- 所有数据库操作通过 repository 模式，服务层不直接写 SQL
​
## Rules
红线，用了强调词：
- NEVER 提交包含密码、API 密钥、连接字符串的代码
- ALWAYS 新建 service 函数先写 pytest 测试
- ALWAYS 外部 API 调用设置 timeout 参数
- 禁止在 Jupyter Notebook 里定义数据模型（只允许在 .py 文件中）
​
## Gotchas
那些代码里看不出来的坑：
- 配置从 YAML 文件加载，不是 JSON 也不是 .env
- CI 环境没有 Redis，涉及缓存的测试用 fakeredis
- 旧版 report 模块的 PDF 生成是同步+阻塞的，不要改异步（依赖 WeasyPrint）
- Alembic 迁移脚本依赖模型 import，删除模型前先检查迁移历史

各部分的职责

五、不该写什么：减少噪音比增加信息更重要

CLAUDE.md 不是 dump all。以下内容请坚决删除：

核心原则：每行不超过 200 行的 CLAUDE.md 是黄金标准。行文越长，指令越被稀释。

六、强调词使用指南

Anthropic 官方建议对关键规则使用强调标记，但有个度：

关键：如果所有规则都打上 IMPORTANT，就没有一条是重要的。

七、@import：让根文件保持精炼

CLAUDE.md 支持 @ 语法引用外部文件：

项目概览请参考 @README.md。
API 设计规范见 @docs/api-conventions.md。
Git 工作流：@docs/git-workflow.md

• 路径相对于当前 CLAUDE.md 文件
• 支持最多 5 层递归引用
• 配合外部文档，根文件可以控制在 30-50 行

八、.claude/rules/：按路径按需加载

项目大了，不可能把所有东西塞在一个文件里。.claude/rules/ 目录允许你按文件路径、按需加载规则：

---
paths:
  - "src/api/**/*.py"
  - "src/handlers/**/*.py"
---
​
# API 设计规则
​
- 所有 handler 返回统一的 ResponseWrapper 格式
- 请求体验证统一用 Pydantic v2
- 每个路由必须设置 rate limit middleware
- 错误日志用 structlog，不要用 print

不带 paths 的 rules 文件：启动时加载（类似 CLAUDE.md）

带 paths 的 rules 文件：仅在 Claude 读取匹配路径的文件时才加载——这种方式省 token，适合大型 monorepo。

九、日常维护：CLAUDE.md 是活的

CLAUDE.md 不是写完就扔。它应该随着项目演化：

即时补充

Claude 做错了什么假设时，立刻说一句：

"把这个加到 CLAUDE.md：我们用 structlog 不是 logging"

Claude 会自动打开编辑。

定期审查

每隔几个迭代，让 Claude 帮你做一次体检：

"审查 CLAUDE.md，找出冗余、冲突和过时的内容"

把 CLAUDE.md 当成项目的"关键配置"来对待——团队 review、版本控制、与代码同步更新。

从 Code Review 中提取

当 reviewer 在 PR 里反复指出同一种模式问题，说明 CLAUDE.md 里缺少这条——补上它。

十、总结

CLAUDE.md 本质上是你写给 AI 的项目入职手册。写好它的秘诀不是"写得多"，而是"写得准"：

• 只写 Claude 查不到、猜不出的信息
• 格式化交给 pre-commit hook，不靠建议
• 踩坑一条补一条，让它自然生长
• 定期审计，别让过时指令害了你

把它当代码一样对待——版本控制、团队 review、持续迭代。一个好的 CLAUDE.md 能让你和 AI 的协作效率提升一个量级。