章节主旨
拆解 CLAUDE.md(即 Claude Code 的项目级 system prompt)到底承担哪四种角色——知识压缩、偏好约定、能力声明、失败成功日志——并指出它同时存在 global 与 local 两个层级,为后续”如何高效维护它”打底。
核心论点
CLAUDE.md不是一段”长咒语”,而是四种功能的集合体——把它当作有明确分区的结构文档,而非越长越好的提示词。(→ 详解1)- 它首先是知识压缩:让 Claude 无需逐文件扫描整个 workspace 就能鸟瞰全局,省 token、省时间。(→ 详解2)
- 它承载你个人的偏好与约定:补齐 Claude Code 原生默认之外、滞后于用户实践的那部分习惯。(→ 详解3)
- 它是能力声明:显式列出 agent 在本 workspace 里”能做什么”,纠正 Claude 对自身 agency 的低估。(→ 详解4)
- 它是失败与成功日志:沉淀踩过的坑与验证过的做法,把解空间里已知无效的大片区域提前划掉。(→ 详解5)
知识点详解
1. CLAUDE.md = 四件事的集合,而非一条长提示词 03:02
作者反对把 CLAUDE.md 写成”网上流传的那种又臭又长的 system prompt”。他的框架是:一份好的 CLAUDE.md 本质是四种功能的叠加——知识压缩、偏好与约定、能力声明、失败与成功日志。
这四者会以不同 section 存在于同一份文件里,也会分布在 global 与 local 两个层级(见详解6)。把它拆成四类,是为了让”该往里写什么”有据可依,而不是凭感觉堆文字。
价值在于:它把”写好 system prompt”从玄学变成可核对的清单——每加一段内容,都能问一句”这属于四类中的哪一类”。
2. 知识压缩:让 Claude 鸟瞰而非逐文件下钻 03:02
第一重角色是 知识压缩。没有它,Claude 要对代码库做高层判断,就得逐个文件夹、逐个文件读一遍,既烧 token 又慢。
CLAUDE.md 把整个 workspace 压成一份高度精炼的摘要:讲清”这个目录里到底在干什么”,或至少给出”某类文件住在哪里”的引用指针。于是下次你问”几周前我做的那个关于 XYZ 的文件在哪”,Claude 能在鸟瞰层面直接推理,而不必潜到细节里翻。
一句话:用一次性写好的摘要,换掉每次对话都要重复的全库扫描成本。
3. 偏好与约定:补齐原生默认滞后的那部分 04:07
第二重角色是 偏好与约定。Anthropic 每次更新 Claude Code,都会把更多”好习惯”(如何给文件路径、如何处理文档/调试、如何自我更新)烘焙进原生默认。
但原生默认必然滞后——官方要先观察大量用户的真实用法,才能把某种约定收进产品。因此高阶用户手上总会有一份”尚未被原生内置”的偏好清单:自己的编码规范、信息组织方式、结构约定等。
CLAUDE.md 就是安放这份清单的地方,让 Claude 按你的习惯而非通用默认来干活。
4. 能力声明:纠正 Claude 对自身 agency 的低估 05:05
第三重角色是 能力声明(declaration of capabilities)。若 CLAUDE.md 不够充实,而某个 skill 或某些知识散落在几个文件里,你让 Claude 去做,它常会”两手一摊”:我没有内置的方式做这个,要不要我从零搭一个?——一轮完全多余的减速循环。
根因是:再 agentic,Claude 仍严重低估自己的 Agency。作者举例:问它某事要多久,它答”大概三个月,因为你得先建 A、再建 B、再建 C”;而实际上”这些正是我要它建的,它 5 秒就能开工”。或者做 API 时它甩回一条命令行让你”自己粘到终端里”,也需要被提醒——不,这正是我叫你做的。 06:20
对策是在 CLAUDE.md 里逐条列明 agent 当前”能做什么”:能调这个 API、这个数据库,能自主跑一段 10–15 分钟的完整计划,能用浏览器自主行动等。把能力显式化,agent 就不会在第一眼看不出时误判自己无能为力。
5. 失败与成功日志:把解空间的已知无效区提前划掉 07:12
第四重角色是 失败与成功日志。项目里每一段代码、每个文件都是”hard won”——你花了 token 和时间才拿到,而这两者是”即将最值钱的两种资源”。
比复用更浪费的是让 Claude 每次从零重启。把每一次开发/行动的经验教训写进下一次的 system prompt,才是高效做法。
作者给了一个几何直觉:设想 Claude 面对某任务的全部可能做法构成一片解空间(theoretical solution space),失败/成功日志就是从中”切掉大块”、划出禁区——已经试过、不通的区域不必再碰,可行解只落在剩下的窄带里。 08:01
效果是:日志能立刻划掉约 80% 的可能做法,把时间、token、精力集中到真正有效的那 20%。
6. 两个层级:global 与 local 08:43
上述四种功能不仅分 section,还分层:既有 global 层(跨项目的个人级),也有 local 层(单项目级)。同一类内容会按作用范围落到不同层。
作者预告:接下来会讲这四条原则在 global/local 各自的高 ROI 组合方式,以及一套”如何有效更新 CLAUDE.md”的工作流循环——本章只负责把”它是什么”讲透,“怎么维护”留到后文。
术语
- system prompt(系统提示词,喂给 agent 定调其行为与知识的顶层文本)
- CLAUDE.md(Claude Code 的项目级 system prompt 文件,承载知识压缩/偏好/能力/日志四类内容)
- knowledge compression(知识压缩,把整个 workspace 压成可鸟瞰的精炼摘要)
- declaration of capabilities(能力声明,显式列出 agent 在本 workspace 能做什么)
- agency(能动性,agent 主动采取行动完成任务的能力;Claude 常低估自己的这一项)
- global / local(全局层 / 局部层,system prompt 的两级作用范围:跨项目 vs 单项目)
自检问题
CLAUDE.md承担哪四种角色? 答案:知识压缩、偏好与约定、能力声明、失败与成功日志。四者以不同 section 存在,并分布在 global/local 两层。(详解1) 03:02- “能力声明”要解决的核心问题是什么? 答案:Claude 严重低估自身 agency,遇到没内置的任务会退回”要不要我从零搭”的减速循环;显式列明它能调哪些 API/数据库、能自主跑多长的计划,就能纠正误判。(详解4) 05:05
- “失败与成功日志”用什么直觉来解释它的价值? 答案:把任务的全部可能做法看成一片解空间,日志切掉已知无效的大块(约 80%),让 Claude 只在剩下的 20% 窄带里尝试,省 token、省时间。(详解5) 08:01
- 为什么不建议把
CLAUDE.md写成一条又长又全的 system prompt? 答案:因为好的CLAUDE.md是四类功能的结构化集合而非”长咒语”;按四类分区能让”该写什么”可核对,且内容还需按 global/local 分层安放。(详解1、详解6)