claude-mdlisted

# 写 / 优化 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. **常用命令