Claude Code 编程白皮书

这本书写给谁

写给三类人：

• 用过几次 Claude Code，知道它能写代码，但不清楚它为什么忽好忽坏的人。第一、二、三章会给你答案。
• 想把它真当工程工具来用、要做到稳定可交付的人。第四到第七章是工程篇，讲怎么把它放进一个真实的工作流里。
• 已经在用 Claude Code 干活，想往自动化和团队规模化推进的人。第八到第十章讲的是落地、协作和长期生态。

怎么读

按顺序读。每一章的论证依赖前一章——你跳读看「Skills 该怎么写」却没读「Agent Loop 怎么转」，写出的 Skill 大概率不会被触发。 每章末尾会给一个实践收口，写明这一章读完后你应该能在自己工作流里做什么改动。如果你只想找具体技巧，最后的附录是 30 篇 wiki 原文索引。

一LLM 的工作本质

要用对 Claude Code，先要承认它的物理基础——一个自回归的、有 O(n²) 注意力机制的、没有"先想再说"能力的概率模型。 这一章不讲技巧，讲它的"五个先天缺陷"。所有后面的工程实践，本质都是在补这些缺陷。

自回归：边说边想

大模型生成文本的方式是一个 token 一个 token 往外蹦。没有"先想好再说"这回事——它预测下一个词的时候，唯一的依据就是前面所有的词。

这个机制的直接后果：模型写代码跟人类完全不一样。人会先在脑子里构思一个大致方案，然后落笔实现。模型做不到。它写第 50 行的时候，看到的只有前 49 行和你给它的提示，没有"全局规划"这个概念。

Chain-of-Thought（思维链）为什么有效？它给了模型更多的中间 token 来铺垫推理过程，跟"教会模型思考"没什么关系。多写几步中间推导，下一个 token 的预测就更准。拿输出空间换计算深度，仅此而已。

注意力的物理极限

Attention 机制决定了模型能"同时看到"多少信息。计算复杂度是 O(n²)，上下文长度翻倍，计算量翻四倍。上下文窗口有物理上限，这不是工程能解决的事，是数学决定的。

更关键的一点：标称窗口大小跟有效窗口大小是两回事。

实际工程含义：别想着把所有文档一股脑塞进去。200K 的窗口，你有效利用的大概只有开头和结尾的 40%。中间扔进去的代码、文档、历史对话，模型大概率"看见但没在意"。

Coding Agent 的五个先天缺陷

这些不是 bug，是架构层面的固有限制：

1. 局部最优：一步步续写不等于全局规划。模型容易写到一半发现路走偏了，然后打补丁而不是重新设计。
2. 偏差滚雪球：前面做了一个错误假设，后面整段代码在错误的世界观里自圆其说。越写越远，而且自己不知道错了。
3. 改不回去：模型倾向于重写而不是精确局部编辑。你让它改一行，它可能给你重写半个文件。
4. 看不到全貌：跨文件、跨模块的隐式约束，模型看不到。它改这里满足了局部需求，远处那个调用方就坏了。
5. 风格回归均值：训练数据见过的代码越多，输出越靠近"平均代码"。你项目里的特殊约定，它会缓慢但稳定地稀释掉。

这五个缺陷是后面所有章节的起点。Rules 体系是为了第 4、5 个缺陷服务的；Plan 模式是为了治第 1 个；rewind 是为了治第 2 个； Skills 是把第 5 个对抗到底。如果你不承认这五条，往下读的所有工程实践都会变成"为什么这么麻烦"的疑问。

二Agent Loop

Claude Code 不是一个"聊天框"，它是一个 Loop。理解这个循环，就理解了它能干什么、什么时候会卡、为什么有些 prompt 工程在它身上失效。

核心循环

把 Claude Code 简化到本质，每一轮工作都是这样一个循环：

读输入 → 推理 → 选工具调用 → 看结果 → 推理 → 选工具调用 → …… → 输出

它和聊天模型最大的差别，是中间会插入大量"工具结果"：读文件、执行命令、运行测试、grep 代码、写文件。 每一次工具调用都会把新内容塞进上下文。也就是说，对话越长，上下文不仅有你说的话，还有所有命令的输出。

上下文生命周期

一个 Claude Code 会话的上下文，会经历四个阶段：

1. 启动期：系统提示 + CLI 前缀 + CLAUDE.md + 工具 schema。这些是"前缀"，每次都一样。
2. 累积期：你的需求 + 它读的代码 + 工具结果 + 它的输出，一层一层加。
3. 污染期：失败的尝试、错误的工具结果、被你纠正过但留在历史里的方案，开始在上下文里发酵。模型会"看见"自己的错误尝试，并把它当事实。
4. 崩溃期：超过有效窗口后，模型开始遗忘开头、注意力涣散，工具调用质量肉眼可见地下降。

三KV 缓存与成本

为什么同一个 session 第二轮变便宜了？为什么改一行 CLAUDE.md 账单突然涨？答案是 KV 缓存。 省 token 的真相不是"少说话"，是保护缓存前缀。

前缀缓存机制

每一次请求都被切成六层，按顺序拼接：

[计费头] → [CLI 前缀] → [静态指令] → [动态内容] → [工具 schema] → [消息历史]

缓存按前缀匹配。如果前面所有层都没变，后面的部分可以直接复用上一次的计算结果——价格大约是重新计算的 1/10。

反过来说，任何前面层的变化，都会让后面的缓存链断掉。改 CLAUDE.md、换模型、加 MCP server、改 system prompt——任何一个都让你之后所有对话都按全价算。

Subagent 几乎不能复用主线程缓存，因为它的工具集、消息历史、有时候连模型都不同，本质上是另一条前缀。

会话决策表

每次大任务开始前，先选路径，不要凭感觉：

四上下文工程

上下文窗口是 Claude Code 真正的"内存"。和操作系统一样，内存满了不是给你买更多内存，是教你把东西换出去。 这一章讲怎么管理这块内存。

短对话策略

长对话不是越长越好。Context rot 会让模型注意力分散，长会话执行质量反而下降。一个简单原则： 能 5 轮内完成的任务，不要拖到 15 轮。具体做法是任务一开始就讲清目标、约束、产出格式， 不要"边干边想"地慢慢喂。

渐进式索引

大代码库不能整个塞进去。正确做法是渐进式索引：先让 Claude 读项目入口和目录结构， 再按需要读具体文件。这本质上是用"模型自己的判断"替代"你的盲塞"——它知道下一步该看什么。

对长文档同理：给路径不要直接贴。让 Claude 读、摘要、按需深入。塞了反而被 Lost in the Middle 吞掉，浪费 token 还得到更差的结果。

rewind / clear / compact

每一轮结束都是分支点。三个动作各有边界：

• rewind：调试失败时不要喊"不是这样"——叠加纠正会把错误方案留在上下文里。回退到错误分叉前，让 Claude 从那里重新走。
• clear：上下文真脏了就开新会话，把主线写成简短交接信塞给新会话。比硬撑省钱也省脑。
• compact：主动 compact 时明确告诉 Claude 要保留什么。自动 compact 经常发生在模型最疲劳的时候，效果最差。

五Rules 规则体系

Rules 是对抗模型"风格回归均值"和"看不到全貌"两大缺陷的主要工具。规则不是越多越好，是越分层越好。

三层规则

规则按层级分开放，不要混：

• 用户级 ~/.claude/CLAUDE.md：你个人的工作习惯。所有项目共享。不要放团队约定，会污染。
• 项目级 ./CLAUDE.md：团队共识。技术栈、命名约定、禁止动的目录、必须跑的命令。
• 子目录级 ./xxx/CLAUDE.md：专属约束。比如 migrations/ 下禁止删字段、infra/ 下任何改动都要 plan。

这种分层对应着模型注意力分布的实际方式——越靠近当前编辑文件的规则，越被认真执行。

Allow 与 Deny

settings.json 里 Allow 和 Deny 都能配权限，但Deny 永远比 Allow 重要。 Allow 写不完，Deny 救命。最少要挡住这几条：

rm -rf
sudo
git push --force
git reset --hard
curl ... | sh
.env / credentials / secrets 读写

个人 override 放 settings.local.json 并 gitignore，不要让你的偷懒污染团队 baseline。

Karpathy 四原则

团队 CLAUDE.md 顶部建议直接写这四条，比一千字废话有用：

1. Think Before Coding：先理解透彻再动手，避免错误假设。
2. Simplicity First：拒绝过度设计，最简单的方案往往最优。
3. Surgical Changes：只改被要求的部分，不触碰其他代码。
4. Goal-Driven Execution：测试先行，验证成功标准。

这四条直接针对模型五缺陷里的 1、3、4 三条。

六Skills 能力封装

Skill 不是一段 prompt，是一个文件夹。它把"做某件事的标准方法"沉淀下来，让 Claude 在合适的时机自动触发。 做对了，任务从 15 轮降到 2 轮。做错了，要么从不触发，要么乱触发。

设计方法论

一个 Skill 至少包含：

• SKILL.md：目标、输入、输出、步骤、3 条以上 gotcha。
• description 字段：决定触发时机——这是 Skill 真正的"命门"。
• 负面样例：写"什么时候不要用"，往往比写"什么时候用"更稳。
• （可选）配套的脚本、模板、数据、钩子。

不要从大而全 Skill 开始。先给一个重复任务写 20 行 SKILL.md，加 3 个 gotcha，再用真实请求测试触发。

触发边界

做完 Skill 后用一套标准测：

• 5 种相关说法：自然语言、同义词、缩写、相关场景。至少 4/5 命中。
• 3 个无关请求：明显与 Skill 无关。期望 0/3 命中。

这个 8/8 测试通过，Skill 才算可用。否则 description 要么太泛要么太窄，回去改。

生态地图

当前 Skill 生态主要三个来源：

• 官方 Skills：Anthropic 维护，质量最稳。
• Matt Pocock skills：偏 TDD / Domain Driven，工程师风格。
• SkillsMP：社区驱动，量大但良莠不齐。

推荐安装顺序：元能力（Skill-Creator / Grill-Me / Git-Guardrails）→ 规划类 → 代码安全类 → Superpowers → 按需补商业、文档、设计。 一个常见错误是装一堆 Skill 期待"自动变强"——不会的。装了不用等于没装。

四个相邻概念别混

七多 Agent 与 Harness

能力强弱不只看模型。Agent = Model + Harness，差距常常在 Harness。

Agent = Model + Harness

Claude Code 和 OpenClaw 都不自研模型，差距全在 Harness——权限、上下文、记忆、工具集、会话隔离、扩展机制。 评估任何 Agent 工具，不要先问"模型多强"，要问这六个维度：

1. 权限边界：能不能精细化？
2. 上下文管理：怎么 compact、怎么 rewind？
3. 记忆持久化：跨会话能记住什么？怎么验证记忆没腐败？
4. 工具集合：能扩展吗？支持 MCP 吗？
5. 会话隔离：能并行吗？worktree？
6. 扩展机制：Skill、Plugin、Hook、Routine 全不全？

架构上 Claude Code 是单用户深对话纵深架构，OpenClaw 是多用户横向并行架构。 没有谁强谁弱，只有谁适合你的场景。

Subagent / Team / Agent View

三个词经常被混用，但它们解决的是不同层级的问题：

• Subagent：单个 Claude 内部的并行——拆任务给小弟。
• Team：多个 Claude 协作——多个独立 agent 配合完成一件事。
• Agent View：给人用的 dashboard——你怎么管理你启动的所有 Claude。

Agent View 的核心价值不是让单个 Claude 更聪明，是让你这个"人类调度器"不崩溃。 会话从终端解绑、后台持久化、每个 agent 跑在独立 worktree 里、天然隔离改动。

Routines 与触发器

Routines 是云上 Claude 实例，本质是"带推理能力的后台 agent"，不是 n8n 那种节点编排。 它的优势是能理解、能适应，不是"接得多"。所以选场景要选那些写硬规则写不出来的事——PR review、故障诊断、文档漂移。

三类触发器各管一段：

• Schedule：晨报、周报、文档巡检。
• API：报警、部署后验证、外部事件。
• GitHub：PR、commit、issue 事件。

所有 Routine 默认以你的 GitHub 身份执行，分支锁在 claude/*，配额消耗订阅额度。设计时先问"什么时候被触发"，再写 prompt——顺序反了会反复返工。

八自动化工作流

自动化不是让 AI 代替人写代码，是把重复工程任务变成可审查流水线。人类的工作从写代码变成审代码和判方向。

PR 三段式

任何 Claude 参与的代码变更，都应该走三段：

1. 分类：Claude 只判断，不动手。可开发 / 不可开发 / 需要更多信息。不可开发就生成草稿回复，可开发才进下一步。
2. 执行：通过分类后才允许新建分支和改文件，改动控制在最小范围。Surgical Changes 是底线。
3. 审查：必须人类审查后才合并。一周内 PR 不允许自动 merge——这一条不要省。

从最低风险的 issue 分类自动化开始。先跑一个月只看分类质量，再考虑放开下一段权限。

商业 Pipeline

Claude Code 当编排层，API 和工具当能力层，你对业务场景的理解才是护城河。挑可重复、可计费、有异常处理空间的流程。 五类典型可卖 pipeline：

• 视频再利用（长视频 → 短片 + 文字稿）
• 线索富集（线索表 → 补全公司/角色/上下文）
• 竞品情报（URL 列表 → 定时快照 + diff + 周报）
• 发票/文档提取（图片/PDF → 结构化数据，5% 异常人工兜底）
• 知识库自动化（散乱文档 → 索引 + 摘要 + 检索）

它们的共同特征是不需要完整 App，只需要稳定流程。能卖钱的不是炫技，是"替别人省时间还能稳跑"。 5% 的异常人工队列要诚实写出来——这才是专业活。

飞书 CLI

飞书 CLI 把 Claude Code 接进真实办公系统：消息、妙记、任务、邮件、文档、表格、审批。 关键不是"能调多少 API"，是解决了哪个真实场景。推荐起步顺序：

1. 会议知识库：选一个固定会议系列，拉历史妙记，生成跨场次主题索引和新人入门文档。
2. 季度复盘：并行抓 8 路上下文，质量远高于手写凑字数。
3. 对账 / 报销 / 画板批注归档：日常重复操作，关键是以本人身份调用，留有审计。

九第二大脑

"把文件丢给 Claude 就有第二大脑"是幻想。第二大脑是索引 + 画像 + 摘要 + Hook + 学习循环——把长期知识变成每次 prompt 的背景。

输入即输出

所有"内容输出问题"的本质都是输入问题。你让 Claude 直接写文章，输出永远是套路八股，不是它的错——是你没经营输入。

先建好输入端：

• 四类素材：观察、反应、模式、数字。每条笔记标签不超过 3 个。
• 晨间节律：每天先写 20 分钟 Vault，再看社交媒体。被外部信息牵着走的人没有原创洞察。
• Claude 的角色：连接器 + 校对，不是写手。让它找跨域非显然连接，再把连接变成 brief。

每篇文章写五字段 brief：一句话洞察、证据、读者转变、钩子、结尾。然后再让 Claude 写正文，你做最后的"润和删"。

三层学习循环

第二大脑要能自我演化，需要三层循环：

• 每会话 /learn：每次重要会话结束总结 1–3 条经验，回写 me.md 或 context 摘要。
• 每日晨报：自动抓昨日动态，生成今日 brief。
• 每月复盘访谈：让 Claude 当面试官问你这个月做对了什么、哪里走偏。

配 UserPromptSubmit Hook，每次 prompt 前自动检索知识库注入相关上下文。 先建 me.md，再做 5 个 context 摘要文件，最后才接自动检索。不要一开始就追求全库智能。

Project / Skill / MCP

Claude Projects、Skills、MCP 不是一个东西，三层职责必须分清：

Project 的自定义指令保持 200–500 字，分四块写：Profile（你是谁）、Voice（语气）、Rules（边界）、Formatting（输出格式）。

十账号与生态

长期重度用 Claude Code，账号是基础设施。这一章讲怎么把基础设施稳住——防风控、分流、生态分层。

防风控

风控不是玄学，是概率判断：你的账号看起来像不像正常人类。

• 新账号第一周只用 Desktop 和网页，不要直接 CLI 高强度自动化。
• 订阅走 App Store / Google Play 渠道，Pro 起步用一两个月再考虑 Max。
• IP 和设备稳定，不要每天换 VPN 节点。公共代理、共享账号、24 小时跑满都会拉高异常分。
• 保持作息节律——凌晨 4 点的 CLI 高负载比白天可疑得多。
• 记录账号档案：邮箱、订阅渠道、注册时间、常用 IP、备用账号。出问题能复盘。

有备用账号、有国产模型分流方案，才算"基础设施"。否则一被封整个工作流停摆。

国产模型分流

Claude 继续做主力编程和复杂推理。大文档、长程后台、批量内容、自动网页操作可以分给国产模型—— 这些场景对推理强度没那么敏感，但对 token 单价和上下文长度敏感。

切换成本被严重低估：插件、提示词、习惯都围绕主力工具沉淀。所以分流要做"场景隔离"，不要换主力。

四产品分层

Claude 不是单一产品，是四层能力矩阵：

• Chat：思考伙伴，构思 / 复盘。
• Code：开发者工作马，改代码、跑命令、读项目。
• Cowork：非开发者操作软件，浏览器 / 文档 / 表格 / PPT。
• Managed Agents：基础设施层，长期运行、跨用户、定时触发。

选择逻辑：先 Chat 想清楚 → 要操作就转 Cowork 或 Code → 要规模化再上 Managed Agents。 四者不竞争，是同一平台在不同行动深度上的分层。一个入口解决所有事只会让所有事都做不好。

第三方 API（Anthropic-compatible）能省钱，但要任务分级：

• 公开级（公开文档总结、个人代码片段）：可以走第三方。
• 内部级（团队代码、内部资料）：默认不走，看具体协议。
• 敏感级（客户数据、私密文档）：永远走官方。

附30 篇 wiki 原文索引

本书的论证来自下面 30 篇 wiki 笔记。按主题归类，作为 reference。原文比白皮书更细，需要查具体例子或反例时来这里。

原理篇相关

工程篇相关

应用篇相关