第 3 章 · 03 CLAUDE.md 的黄金法则与最佳实践

第 3 章 · 03 CLAUDE.md 的黄金法则与最佳实践

本节摘要:本节是原书 claude-md 技能(CLAUDE.md 最佳实践专家)的核心提炼,含七条黄金法则:①LLM 是无状态的(CLAUDE.md 是唯一自动包含的文件);②少即是多(前沿 LLM 约能遵循 150-200 条指令,系统提示词已占约 50 条);③只放通用信息(任务说明放单独文件);④不要把 Claude 当 lint 工具(风格规则交给 prettier/eslint);⑤绝不自动生成(它是"AI harness 中杠杆最高的位置",应手工深思);⑥内容按 WHAT/WHY/HOW 组织;⑦大项目用渐进披露。质量约束:<300 行(理想 <100)、无风格规则、无任务说明、无代码片段、不重复 README。附最佳实践清单与 AGENTS.md 的处理澄清。

学习目标

阅读完本节,你应当能够:

1. 背出黄金法则至少五条,并用"150-200 条指令"解释"少即是多"。
2. 解释"不要把 Claude 当 lint 工具"背后的上下文成本逻辑。
3. 说出 CLAUDE.md 的质量约束(<300 行、无风格规则、无任务说明等)。
4. 说出反模式清单与 AGENTS.md 的正确处理方式。

一、七条黄金法则(原书经验)

1. LLM 是无状态的:CLAUDE.md 是每次对话唯一自动包含的文件,是 agent 了解代码库的主要入口——它就是你项目的"记忆起点"。
2. 少即是多:前沿 LLM 大约能遵循 150-200 条指令,而 Claude Code 的系统提示词已占约 50 条——CLAUDE.md 必须聚焦,塞得越多,真正被遵循的越少。
3. 只放通用信息:任务特定说明放单独文件(或用 skill/命令承载),CLAUDE.md 只放跨任务的规则与事实。
4. 不要把 Claude 当 lint 工具:风格指南会膨胀上下文、降低指令遵循——交给 prettier/eslint 等确定性工具,而不是让 AI 每次记住。
5. 绝不自动生成:CLAUDE.md 是"AI harness 中杠杆最高的位置",应手工深思熟虑地写——自动生成的产物往往是不痛不痒的废话。
6. 内容按 WHAT/WHY/HOW 三维组织:项目是什么、为什么这么设计、怎么开发运行。
7. 大项目用渐进披露:用 agent_docs/ 分层加载,用 file:line 引用而非代码片段。

原书注释:"系统提醒会告诉 Claude,CLAUDE.md '可能相关也可能不相关'——噪音越多,越容易被忽略。"

二、质量约束与反模式

质量约束:<300 行(理想 <100)、无风格规则、无任务说明、无代码片段、不重复 README。

反模式清单(不要写进 CLAUDE.md):风格指南、如何使用 Claude 的说明、泛泛的最佳实践、TODO 列表等。

三、AGENTS.md 的处理(原书澄清)

Claude Code 不直接读 AGENTS.md(GitHub 生态的 agent 规范文件)——需要 @AGENTS.md 导入,或建立软链到 CLAUDE.md。这是多工具协同(如 GitHub Copilot 与 Claude Code 共用仓库)时的关键细节。

四、记忆最佳实践清单

应做:项目记忆存团队标准、目录记忆存局部差异、先简后繁、可重复内容写进 CLAUDE.md;优先引用已有文档而非重复粘贴(@ 引用)。

不做:不要把 README 整份复制进来、不要塞实现细节、不要让记忆变垃圾桶、定期清理过期/冲突规则。

小结

黄金法则的底层逻辑只有一条:上下文是稀缺资源,而 CLAUDE.md 是每次对话都占用它的文件——所以它必须短、准、通用、手工打磨。写 CLAUDE.md 的标准不是"信息全",而是"噪音少"。下一章看与命令同源的另一种载体:技能 Skills。