CLAUDE.md 模板：一份可复制的起步文件，外加每个文件到底放哪

CLAUDE.md 是 Claude Code 每次会话启动时读取的项目记忆：构建命令、代码约定，以及没人提醒就容易反复做错的地方。本文给你两份可复制的起步文件，也补上很多指南没讲清的一点：什么内容应该放进哪个文件。Claude Code 会同时加载多份 CLAUDE.md，它们不是同一个文件的不同摆放位置。（文件写好以后，怎么继续打磨，见如何写好 CLAUDE.md；如果你在处理跨工具的 AGENTS.md，先看 CLAUDE.md 和 AGENTS.md 到底怎么分工。）

项目模板

把下面内容放到仓库根目录的 CLAUDE.md（或 ./.claude/CLAUDE.md）。填上你的技术栈，再删掉不适用的行：

# CLAUDE.md

## Project
One paragraph: what this is, the stack, and the one architectural fact
Claude keeps getting wrong. (e.g. "API and worker share types from
packages/core — change them together or the build breaks.")

## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test one file: `pnpm vitest run <path>`   # not the whole suite
- Lint + typecheck: `pnpm lint && pnpm tsc --noEmit`
- Never run: `pnpm deploy` (CI only), `pnpm db:reset` (destructive)

## Conventions
- TypeScript strict. No `any` — fix the type, don't cast around it.
- Imports absolute from `src/`. No deep `../../` chains.
- Errors: throw typed `AppError` subclasses, never bare strings.
- Match the nearest existing file's patterns for new code.

## Boundaries
- Don't edit `src/generated/**` — regenerated on build.
- Append new files in `db/migrations/`; never edit existing ones.
- Secrets come from env vars. Never hardcode or commit real data.

## Done means
- `pnpm test` green, no new lint/type errors.
- Behavior change ⇒ a test changed or added.

<!-- maintainer note: keep this under 200 lines; move topic detail to .claude/rules/ -->

最后那行不是装饰，而是一个实用技巧：块级 HTML 注释会在文件进入 Claude 上下文前被剥离。维护者提醒可以留在文件里，但不会花掉 token。

每个文件放在哪里（真正重要的部分）

Claude Code 会从四层作用域加载 CLAUDE.md，按从宽到窄的顺序拼接；它们不是覆盖关系，不会只留下最后一份。放置规则很简单：先问这条指令是写给谁看的。

最常见的错误，是把个人偏好塞进团队共享的项目文件。这样等于把你的习惯发给每个队友，还会悄悄替他们多烧 token。按上表拆开：项目事实进项目文件，个人口味进用户文件。

个人配套文件

~/.claude/CLAUDE.md 会作用于这台机器上的所有项目。这里只放真正跨项目成立的偏好：

# ~/.claude/CLAUDE.md

- Explain non-obvious changes in one line before the diff.
- Prefer standard library over adding a dependency; ask before adding one.
- When tests fail, show me the failing output before proposing a fix.
- Commit messages: imperative mood, no "Generated by" footers.

如果某条规则只对一个仓库成立，就让它回到那个仓库的文件里，不要放在这里。

一个真理源：导入和 AGENTS.md 桥接

CLAUDE.md 可以用 @path 导入其他文件。启动时，导入内容会展开进上下文；相对路径、绝对路径和 @~/ 主目录路径都支持，最多四跳：

See @README.md for overview and @package.json for scripts.
- Git workflow: @docs/git-instructions.md

如果仓库已经有 AGENTS.md，这也是避免维护两份指令的办法。Claude Code 不会原生读取 AGENTS.md；文档原话是：“Claude Code reads CLAUDE.md, not AGENTS.md.” 所以给 Claude 的入口仍然是 CLAUDE.md。做法很薄：让 CLAUDE.md 只负责导入共享文件，再写少量 Claude 专属补充。

@AGENTS.md

## Claude Code
Use plan mode for changes under `src/billing/`.

其他工具直接读 AGENTS.md；Claude 读到同一份共享文件，再加这些 Claude 专属补充。完整设置，包括软链方案和 monorepo 目录，见AGENTS.md 模板。

两个值得知道的命令

• /init 会分析你的代码库，生成一份起步 CLAUDE.md：构建命令、测试说明，以及它能从代码里发现的约定。如果文件已经存在，它会给出改进建议，而不是直接覆盖。它还会吸收已有的 AGENTS.md、.cursorrules、.devin/rules/ 和 .windsurfrules。把结果当第一稿，然后手动删瘦。
• /memory 会列出当前会话实际加载的每一个 CLAUDE.md 和 CLAUDE.local.md，并能打开其中任意一个编辑。某条指令没被遵守时，先跑 /memory；如果文件不在列表里，Claude 就根本看不见它。

保持轻量

CLAUDE.md 每个 session 都会完整加载，所以文件越大，token 和注意力就越要每次重付。目标是控制在 200 行以内。项目复杂以后，不要继续往根文件里塞；把专题细节拆进 .claude/rules/，按路径作用域加载，只在 Claude 真去碰相关文件时进上下文。上面的模板短，不是因为省掉了重要信息，而是因为每一行都应该对应 Claude 在你仓库里本来会做错的事，而不是它早就知道的常识。

延伸阅读

• AGENTS.md 模板 —— 跨工具版本，适合不止一个 agent 会读指令的仓库。
• 如何写好 CLAUDE.md —— 写作工艺，包含真实前后对比。
• CLAUDE.md vs AGENTS.md —— Claude Code 实际读哪个文件，以及怎么桥接。
• CLAUDE.md 中 5 个偷烧 token 的坏习惯 —— 哪些内容该从文件里删掉。