---
title: '02 高阶 System Prompt 与 CLAUDE.md'
video_id: UPtmKh1vMN8
part: 2
---

> 章节 2 / 29 · [[00-总览|课程总览]] · 起始 [00:57](https://youtu.be/UPtmKh1vMN8?t=57)


## 章节主旨

拆解 `CLAUDE.md`(即 Claude Code 的项目级 system prompt)到底承担哪四种角色——知识压缩、偏好约定、能力声明、失败成功日志——并指出它同时存在 global 与 local 两个层级,为后续"如何高效维护它"打底。

## 核心论点

1. **`CLAUDE.md` 不是一段"长咒语",而是四种功能的集合体**——把它当作有明确分区的结构文档,而非越长越好的提示词。([[#1-claudemd--四件事的集合而非一条长提示词-0302|→ 详解1]])
2. **它首先是知识压缩**:让 Claude 无需逐文件扫描整个 workspace 就能鸟瞰全局,省 token、省时间。([[#2-知识压缩让-claude-鸟瞰而非逐文件下钻-0302|→ 详解2]])
3. **它承载你个人的偏好与约定**:补齐 Claude Code 原生默认之外、滞后于用户实践的那部分习惯。([[#3-偏好与约定补齐原生默认滞后的那部分-0407|→ 详解3]])
4. **它是能力声明**:显式列出 agent 在本 workspace 里"能做什么",纠正 Claude 对自身 agency 的低估。([[#4-能力声明纠正-claude-对自身-agency-的低估-0505|→ 详解4]])
5. **它是失败与成功日志**:沉淀踩过的坑与验证过的做法,把解空间里已知无效的大片区域提前划掉。([[#5-失败与成功日志把解空间的已知无效区提前划掉-0712|→ 详解5]])

## 知识点详解

### 1. `CLAUDE.md` = 四件事的集合,而非一条长提示词 [03:02](https://youtu.be/UPtmKh1vMN8?t=182)

作者反对把 `CLAUDE.md` 写成"网上流传的那种又臭又长的 system prompt"。他的框架是:一份好的 `CLAUDE.md` 本质是四种功能的叠加——知识压缩、偏好与约定、能力声明、失败与成功日志。

这四者会以不同 section 存在于同一份文件里,也会分布在 global 与 local 两个层级(见详解6)。把它拆成四类,是为了让"该往里写什么"有据可依,而不是凭感觉堆文字。

价值在于:它把"写好 system prompt"从玄学变成可核对的清单——每加一段内容,都能问一句"这属于四类中的哪一类"。

### 2. 知识压缩:让 Claude 鸟瞰而非逐文件下钻 [03:02](https://youtu.be/UPtmKh1vMN8?t=182)

第一重角色是 知识压缩。没有它,Claude 要对代码库做高层判断,就得逐个文件夹、逐个文件读一遍,既烧 token 又慢。

`CLAUDE.md` 把整个 workspace 压成一份高度精炼的摘要:讲清"这个目录里到底在干什么",或至少给出"某类文件住在哪里"的引用指针。于是下次你问"几周前我做的那个关于 XYZ 的文件在哪",Claude 能在鸟瞰层面直接推理,而不必潜到细节里翻。

一句话:用一次性写好的摘要,换掉每次对话都要重复的全库扫描成本。

### 3. 偏好与约定:补齐原生默认滞后的那部分 [04:07](https://youtu.be/UPtmKh1vMN8?t=247)

第二重角色是 偏好与约定。Anthropic 每次更新 Claude Code,都会把更多"好习惯"(如何给文件路径、如何处理文档/调试、如何自我更新)烘焙进原生默认。

但原生默认必然滞后——官方要先观察大量用户的真实用法,才能把某种约定收进产品。因此高阶用户手上总会有一份"尚未被原生内置"的偏好清单:自己的编码规范、信息组织方式、结构约定等。

`CLAUDE.md` 就是安放这份清单的地方,让 Claude 按你的习惯而非通用默认来干活。

### 4. 能力声明:纠正 Claude 对自身 agency 的低估 [05:05](https://youtu.be/UPtmKh1vMN8?t=305)

第三重角色是 能力声明(declaration of capabilities)。若 `CLAUDE.md` 不够充实,而某个 skill 或某些知识散落在几个文件里,你让 Claude 去做,它常会"两手一摊":我没有内置的方式做这个,要不要我从零搭一个?——一轮完全多余的减速循环。

根因是:再 agentic,Claude 仍严重低估自己的 Agency。作者举例:问它某事要多久,它答"大概三个月,因为你得先建 A、再建 B、再建 C";而实际上"这些正是我要它建的,它 5 秒就能开工"。或者做 API 时它甩回一条命令行让你"自己粘到终端里",也需要被提醒——不,这正是我叫你做的。 [06:20](https://youtu.be/UPtmKh1vMN8?t=380)

对策是在 `CLAUDE.md` 里逐条列明 agent 当前"能做什么":能调这个 API、这个数据库,能自主跑一段 10–15 分钟的完整计划,能用浏览器自主行动等。把能力显式化,agent 就不会在第一眼看不出时误判自己无能为力。

### 5. 失败与成功日志:把解空间的已知无效区提前划掉 [07:12](https://youtu.be/UPtmKh1vMN8?t=432)

第四重角色是 失败与成功日志。项目里每一段代码、每个文件都是"hard won"——你花了 token 和时间才拿到,而这两者是"即将最值钱的两种资源"。

比复用更浪费的是让 Claude 每次从零重启。把每一次开发/行动的经验教训写进下一次的 system prompt,才是高效做法。

作者给了一个几何直觉:设想 Claude 面对某任务的全部可能做法构成一片解空间(theoretical solution space),失败/成功日志就是从中"切掉大块"、划出禁区——已经试过、不通的区域不必再碰,可行解只落在剩下的窄带里。 [08:01](https://youtu.be/UPtmKh1vMN8?t=481)

效果是:日志能立刻划掉约 80% 的可能做法,把时间、token、精力集中到真正有效的那 20%。

### 6. 两个层级:global 与 local [08:43](https://youtu.be/UPtmKh1vMN8?t=523)

上述四种功能不仅分 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 单项目)

## 自检问题

1. `CLAUDE.md` 承担哪四种角色?
   **答案**:知识压缩、偏好与约定、能力声明、失败与成功日志。四者以不同 section 存在,并分布在 global/local 两层。(详解1) [03:02](https://youtu.be/UPtmKh1vMN8?t=182)
2. "能力声明"要解决的核心问题是什么?
   **答案**:Claude 严重低估自身 agency,遇到没内置的任务会退回"要不要我从零搭"的减速循环;显式列明它能调哪些 API/数据库、能自主跑多长的计划,就能纠正误判。(详解4) [05:05](https://youtu.be/UPtmKh1vMN8?t=305)
3. "失败与成功日志"用什么直觉来解释它的价值?
   **答案**:把任务的全部可能做法看成一片解空间,日志切掉已知无效的大块(约 80%),让 Claude 只在剩下的 20% 窄带里尝试,省 token、省时间。(详解5) [08:01](https://youtu.be/UPtmKh1vMN8?t=481)
4. 为什么不建议把 `CLAUDE.md` 写成一条又长又全的 system prompt?
   **答案**:因为好的 `CLAUDE.md` 是四类功能的结构化集合而非"长咒语";按四类分区能让"该写什么"可核对,且内容还需按 global/local 分层安放。(详解1、详解6)