从零写一份能跟着项目长大的 CLAUDE.md：结构、引用与演进清单

每次新开 Claude Code 会话，模型都会「失忆」：不知道你用 pnpm 还是 npm，不知道测试要先起 Docker，更不知道鉴权模块里那坨历史包袱不能乱动。于是你要么反复口述，要么事后返工。

CLAUDE.md 要解决的，不是把 Wiki 整本塞进根目录，而是把每轮都会用到的项目事实写成一份会随代码一起演进的活文档。本文按「从零开写 → 结构模板 → 拆分与引用 → 长期维护」给出可复制的写法；Cursor / Zed 等工具上的 AGENTS.md 也可套用同一思路。

说明：本地已有一篇讲「八层 .claude/ 配置栈、Hooks、路径级规则」的配置文（claude-config）。那篇偏控制面架构；本文偏从零写好、养好一份主记忆文件，刻意不重复 Hooks / Subagent 整栈展开。

为什么需要「项目一句话」而不是「项目百科」

Claude 每次会话都从空白上下文起步。它不知道你们分支命名、不知道 Stripe Webhook 必须验签、不知道你们禁用 any。缺了这些，它会用「通用最佳实践」硬套你的仓库。

CLAUDE.md 的价值是：把你本来要在每个 Prompt 里重复的话，改成会话启动时自动注入的权威上下文。 它不是系统强制配置，写法越具体、越可验证，遵守率越高。

反例是把整份内部 Wiki、API 全量说明、历史会议纪要都贴进去。行数一多，真正干活的注意力就被挤掉——这也是另一类「臃肿 CLAUDE.md」灾难，但解法不是放弃写文件，而是只写启动前必须知道的事实，细节用引用与按需规则承接。

最快起步：/init 生成，再删到能用

最快路径是在项目目录里跑 Claude Code，执行：

claude
# 然后在会话中输入：
/init

/init 会扫 package.json / pyproject.toml、目录结构和常见配置，吐出一版初稿：构建命令、测试入口、它猜到的约定。已有 CLAUDE.md 时，新版流程更倾向「建议改进」而不是粗暴覆盖。

推荐姿态是：把 /init 当草稿，大胆删。 生成物常夹着「人人都知道」的废话；删比从零写省力。上下文是稀缺资源，每一行都在和「真正的任务描述」抢注意力。

放哪、叫什么

文件名大小写敏感：必须是 CLAUDE.md（CLAUDE 全大写，.md 小写）。写成 Claude.md / claude.md 时，记忆加载可能直接找不到。

结构模板：五段就够，每条都要可验证

一份能用的主文件，通常就这五块：

1. 项目背景：一句话定位（技术栈 + 业务形态）。

2. 代码风格：可执行偏好（命名导出、禁止 any、只用 Tailwind 等），禁止写「写得干净一点」。

3. 常用命令：dev / test / lint / migrate 的真实命令，让模型少猜。

4. 架构地图：关键目录干什么，而不是贴完整树。

5. 坑点与红线：绝不能直接改的目录、必须验签的接口、奇怪的重试逻辑。

下面是一份可直接改写的 Next.js 示意（演示用，勿照抄进生产密钥）：

# Project: ShopFront

Next.js 14 电商应用，App Router + Stripe + Prisma。

## Code Style
- TypeScript strict，禁止 `any`
- 使用 named exports，不用 default export
- 样式只用 Tailwind utility，不新建散落 CSS 文件

## Commands
- `npm run dev`：开发服（端口 3000）
- `npm run test`：Jest
- `npm run test:e2e`：Playwright
- `npm run lint`：ESLint
- `npm run db:migrate`：Prisma migrate

## Architecture
- `/app`：页面与 layout
- `/components/ui`：可复用 UI
- `/lib`：工具与共享逻辑
- `/prisma`：schema 与迁移
- `/app/api`：API routes

## Important Notes
- 禁止提交 `.env`
- `/app/api/webhooks/stripe` 必须校验签名
- 商品图在 Cloudinary，不落本地
- 鉴权细节见 @docs/authentication.md

标题清晰、条目可扫、命令可复制——模型处理这类结构远比散文有效。

多长合适？

社区经验值是单文件尽量压在约 300 行以内，能更短更好。官方文档常见建议是单文件瞄准 200 行量级；复杂仓库可以略长，但前提是每一行都能防止一次错误假设。只在特定模块才重要的内容，不要常驻主文件。

瘦身三板斧：@import、规则目录、子目录记忆

主文件要瘦，细节要活，可以用三层机制（此处只讲「怎么写主记忆」，不展开 Hooks 整栈）：

1. @path 引用

See @README.md for project overview
See @docs/api-patterns.md for API conventions
See @package.json for available npm scripts

支持相对路径、绝对路径，甚至 @~/.claude/my-preferences.md。被引用文件还可以再引用（递归），但别做成迷宫——主文件只留常驻要点，专题细节进独立 Markdown。

注意：@import 仍会在启动时装进上下文；它是组织方式，不是自动省 Token。真正按场景减负，要靠路径级规则或子目录记忆。

2. .claude/rules/ 专题规则

大团队可以把「代码风格 / 测试 / 安全」拆成多个 Markdown，丢进 .claude/rules/。这些文件与主 CLAUDE.md 同等优先级自动加载，不必手写 import，也方便不同小组各改各的、少撞合并冲突。

带 YAML paths 的路径作用域规则，可在触碰匹配文件时才加载——适合「前端规范别拖进后端改动」。那是配置栈另一篇文章的王牌；这里记住一句就够：主文件写全局事实，领域细则尽量外置。

3. 子目录 CLAUDE.md

Monorepo 里 /api、/packages/ui 可以各自放一份。它们不会在启动时全量灌入，只有模型在该子树工作时才挂上。适合「模块约定差异大、根文件写不下」的场景。

长期提效：边干活边写，而不是一次性写完

CLAUDE.md 不是「设完就忘」。项目会变，偏好会变，文件也必须变。

当场沉淀纠错

模型又用了 console.log，而你们统一用项目 logger？不要只改这一次。直接说：

把这条写进 CLAUDE.md：调试输出一律用项目 logger，禁止 console.log。

早期版本曾有 # 快捷键追加规则；较新版本里更稳妥的做法是明确让 Claude 编辑 CLAUDE.md。规则来自真实踩坑，比空想清单更准。

定期复盘

每隔几周丢一句：「审一下这份 CLAUDE.md，标出过时、冲突、可合并的条目。」删过时、并重复、澄清模糊句。这是维护成本，但通常低于每轮复述或每轮返工。

关键规则用强调词，但别滥用

IMPORTANT: / YOU MUST 可以提高注意力，尤其对「禁止直接改 migrations」这类红线。它不是锁：对话一长、上下文一挤，仍可能越界。若满篇都是 IMPORTANT，等于没有重点。

从 Code Review 回流

PR 里审出一条未文档化的约定，或发现模型反复踩同一雷——当场补进 CLAUDE.md。若启用了 Claude Code 的 GitHub Action，可在评论里 @claude 请它把约定写回文件并随 PR 提交。Boris Cherny 分享过这类闭环：真实问题 → 写入规则 → 减少下一轮问题。

把它当代码一样对待：首版不必完美，允许重构，允许删减。

本地小工具：先体检，再提交

配套练习目录 practice/ 提供一个零依赖脚本 check_claude_md.py，对示例 CLAUDE.md 做「可维护性」体检：文件名大小写、必备章节、过长警告、模糊措辞扫描。

cd content/articles/2026-09/2026-09-15/claude-md-playbook/practice
python3 check_claude_md.py --file sample_CLAUDE.md

一次本地跑通的 stdout 节选：

[OK] filename case: CLAUDE.md
[OK] section: Project / Code Style / Commands / Architecture / Important
[WARN] line budget: 42 lines (soft limit 300) — fine
[FAIL] vague phrase: "写得干净一点" @ line 18 — rewrite as verifiable rule
[SUMMARY] 1 fail, 0 warn-blockers → fix before commit

把「模糊散文」拦在提交前，比指望模型自己悟更稳。

实操清单（可打印）

今天就能做

• 没有文件：跑 /init，删废话，补一句话项目背景 + 真实命令。
• 已有文件：下次纠错时，顺手让模型写回 CLAUDE.md。
• 确认文件名是 CLAUDE.md，个人癖好放 CLAUDE.local.md 并 gitignore。

写的时候

• 风格要可验证；命令要可复制；坑点要能防错。
• 控制体量；细节用 @import / 规则目录 / 子目录记忆承接。
• 关键红线可加强调，但只标真正关键的。

养的时候

• 边用边补；几周复盘一次；从 PR 评论回流约定。
• 大团队用 .claude/rules/ 分权；Monorepo 用子目录 CLAUDE.md。

小结

一份好的 CLAUDE.md，不是越厚越强，而是启动必知的事实写清、其余外置、纠错即时回写。从 /init 删到能用，用五段模板钉住结构，用引用与分层避免百科化，再用「纠错 → 复盘 → PR 回流」把它养成团队知识的一部分——几分钟的写法投入，会在后续每一个会话里省下大量复述与返工。

若你还要上路径级规则、Hooks 拦截危险 git push、只读 Subagent，那是配置栈下一层的事；先把主记忆文件写短、写准、写活，再往上加控制面，通常更稳。