章节主旨
讲 Claude Code 的 prompt 组织机制:CLAUDE.md 分 global(用户级)与 local(项目级)两个 scope,各自该装什么内容,以及如何用两条 workflow 分别维护它们。
核心论点
- Claude Code 启动时会加载两层
CLAUDE.md——global 与 local——拼成注入上下文顶部的 system prompt。(→ 详解1) - global 装高层推理与个人偏好、local 装项目低层知识,是由「global 每次都注入」这一事实推导出的分工。(→ 详解2)
- local 应尽量把项目知识(甚至整份 API 文档)就地内联,以减少工具调用、省 token、更快更准。(→ 详解3)
- 别照抄别人的
CLAUDE.md,理解原理后自建,并用专门的 workflow 持续更新两层文件。(→ 详解4)
知识点详解
1. global 与 local 两个 scope 09:18
Claude Code 初始化时会去若干位置读取要注入 context 顶部的 prompt。对使用者关键的是两处:user(等价 global)与 project(等价 local)。
放在用户主目录 CLAUDE.md 里的内容,无论你在哪个 workspace 开 session 都会被加载;放在项目仓库 .claude 目录下的 CLAUDE.md 则只在该仓库内被加载。
于是形成一个「全局优先注入、局部叠加」的结构:global 每次运行都在,local 是针对当前项目的小块补充。作者强调,他之后说的 System Prompt 指的是这两者合起来,不是单指某一个。
参考本项目:~/.claude/CLAUDE.md 是 global,仓库根的 CLAUDE.md 是 local,正是这套双层结构的实例。
2. 两层的内容分工 10:37
因为 global 每次都注入,分工策略随之而定:global 放高层推理与个人信念,local 放项目的低层具体知识。(System Prompt = 二者之和,见详解1 10:20)
global 里适合写三类:个人偏好(如「返回文件时给可点击的绝对路径」)、编程约定(如统一用 OOP 或 Rust)、以及「能力授权」——明确告诉 Claude「你其实能做 X,若你以为不能,那是你错了」。
一个具体偏好例子:遇到不熟的工具,先读官方 API 文档再动手,因为过往裸上手总是空转、浪费 token;若文档是 JS 动态加载的,就挂 Chrome DevTools MCP 去取。
local 则写项目描述、各部分位置与用途、低层偏好(如某个 API 的具体用法),让 Claude 靠读 CLAUDE.md 就能掌握 workspace,而不必逐个文件翻。
3. local 内联知识以省调用 13:10
/init(视频里写作 \init)会生成一份 workspace 知识的压缩版,让 Claude 日后读这份 CLAUDE.md 即可大致理解项目结构与目的,不用每次遍历全部文件。(12:11)
更进一步:若项目要用某个第三方 API,可以把整份 API 文档直接放进项目内联。这样 Claude 不必派 research subagent 去外部抓取,本地就能读到。
收益是三重的:减少总工具调用次数、降低 token 用量、并且更快更准。核心思路是用「就地可读的静态知识」替换「运行时的动态检索」。
4. 两条 workflow 与自建原则 13:45
作者区分两条 workflow:local workflow 负责更新项目的 local CLAUDE.md,global workflow 负责更新用户的 global CLAUDE.md。两层各有专门的维护动作,而非一次写死。
关键态度:不要指望别人把一份现成 CLAUDE.md 端上来照抄。理解背后原理、据此自建,才能成为更强的开发者、也更高产。
换言之,CLAUDE.md 的价值不在模板本身,而在你为「global 放什么、local 放什么」所做的判断——这份判断只能由你结合自己的工作方式长出来。
术语
- scope(作用域):此处指 prompt 的加载范围,分 global(用户级、全局)与 local(项目级、局部)。
- CLAUDE.md:被 Claude Code 注入 context 顶部的 Markdown 指令文件,分 global 与 local 两份。
- system prompt(系统提示):作者语境下指 global + local 两份
CLAUDE.md合并后的注入内容。 /init:生成 workspace 知识压缩版并写入 localCLAUDE.md的初始化命令。
自检问题
- global 与 local 的
CLAUDE.md在「何时被加载」上有何本质区别?这一区别如何决定各自该装什么? 答案:global(用户主目录)每次开 session 都注入,与在哪个 workspace 无关;local 只在其所属项目仓库内被加载。正因 global 恒在,才把高层推理/个人偏好/能力授权放 global,把项目专属的低层知识放 local。见详解1、2 10:37 - 为什么作者建议把整份第三方 API 文档内联进 local?带来哪几项收益? 答案:让 Claude 本地即可读到,不必派 research subagent 外出抓取;收益是减少工具调用、省 token、更快更准。见详解3 13:10
- 作者为何不直接给一份现成
CLAUDE.md让人照抄? 答案:因为价值在于理解「global/local 各放什么」的原理并自建,照抄学不到判断;自建才能成为更强、更高产的开发者。见详解4 13:45