CLAUDE.md 配置文件：放在哪里与怎么写

学习 Claude Code 的 CLAUDE.md 应该放在哪里、写什么、不写什么，以及如何维护长期项目记忆。

CLAUDE.md 是 Claude Code 用来读取长期项目规则的记忆文件。它适合记录项目命令、架构边界、编码规范、测试要求和高风险提醒。写得越具体、越贴近仓库，效果越稳定。

快速结论

如果规则需要团队共享，把项目级 CLAUDE.md 放在仓库根目录。如果只是个人偏好，放在用户级记忆里。只有 monorepo 里前端、后端、基础设施或包规则明显不同时，才需要嵌套多个 CLAUDE.md。

位置	适合记录	是否提交到 git
`./CLAUDE.md`	团队共享的项目规则、命令、架构说明	通常提交
`./frontend/CLAUDE.md`	monorepo 子项目规则	共享规则就提交
`~/.claude/CLAUDE.md`	跨项目个人偏好	不提交
`CLAUDE.local.md`	本地私有但不含密钥的提醒	通常 ignore

应该写什么

写 Claude Code 在真实工作中会用到的规则：

准确的安装、开发、构建、lint、测试和类型检查命令。
包管理器和运行时版本约定。
关键目录和模块边界。
认证、支付、数据库和部署相关安全规则。
常见改动后必须运行的验证命令。
反复出现过的错误和避坑提醒。

不要把每个组件、每条路由、每个临时目标都塞进去。如果一条内容不会改变 Claude Code 的行为，它通常不该写进 CLAUDE.md。

最小模板

# CLAUDE.md

## Project Commands

- `pnpm install`: install dependencies
- `pnpm dev`: start local development
- `pnpm build`: production build
- `pnpm lint`: lint checks
- `pnpm test`: run tests

## Architecture Notes

- Keep public marketing pages in `content/pages`.
- Keep tutorial documentation in `content/docs`.
- Do not change auth, payment, or deployment code without a plan first.

## Working Rules

- Prefer small, reviewable diffs.
- Preserve existing URLs unless a redirect is explicitly planned.
- Run the relevant checks before summarizing implementation work.

大多数项目用这个骨架就够了。只有当 Claude Code 反复需要某类上下文时，再补充细节。

Monorepo 写法

对于 monorepo，根目录文件写通用规则，子目录文件写局部规则：

repo/
├── CLAUDE.md
├── apps/
│   ├── web/
│   │   └── CLAUDE.md
│   └── admin/
│       └── CLAUDE.md
└── packages/
    └── db/
        └── CLAUDE.md

根目录适合写共享命令和安全边界。子目录适合写框架规则、迁移命令、生成代码边界和包级测试命令。

怎样写才有效

不够好的写法	更好的写法
“写干净代码。”	“沿用 `src/components/ui` 里的组件 primitives，未经确认不要新增 UI 库。”
“记得跑测试。”	“改 billing 后运行 `pnpm test billing` 和 `pnpm build`。”
“数据库要小心。”	“编辑 migration 前先列出回滚步骤和影响表。”
“记住项目结构。”	“公开页面在 `content/pages`，教程在 `content/docs`，已有 URL 优先保持稳定。”

什么时候更新

当一条规则变成长期规则时，再更新 CLAUDE.md：

新命令替代了旧命令。
项目换了包管理器。
高风险模块增加了固定验证步骤。
某个反复纠正的问题应该变成常驻规则。
迁移改变了路由、内容或服务组织方式。

不要把 CLAUDE.md 当作每次任务的草稿纸。临时记录留在当前会话或单独交接文档里更合适。

常见错误

写入密钥、token、API key 或客户隐私数据。
写无法验证的宽泛偏好。
项目变化后仍保留旧命令。
直接复制整份 README，而不是写 Claude Code 需要遵守的工作规则。
嵌套太多 CLAUDE.md，却没有说明规则优先级。

官方来源

下一步：工具权限管理 - 管理 Claude Code 可以读取、编辑和运行的内容。