写 / 优化 CLAUDE.md
把"让 Claude 更懂这个项目"变成一份精炼、每行都有用、贴合本仓库真实情况的 CLAUDE.md。最佳实践已内置在本技能里,不需要每次再去社区/官网搜;若用户明确想要最新外部观点,references/reference.md 末尾列了权威来源。
先理解它是什么:上下文注入,不是文档
CLAUDE.md 在每次会话开始时被全量注入上下文(作为 system prompt 之后的一条 user message,不是强制配置,Claude 会尽量遵守但不保证)。两个直接后果决定了怎么写:
- 占 token,且越长遵从度越低。 文件越长,Claude 越倾向把里面的规则当成"可忽略"(它被包在标注 may-or-may-not-be-relevant 的提醒里)。塞太多 → 关键指令被噪声淹没,反而整体被无视。官方推荐:目标 < 200 行(memory 文档原文 "target under 200 lines",超过会降低遵从度)。
- 只在"每次会话都需要"时才值得占这个位置。 偶尔才用的多步流程、参考资料,应做成 skill 或放进
references/ 按需加载,而不是塞进每次会话。必须 100% 生效的红线(如"禁止改 .env")要用 hook 强制,prompt 里的规则只是"请求"。
黄金筛选法则(贯穿始终)
逐行自问:"删掉这一行,Claude 会不会因此犯错?" 不会 → 删掉。这是最重要的一条,写和优化时都用它过一遍。配套两条:
- Two-strikes(两次法则): 一个坑/约定,出现/纠正过两次才值得写进去。"一次是噪声,两次才是模式。"别凭空想象 Claude 理论上可能需要什么。
- 能交给确定性工具的,就不写进文件。 缩进/引号/import 顺序这类风格规则交给 linter/formatter/hook,别让 Claude 当 linter——慢、贵、还不可靠。
只写"从代码里看不出、容易判断错"的东西
| ✅ 该写 |
❌ 不该写 |
| Claude 猜不到的命令(build/test/lint/typecheck/本地运行/部署) |
读代码就能推断出来的东西 |
| 与默认不同的约定(import 别名、特定库/工具的非标准用法、项目自定的分层或模式) |
标准语言/框架惯例(Claude 已经会) |
| 本项目特有的架构决策、目录地图(尤其非显而易见的布局) |
README 式项目介绍、卖点、Getting Started |
| 环境怪癖(必需的环境变量、版本锁、降级分支) |
频繁变动的信息(具体 API 字段、易过期的细节) |
| 非显而易见的坑、反直觉行为(踩过的雷) |
逐文件的代码库描述、贴大段会过期的代码片段 |
| 仓库规范(分支命名、PR 约定、提交习惯) |
"写干净代码"这类不言自明的废话 |
经验法则:如果一段内容更像 README 或教程,它就不属于 CLAUDE.md。
推荐结构(可裁剪,按本项目实际取舍)
顺序大致 简介 → 命令 → 目录地图 → 约定 → 坑 → 指针,每段用 markdown 标题 + bullet,做到可扫读:
- 一两句简介 — 是什么 + 技术栈(给一张 mental map,别展开)。
- 常用命令 — 只列真实必需的:dev / build / test / lint / typecheck / 本地运行 / 部署。注明在哪个目录跑。
- 目录地图 — 非显而易见的布局(monorepo、非常规的源码/输出目录、生成目录、应用代码的实际所在、import 别名)。
- 关键约定 — 只写非默认的:项目自定的分层与模式、数据访问方式、接口/错误约定、鉴权模型、特定库的用法。
- 坑 / 反直觉行为 — 构建/部署的特殊处理、环境变量、易踩的雷。
- 指针(渐进式披露) — 偶尔才用的流程指向对应 skill 或
references//docs/ 文件,只留一句话 + 路径,不展开。
写法要点
- 具体优于模糊,声明式优于步骤流。 给可验证的成功终点并附上该项目的真实命令——写"提交前必须通过测试/类型检查(命令:…)"而不是"保证代码质量";写"改完后测试全绿、diff 不留调试输出"这种终点,而不是"读 A→改 B→跑 C"的步骤流(步骤流容易把 Claude 引进死路;它更擅长循环逼近一个明确目标)。
- 解释 why,而不是堆 MUST。 今天的模型有很好的 theory of mind。讲清"为什么这条重要"比一堆全大写 ALWAYS/NEVER 更有效,也更耐用。
- 强调要省着用。 每条都标 IMPORTANT/YOU MUST,强调就失效了。只在确实反复被忽略的关键规则上前缀一次。
- 用指针代替副本。 引用代码用
file:line(会随代码更新),别贴会过期的 snippet;大段参考资料给路径而非内容。
- 语言跟项目走。 项目用中文就写中文,英文就写英文;和现有 CLAUDE.md / README 保持一致。
工作流
1. 判断模式
新建一份,还是优化现有的?优化时先 Read 现有文件,但不要只盯着它改——务必结合下面的项目勘探,因为现有文件可能本身就有遗漏或过期。
2. 勘探项目真实情况(关键,不能跳)
目标是挖出"从代码看不出、需要文档说明"的事实。亲自 Read/Grep 或在大项目里派 Explore subagent 并行勘探,至少覆盖:
- 真实命令 — 读
package.json(或 Makefile / pyproject / cargo 等)的 scripts;分清 build 是否做类型检查、test/lint/typecheck 各自怎么跑。命令要真实可跑,必要时用 Bash 抽查。
- 目录布局 — 哪里是应用代码真正所在、有没有反直觉的嵌套/生成目录、import alias 配在哪。
- 约定与模式 — 项目自定的分层、数据访问、接口/错误约定、鉴权,以及特定库/工具的非标准用法。
- 坑 — 构建/部署的特殊处理、必需环境变量、本地与生产的差异、降级分支。
- 辅助信源 — README、现有 CLAUDE.md、
git log,但只取从代码看不出的部分。
3. 起草 / 优化
- 新建:套上面的结构,每段只放通过黄金法则的内容。宁可短。
- 优化:逐行过黄金法则删废话 → 补上缺失的命令/目录地图 → 合并矛盾或重复条目 → 把偶尔才用的多步流程挪去 skill 或
references/ 留指针 → 把模糊指令改成具体命令/可验证终点。
4. 自查清单(交付前对照)
5. 交付与维护建议
给出改动说明。可顺带提醒用户:CLAUDE.md 要当 living doc——架构变更时在同一个 PR 顺手更新;发现 Claude 第二次犯同样的错时再往里加;别配一次就不管(三个月后容易在遵守不再适用的指令)。
更深的机制 / 数据 / 反模式目录 / 参考实例
需要时读 references/reference.md:层级体系(user/project/local/嵌套加载顺序)、@path import 语法与限制、/init 与 /memory、长度阈值的各家实测数据与矛盾点、完整反模式清单、monorepo 处理、CLAUDE.md vs Skills vs Rules vs Hooks 的官方分界,以及可参考的优秀 CLAUDE.md 仓库与权威来源 URL。
1---2name: claude-md3description: 创建或优化仓库的 CLAUDE.md。4---56# 写 / 优化 CLAUDE.md78把"让 Claude 更懂这个项目"变成一份**精炼、每行都有用、贴合本仓库真实情况**的 CLAUDE.md。最佳实践已内置在本技能里,**不需要每次再去社区/官网搜**;若用户明确想要最新外部观点,`references/reference.md` 末尾列了权威来源。910## 先理解它是什么:上下文注入,不是文档1112CLAUDE.md 在**每次会话开始时被全量注入**上下文(作为 system prompt 之后的一条 user message,不是强制配置,Claude 会尽量遵守但不保证)。两个直接后果决定了怎么写:13141. **占 token,且越长遵从度越低。** 文件越长,Claude 越倾向把里面的规则当成"可忽略"(它被包在标注 may-or-may-not-be-relevant 的提醒里)。塞太多 → 关键指令被噪声淹没,反而整体被无视。官方推荐:**目标 < 200 行**(memory 文档原文 "target under 200 lines",超过会降低遵从度)。152. **只在"每次会话都需要"时才值得占这个位置。** 偶尔才用的多步流程、参考资料,应做成 skill 或放进 `references/` 按需加载,而不是塞进每次会话。必须 100% 生效的红线(如"禁止改 .env")要用 hook 强制,prompt 里的规则只是"请求"。1617## 黄金筛选法则(贯穿始终)1819逐行自问:**"删掉这一行,Claude 会不会因此犯错?"** 不会 → 删掉。这是最重要的一条,写和优化时都用它过一遍。配套两条:2021- **Two-strikes(两次法则):** 一个坑/约定,出现/纠正过**两次**才值得写进去。"一次是噪声,两次才是模式。"别凭空想象 Claude 理论上可能需要什么。22- **能交给确定性工具的,就不写进文件。** 缩进/引号/import 顺序这类风格规则交给 linter/formatter/hook,别让 Claude 当 linter——慢、贵、还不可靠。2324## 只写"从代码里看不出、容易判断错"的东西2526| ✅ 该写 | ❌ 不该写 |27|---|---|28| Claude 猜不到的命令(build/test/lint/typecheck/本地运行/部署) | 读代码就能推断出来的东西 |29| 与默认**不同**的约定(import 别名、特定库/工具的非标准用法、项目自定的分层或模式) | 标准语言/框架惯例(Claude 已经会) |30| 本项目特有的架构决策、目录地图(尤其非显而易见的布局) | README 式项目介绍、卖点、Getting Started |31| 环境怪癖(必需的环境变量、版本锁、降级分支) | 频繁变动的信息(具体 API 字段、易过期的细节) |32| 非显而易见的坑、反直觉行为(踩过的雷) | 逐文件的代码库描述、贴大段会过期的代码片段 |33| 仓库规范(分支命名、PR 约定、提交习惯) | "写干净代码"这类不言自明的废话 |3435> 经验法则:如果一段内容更像 README 或教程,它就不属于 CLAUDE.md。3637## 推荐结构(可裁剪,按本项目实际取舍)3839顺序大致 **简介 → 命令 → 目录地图 → 约定 → 坑 → 指针**,每段用 markdown 标题 + bullet,做到可扫读:40411. **一两句简介** — 是什么 + 技术栈(给一张 mental map,别展开)。422. **常用命令** — 只列真实必需的:dev / build / test / lint / typecheck / 本地运行 / 部署。注明在哪个目录跑。433. **目录地图** — 非显而易见的布局(monorepo、非常规的源码/输出目录、生成目录、应用代码的实际所在、import 别名)。444. **关键约定** — 只写**非默认**的:项目自定的分层与模式、数据访问方式、接口/错误约定、鉴权模型、特定库的用法。455. **坑 / 反直觉行为** — 构建/部署的特殊处理、环境变量、易踩的雷。466. **指针(渐进式披露)** — 偶尔才用的流程指向对应 skill 或 `references/`/`docs/` 文件,只留一句话 + 路径,不展开。4748## 写法要点4950- **具体优于模糊,声明式优于步骤流。** 给**可验证的成功终点**并附上该项目的真实命令——写"提交前必须通过测试/类型检查(命令:…)"而不是"保证代码质量";写"改完后测试全绿、diff 不留调试输出"这种终点,而不是"读 A→改 B→跑 C"的步骤流(步骤流容易把 Claude 引进死路;它更擅长循环逼近一个明确目标)。51- **解释 why,而不是堆 MUST。** 今天的模型有很好的 theory of mind。讲清"为什么这条重要"比一堆全大写 ALWAYS/NEVER 更有效,也更耐用。52- **强调要省着用。** 每条都标 IMPORTANT/YOU MUST,强调就失效了。只在**确实反复被忽略**的关键规则上前缀一次。53- **用指针代替副本。** 引用代码用 `file:line`(会随代码更新),别贴会过期的 snippet;大段参考资料给路径而非内容。54- **语言跟项目走。** 项目用中文就写中文,英文就写英文;和现有 CLAUDE.md / README 保持一致。5556## 工作流5758### 1. 判断模式59新建一份,还是优化现有的?优化时先 `Read` 现有文件,但**不要只盯着它改**——务必结合下面的项目勘探,因为现有文件可能本身就有遗漏或过期。6061### 2. 勘探项目真实情况(关键,不能跳)62目标是挖出"从代码看不出、需要文档说明"的事实。亲自 `Read`/`Grep` 或在大项目里派 `Explore` subagent 并行勘探,至少覆盖:6364- **真实命令** — 读 `package.json`(或 Makefile / pyproject / cargo 等)的 scripts;分清 build 是否做类型检查、test/lint/typecheck 各自怎么跑。命令要**真实可跑**,必要时用 Bash 抽查。65- **目录布局** — 哪里是应用代码真正所在、有没有反直觉的嵌套/生成目录、import alias 配在哪。66- **约定与模式** — 项目自定的分层、数据访问、接口/错误约定、鉴权,以及特定库/工具的非标准用法。67- **坑** — 构建/部署的特殊处理、必需环境变量、本地与生产的差异、降级分支。68- **辅助信源** — README、现有 CLAUDE.md、`git log`,但**只取从代码看不出的**部分。6970### 3. 起草 / 优化71- **新建**:套上面的结构,每段只放通过黄金法则的内容。宁可短。72- **优化**:逐行过黄金法则删废话 → 补上缺失的命令/目录地图 → 合并矛盾或重复条目 → 把偶尔才用的多步流程挪去 skill 或 `references/` 留指针 → 把模糊指令改成具体命令/可验证终点。7374### 4. 自查清单(交付前对照)75- [ ] 每一行都通过"删了 Claude 会犯错吗"?76- [ ] 总长 < ~200 行?distinct 指令条数 < ~50?(越短越好,但别把关键信息也砍掉——精简有下限)77- [ ] 有没有混进 README 式介绍 / 代码能推断的东西 / 风格规则?清掉。78- [ ] 列出的命令都验证过真实可跑?79- [ ] 偶尔才用的多步流程是否已挪去 skill / references,只留指针?80- [ ] 必须 100% 生效的红线,是否提示用户用 hook 而非 prompt?81- [ ] 语言与项目一致?结构可扫读?8283### 5. 交付与维护建议84给出改动说明。可顺带提醒用户:CLAUDE.md 要当 living doc——**架构变更时在同一个 PR 顺手更新**;发现 Claude 第二次犯同样的错时再往里加;别配一次就不管(三个月后容易在遵守不再适用的指令)。8586## 更深的机制 / 数据 / 反模式目录 / 参考实例8788需要时读 `references/reference.md`:层级体系(user/project/local/嵌套加载顺序)、`@path` import 语法与限制、`/init` 与 `/memory`、长度阈值的各家实测数据与矛盾点、完整反模式清单、monorepo 处理、CLAUDE.md vs Skills vs Rules vs Hooks 的官方分界,以及可参考的优秀 CLAUDE.md 仓库与权威来源 URL。
dootask