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。