CLAUDE.md 怎么写：项目记忆配置实践

每次新开会话都要重新交代一遍”测试命令是什么、缩进用几空格、API 前缀是什么”——人烦，模型也记不住。CLAUDE.md 是 Claude Code 的项目记忆文件：每次会话自动注入，把口头约定固化成随仓库走的文件。这篇讲怎么从零写一份不啰嗦、可维护的 CLAUDE.md。

解决什么问题

新会话里的模型对项目一无所知，三类内容必须每次交代：

命令：怎么装依赖、怎么跑测试、怎么起服务；
约定：代码风格、目录结构、接口规范；
禁区：哪些文件不能动、哪些操作要先问。

靠聊天交代有两个问题：一是每次重复；二是聊到后半场，前面的交代在长上下文里被稀释。CLAUDE.md 把这三类内容写进文件，每轮对话完整进入模型上下文，等于给每个新会话发一份员工手册。反过来，有三类内容不该进来：README 里已有的项目背景（引用即可，别复制）；只对某次任务有效的临时要求（那是对话里说的）；纯故事性介绍（影响不了模型行为）。

环境与版本

Claude Code 已安装（流程见安装教程），实测版本【待补：claude —version 输出】。
记忆分层（范围从大到小）：

层级	位置	作用范围
企业策略	由管理员统一下发【待补：组织内实际路径与下发方式】	全组织强制
用户级	`~/.claude/CLAUDE.md`	本机所有项目
项目级	仓库根目录 `./CLAUDE.md`	随 git 共享，团队标准
子目录级	各子目录下的 `CLAUDE.md`	Claude 处理该子目录文件时按需加载

另有 CLAUDE.local.md：个人本地记忆，不进 git；官方文档已将其标记为弃用方向，新项目建议改用 @import 引入个人文件【待补：当前版本的实际行为与文档出处】。

分步骤：从 /init 到可维护的项目记忆

第 1 步：用 /init 生成骨架

claude
> /init

/init 会扫描 README、配置文件和目录结构，生成第一版 CLAUDE.md。注意：自动生成的是”模型看到的仓库描述”，命令与约定要人工核验——它不知道你们团队的隐性规矩。生成后先通读一遍，把”它猜的”和”你确定的”分开，前者删，后者留。

第 2 步：手工改写成”员工手册”

好手册只放”每个新会话都需要”的内容。一份可直接抄的示例：

# 项目：订单后台（Python 3.8 + FastAPI）

## 常用命令
- 跑测试：`pytest -x -q tests/`
- 本地起服务：`uvicorn app.main:app --reload`
- 风格检查：`ruff format . && ruff check --fix .`，提交前必须通过

## 代码约定
- 缩进 4 空格，函数必须写类型标注
- API 统一前缀 /api/v1，响应体固定 {code, msg, data}
- 数据库变更走 alembic 迁移，禁止手改表结构

## 禁止事项
- 不新增第三方依赖，需要先在 issue 里讨论
- 不修改 alembic/versions/ 下已合并的迁移文件

写完用三条标准逐条过：这条内容每个新会话都需要吗？是可执行的命令或明确规则吗？三个月后还成立吗？三条都”是”才留下，否则删掉或挪走。

第 3 步：个人偏好放用户级文件

~/.claude/CLAUDE.md 对这台机器上的所有项目生效，适合放与具体仓库无关的个人习惯：

# ~/.claude/CLAUDE.md（个人全局）
- 一律用中文回复，代码注释跟随仓库现有风格
- git 提交信息用英文，遵循 conventional commits
- 给方案时先给结论和理由，再列备选项

这样每个新项目、新会话都不用再说”请用中文”。

第 4 步：用 @import 拆分长内容

CLAUDE.md 里可以用 @路径 语法引入其他文件，把大块内容拆出去单独维护：

# CLAUDE.md（保持 30 行以内）
@docs/api-conventions.md
@docs/db-style.md

第 5 步：日常维护

会话里随时 #一句话 追加记忆，Claude 会让你选存到哪个文件；
/memory 直接打开记忆文件编辑；
约定变更当天更新，别让手册过期——过期手册比没有手册更糟，模型会照着旧命令跑失败。

常见坑

坑一：写成百科全书。 CLAUDE.md 每次会话全文注入模型上下文，主流模型窗口上限 20 万 token，手册越长，留给干活的空间越小，指令密度下降后模型反而抓不住重点【待补：本文示例 CLAUDE.md 实际注入占用的 token 数】。精简顺序：先删形容词和背景故事，再合并重复条目，最后把低频内容挪进 @import 的文档。

坑二：只写要求，不写验证命令。 “请写带类型标注的代码”是口号；pytest -x -q tests/ 是机制——模型能自己跑、自己验证、自己修。凡是能用命令表达的约定，一律给命令。

坑三：个人偏好混进项目级文件。 想要 vim 键位、英文回复，放用户级文件；只有团队都要遵守的才进仓库里的 CLAUDE.md。放反了，同事的会话全变成你的口味，review 时还说不清这行是谁加的。

坑四：CLAUDE.local.md 提交进 git。 它是个人本地文件，应当进 .gitignore；对团队有价值的部分合并进 CLAUDE.md，其余留在本地。

最终效果

新同事 clone 仓库、装好 Claude Code，第一个会话就直接知道测试命令、代码风格和禁区，不需要任何人口头交代；老成员不用再当复读机。效果好不好有个直接判据：开新会话时，你的第一句话还需要交代背景吗？需要，说明手册还缺东西；不需要，说明它已经够用。把 CLAUDE.md 当成”唯一一份需要维护给 AI 看的团队文档”来经营：短、可执行、随代码一起 review。它和 hooks 是一对——手册负责讲规矩，钩子负责强制执行。

CLAUDE.md 记忆分层与自动注入示意