CLAUDE.md 怎么写：项目记忆文件模板与反例
Claude Code 每次新开会话上下文都是空的。构建命令、目录约定、你说过多少次「先跑测试」，要靠记忆文件续上。CLAUDE.md 就是这份项目记忆：你写明文规则，开局自动读入。下面按官方 Memory 文档整理写法和反例，并在本机用 Claude Code 2.1.309（2026-10-28，北京时间）搭可丢弃 demo，核对路径与文件布局。
环境：Debian box；claude --version → 2.1.309 (Claude Code)；演示目录 /workspace/proj-test/claude-md-demo。本机核对了版本、记忆文件路径与布局；加载顺序与截断数字以 官方 Memory 文档为准。
它读哪些文件：先把位置记死
Claude Code 把「你写的持久说明」和「它自己记的笔记（auto memory）」分开。你要管的是前者：若干份 Markdown，会话开始拼进上下文。官方把它们当上下文指引；要硬拦危险动作，仍靠 permissions 或 Hooks。
| 范围 | 路径 | 谁共享 |
|---|---|---|
| 组织策略 | Linux：/etc/claude-code/CLAUDE.md | 整机所有用户 |
| 用户偏好 | ~/.claude/CLAUDE.md | 仅你，跨项目 |
| 项目说明 | ./CLAUDE.md 或 ./.claude/CLAUDE.md | 进 git，给团队 |
| 个人本地 | ./CLAUDE.local.md（建议 gitignore） | 仅你，当前仓 |
| 子目录 | 子树里的 CLAUDE.md | 触达该目录文件时按需加载 |
加载顺序从宽到窄：策略 → 用户 → 项目 → 本地；同目录里 CLAUDE.local.md 排在 CLAUDE.md 后面。祖先目录的文件在启动时就读；子目录的要等 Claude 在那个子目录里读/写/编辑了别的文件（含对单文件的 cat/head）才进上下文。多份文件是拼接，不是后者覆盖前者——互相打架时它可能随便跟一条。
本机核对：用户级与托管策略文件都不存在；项目里放了根 CLAUDE.md、CLAUDE.local.md、src/CLAUDE.md 与一条 path 规则。
~/.claude/CLAUDE.md 与 /etc/claude-code/CLAUDE.md 均 absent。怎么写：短、可核对、可执行
官方建议写成你会反复口述的事实——构建命令、目录约定、「永远 / 绝不」规则。能验证的句子优于形容词：
- 写「用 2 空格缩进」，别写「把代码写得漂亮」。
- 写「提交前跑
npm test」，别写「记得测试」。 - 写「API 处理器在
src/api/handlers/」，别写「文件整理好一点」。
官方建议单份 CLAUDE.md 目标 200 行以内；再长既吃上下文，也更容易被忽略。多步流程或只对某类文件有用的细则，挪到 Skill，或下面的 path 规则。用 @path/to/file 可以 import 额外文件，但不会省上下文——被 import 的内容会和主文件一起进来；路径含空格要写成 @Design\ Docs/x.md，加引号反而不会被当成 import。
demo 里用的短模板（19 行、489 字符）大致如下，可直接改项目名与命令：
# Project memory for demo-api
## Build & test
- Install: `npm ci`
- Dev: `npm run dev` (port 3000)
- Test: `npm test` — always run before claiming done
## Layout
- `src/` handlers and routes
- `docs/` design notes; do not invent APIs not listed here
## Always
- Prefer editing existing files over creating new ones
- Never commit `.env` or secrets
- Use Conventional Commits
## Never
- Do not rewrite large files without reading them first
- Do not add new dependencies without asking
.claude/rules/api-ts.md 用 paths: src/**/*.ts 限定范围；claude --help 写明 --bare 会跳过 CLAUDE.md 自动发现。根文件里只留命令、路径和「永远 / 绝不」；写得出验收标准的句子，会话里才跟得住。
反例：空话、百科、互相打架
| 反例 | 问题 | 改法 |
|---|---|---|
| 「请务必认真、优雅、可维护」 | 无法验收 | 换成具体格式/测试/目录规则 |
| 把 README + 路线图 + 公司史整进一份 | 超长、冲淡重点 | 砍到每会话都要用的事实；其余用 @ 或规则拆开 |
| 根文件说「必须 pnpm」，子目录说「只用 npm」 | 拼接后冲突，跟哪条不确定 | 定一条真源；定期 /doctor prompt-audit（需较新版本） |
| 只在聊天里说「下次记住」 | 压缩后易丢 | 写进根 CLAUDE.md；根文件在 /compact 后会重新从磁盘注入 |
仓库若已有给其他 Agent 用的 AGENTS.md：默认在「工作目录及以上没有 CLAUDE.md / CLAUDE.local.md」时，Claude Code 会读 AGENTS.md；一旦你加了项目级 CLAUDE.md，默认就只跟 Claude 那套。两边都要时，可用设置里的 Project instructions，或在 CLAUDE.md 里 @AGENTS.md。安全侧别忘了：可写目录里的指令文件本身也是攻击面，见Downloads 自查。
细则放到 .claude/rules/，别全塞进根文件
项目变大后，把主题拆进 .claude/rules/*.md。没有 paths 的规则与项目 CLAUDE.md 同级、启动就加载；带 YAML frontmatter 的只在匹配文件被读写时加载，例如：
---
paths:
- "src/**/*.ts"
---
# API TypeScript rules
- Validate all request bodies with zod
- Return `{ ok: false, error }` on failure — never throw raw strings
个人跨项目偏好可以放 ~/.claude/rules/。需要确认当前会话装了哪些记忆文件时，官方说在会话里跑 /context（Memory files 列表）或 /memory 打开编辑。
体积、截断与大文件写入
官方 Memory 文档：启动加载的 CLAUDE.md 只要不超过约 4 MiB 会整份进入；超过则整份跳过。子目录 CLAUDE.md、按需 rules、@ import 等按需加载的文件另有单文件上限——在 200K 上下文窗口上约 40,000 字符（文档写明该上限自 v2.1.309 起作用于按需文件）。超限时模型只拿到文件开头，并附「用 Read 读剩余」的提示；尾部规则在它主动读完之前都不在上下文里。
Anthropic 官方 CHANGELOG 2.1.312 记了一条相关修复：模型在只看到很大的子目录 CLAUDE.md / rules / @ 文件开头时，不再直接整文件覆盖；Write 会要求先读完整份或就地编辑。写长记忆文件时，宁可用 Edit，也不要假设「它已经看见全文」。
claude --help 也写明：加 --bare 会跳过 hooks、auto-memory 与 CLAUDE.md 自动发现——自动化脚本若指望记忆文件，别误开 --bare，或改用 --append-system-prompt / --add-dir 显式喂上下文。
常见坑
- 写了但不生效：先确认文件名与位置（根或
.claude/CLAUDE.md）；子目录文件要触达该目录才会加载。指令太虚或互相冲突时，跟从率会掉。 - 把强制约束只写在 md：「禁止删生产库」这类要用 deny / Hook，不能只靠记忆文件。
- 用 import 当「减肥」：
@只整理结构，总上下文成本照旧；该瘦身就删或改 path 规则。 - 本地偏好进了 git：
CLAUDE.local.md进版本库会把个人沙箱 URL 泄漏给同事——加入.gitignore。
完成标准
- 仓库根（或
.claude/）有一份 <200 行的CLAUDE.md，含构建/测试命令与 Always/Never。 - 个人 URL、本机路径放在
CLAUDE.local.md且已 gitignore。 - 仅对某路径有用的细则进了
.claude/rules/，需要时带paths。 - 本机
claude --version可运行；需要时能用/context看到 Memory files（官方验收方式）。
最后
先写一页根 CLAUDE.md，再按痛点把细则拆进 rules。权限与 Hook 管硬边界，记忆文件少让你重复口述。接下来可看站内权限配置和grill-me 访谈 Skill。
