# Claude Md

> 创建或优化仓库的 CLAUDE.md。

- Skill: `dootask/claude-md` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add dootask/claude-md`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dootask/claude-md/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dootask (https://skillmd.com/u/dootask)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dootask/claude-md

---


# 写 / 优化 CLAUDE.md

把"让 Claude 更懂这个项目"变成一份**精炼、每行都有用、贴合本仓库真实情况**的 CLAUDE.md。最佳实践已内置在本技能里,**不需要每次再去社区/官网搜**;若用户明确想要最新外部观点,`references/reference.md` 末尾列了权威来源。

## 先理解它是什么:上下文注入,不是文档

CLAUDE.md 在**每次会话开始时被全量注入**上下文(作为 system prompt 之后的一条 user message,不是强制配置,Claude 会尽量遵守但不保证)。两个直接后果决定了怎么写:

1. **占 token,且越长遵从度越低。** 文件越长,Claude 越倾向把里面的规则当成"可忽略"(它被包在标注 may-or-may-not-be-relevant 的提醒里)。塞太多 → 关键指令被噪声淹没,反而整体被无视。官方推荐:**目标 < 200 行**(memory 文档原文 "target under 200 lines",超过会降低遵从度)。
2. **只在"每次会话都需要"时才值得占这个位置。** 偶尔才用的多步流程、参考资料,应做成 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,做到可扫读:

1. **一两句简介** — 是什么 + 技术栈(给一张 mental map,别展开)。
2. **常用命令** — 只列真实必需的:dev / build / test / lint / typecheck / 本地运行 / 部署。注明在哪个目录跑。
3. **目录地图** — 非显而易见的布局(monorepo、非常规的源码/输出目录、生成目录、应用代码的实际所在、import 别名)。
4. **关键约定** — 只写**非默认**的:项目自定的分层与模式、数据访问方式、接口/错误约定、鉴权模型、特定库的用法。
5. **坑 / 反直觉行为** — 构建/部署的特殊处理、环境变量、易踩的雷。
6. **指针(渐进式披露)** — 偶尔才用的流程指向对应 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. 自查清单(交付前对照)
- [ ] 每一行都通过"删了 Claude 会犯错吗"?
- [ ] 总长 < ~200 行?distinct 指令条数 < ~50?(越短越好,但别把关键信息也砍掉——精简有下限)
- [ ] 有没有混进 README 式介绍 / 代码能推断的东西 / 风格规则?清掉。
- [ ] 列出的命令都验证过真实可跑?
- [ ] 偶尔才用的多步流程是否已挪去 skill / references,只留指针?
- [ ] 必须 100% 生效的红线,是否提示用户用 hook 而非 prompt?
- [ ] 语言与项目一致?结构可扫读?

### 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。