波仔
🐎 第1章 登高望远：Claude Code 技术架构全景
📄 一句话概括

选型的顺序经常被搞反：先比功能，再看谁写得少，最后才发现想用的那个根本做不到。 正确的顺序是反过来：先拿硬约束筛掉做不到的，再在剩下的里面比谁的维护负担小。 这一节用四个真实需求走一遍，最后收本章。

📝 本章和前面几章的关系

前三节讲了有什么、怎么协作，这一节讲怎么选。 选型这件事没有标准答案，但有标准的错误顺序。 这一节给的是一个能复用的判断流程，不是一张「什么需求用什么」的死表。

一、最常见的错：从功能出发

「这个组件功能最多，就用它」——这类决定的后悔率最高，因为功能多的那个通常也最重。 演示第 ③ 步里，四个需求如果都上 SDK，全都能做。 但其中三个会被做成「为了拧一颗螺丝搬来一台机床」：要部署、要重启、改一次改代码。 反过来也一样。「这个最简单，就用它」同样会翻车：Hook 最简单，但它不会读语义，拿它写周报写不出来。

所以问题不在「哪个好」，在顺序。

二、第一步：硬约束筛

硬约束是「做不到就是做不到」的那类条件，跟成本无关。常见的有四种。 第一种是【必须每次执行】。凡是漏一次就出事的，只能靠钩子或者自己的代码，因为模型可能想不起来。 第二种是【需要理解语义】。要读懂这周干了什么、要判断这段代码有没有问题，只有模型能做，脚本做不了。

第三种是【要连外部系统】。数据库、工单系统、云平台，这些必须走 MCP 或者自己写连接。 第四种是【无人值守】。没有人坐在旁边点确认，就得用命令行模式或者 SDK。 四个问题问完，候选通常只剩一两个。这一步花五分钟，能省掉后面五天的返工。

三、第二步：成本比

剩下的候选功能上都行，那就比维护负担。负担有三块，按重要性排： 第一块是【改一次要动哪里】。改配置、改一份 markdown、改代码，是三档完全不同的成本。 业务规则变得越快，这一项权重越高。 第二块是【多几个进程】。 每多一个常驻进程，就多一个会挂的东西、多一处要监控的地方、多一份要升级的依赖。

第三块是【谁能改】。一份 markdown 谁都能改，一段代码得找开发。要让业务同事自己维护的，别做成代码。 演示第 ③ 步那张表就是按这三块排的。 同一件事，Hook 是「改规则改配置」，SDK 是「要部署要重启」——负担差着一档。

四、第三步：留一条升级路

选型不是一锤定音。今天的「一条 shell 循环」明天可能要拿结构化结果，那就升级到 SDK。 所以选的时候要顺手看一眼：这条路往上走顺不顺？ 从 Hook 往上走是加一个 prompt 类型的钩子（让模型参与判断），路是通的。 从 Skill 往上走是把内容拆成多份、加子智能体，也通。

从 shell 循环往上走是换 SDK，要重写，但业务逻辑本身不多，重写成本可以接受。 真正难升级的是「一开始就用最重的那个」：SDK 写了半年，想退回配置化的方式，等于把沉淀的逻辑全扔了。 从轻往重走容易，从重往轻走要命。

五、本章小结

第一章立的是骨架，四节各管一件事。 1.1 讲循环：Agent 不是更强的模型，是模型外面那圈「工具加状态加终止条件」。 循环有成本，成本随步数加速上升。 1.2 讲分层：记忆、扩展、集成、编程，四层各管一段。 判断一个需求该配哪层，问「我要改的是它知道什么、能做什么、连到哪、还是谁来发起」。

1.3 讲协作：六个组件的真正差别是触发权。触发权决定确定性，确定性决定能不能拦。 「漏一次会出事」的事挂钩子，其余写进指令。 1.4 讲选型：先硬约束筛，再成本比，最后看一眼升级路。顺序反了，后面全是返工。 四节连起来是一句话：这套东西的复杂度不在单个组件，在它们的组合方式。所以先看清骨架， 再往里填肉——后面九章就是填肉。

六、动手 Demo：四个需求，四份配置，走一遍筛和排

四个需求：保存后自动格式化、按模板写周报、查生产库只读数据、每晚批量审查 PR。 每个都真写一份最小可用的配置或者脚本，行数是数出来的。 然后走两步：硬约束筛、成本比，最后落到四句话。

# 第一步：四个问题筛掉做不到的
HARD = [
    (u"保存后自动格式化", u"每次都必须执行", u"Skill、子智能体"),
    (u"按模板写周报", u"要读懂这周干了什么", u"Hook"),
    (u"查生产库只读数据", u"要连一个外部系统", u"Hook、Skill"),
    (u"每晚批量审查 PR", u"无人值守，要循环两百次", u"Hook、Skill"),
]
# 第二步：剩下的比维护负担，不比功能

实跑输出：

--------------------------------------------------------------------
选型不是比功能，是先被约束筛、再被成本排
--------------------------------------------------------------------


  ① 四个需求，四份最小可行的东西
  --------------------------------------------------------------------
  下面这四段都是真写出来的最小版本，行数是数出来的，不是估的。
| 需求 | 载体 | 行数 | 字符 | 额外要维护 |
|---|---|---:|---:|---|
| 保存后自动格式化 | hooks.json | 9 | 180 | 无额外进程 |
| 按模板写周报 | SKILL.md | 11 | 191 | 无额外进程 |
| 查生产库只读数据 | .mcp.json | 8 | 129 | 多一个服务器进程 |
| 每晚批量审查 PR | review.sh | 4 | 157 | 多一个定时任务 |


  ② 先过硬约束：能不能做，不看省不省
  --------------------------------------------------------------------
| 需求 | 硬约束 | 直接出局 | 还活着 |
|---|---|---|---|
| 保存后自动格式化 | 每次都必须执行，不能靠模型想起来 | Skill、子智能体 | Hook、SDK |
| 按模板写周报 | 要读懂这周干了什么 | Hook | Skill、子智能体、SDK |
| 查生产库只读数据 | 要连一个外部系统 | Hook、Skill | MCP、SDK |
| 每晚批量审查 PR | 无人值守，要循环两百次 | Hook、Skill | SDK、Headless CLI |

  这一步经常被跳过。跳过的人会拿 Hook 去写周报，写完发现它不会读文件；
  或者拿 Skill 去连数据库，写完发现它没有连接能力。

  ③ 再比成本：剩下的几个谁更省事
  --------------------------------------------------------------------
| 需求 | 候选 | 落地形态 | 维护负担 |
|---|---|---|---|
| 保存后自动格式化 | Hook | 一段 json 配置 | 轻，改规则改配置 |
| 保存后自动格式化 | SDK | 一个常驻程序 | 重，要部署要重启 |
| 按模板写周报 | Skill | 一份 markdown | 轻，改模板改 md |
| 按模板写周报 | SDK | 一个常驻程序 | 重，改模板要改代码 |
| 查生产库只读数据 | MCP | 装现成的服务器 | 中，连接串与账号要管 |
| 查生产库只读数据 | SDK | 自己写驱动 | 重，重试限流全自己写 |
| 每晚批量审查 PR | Headless CLI | 一段 shell | 轻，一条命令加循环 |
| 每晚批量审查 PR | SDK | 一个服务 | 中，要结构化结果时才值 |


  ④ 落到四句话
  --------------------------------------------------------------------
| 需求 | 该用什么 | 一句话理由 |
|---|---|---|
| 保存后自动格式化 | Hook | 确定性靠配置，不靠模型 |
| 按模板写周报 | Skill | 要理解内容，又要团队复用 |
| 查生产库只读数据 | MCP | 外部系统只接一次，谁都能用 |
| 每晚批量审查 PR | Headless CLI | 无人值守，先别上 SDK |

  ! 注意第四行：能写脚本解决的事，先写脚本。SDK 是给「要拿结构化结果、要嵌进服务」准备的；
  只用一次的任务上 SDK，等于为了拧一颗螺丝搬来一台机床。

①四份东西都是最小可用版本，行数是真的：钩子配置 9 行、技能 11 行、MCP 配置 8 行、shell 循环 4 行。 注意它们都很短。最小可用从来不长，长的是后面加的那些补丁。 ②硬约束这一步把候选砍掉一半。四个需求里，每一个都至少砍掉两个候选。 这一步最容易被跳过，因为跳过的当下感觉更快。代价在后面：拿 Hook 写周报，写到一半发现它不会读文件。 ③成本比这张表没有数字，全是定性：改配置、改 md、改代码，是三档。 没给数字是故意的。 成本不是行数，是「改一次要动哪里、谁来动」。一个四百行的配置如果只是改一个字段， 比五十行代码好维护得多。 ④最后四句话就是答案。前三行跟直觉一致，第四行值得多说一句。 每晚审两百个 PR，很多人第一反应是写个 SDK 服务。 但一条 shell 循环就够了：它不需要保持状态、不需要跟别的系统对话、结果写到 stdout 就完事。 什么时候该升级到 SDK？ 当你需要结构化结果、需要嵌进已有的 Web 服务、或者需要在中间插入自己的业务判断。 这三件事 shell 做不了。

30 秒实验

  1. 给「每晚批量审查 PR」加一个新约束：结果要写进数据库并按周出报表。它还能用 shell 吗？ 该换成什么？
  2. 把「按模板写周报」的模板从一份改成五份（分别给不同部门），技能方案和 SDK 方案各要怎么改？ 改造成本差多少？
  3. 自己写一个需求：「每次提交前检查有没有把密钥写进代码」。走一遍两步法，看最后该用什么。

常见误区

  1. 先比功能再比成本。功能多的那个通常最重，结果是能用但难维护，半年后没人敢动。
  2. 跳过硬约束，直接比成本。便宜但做不到，等于白选。
  3. 用规模判断。任务「多」不等于「复杂」：两百个 PR 每个都很简单，一条循环就够，不需要上 SDK。
  4. 以为选定了就不能改。选型是分阶段的，从轻往重走是正常的演进；反过来才难。所以起步宁可轻一点。
  5. 把「我要写代码」当成能力证明。 能用配置解决的用配置，配置是给人看的，代码是给机器看的——这份东西将来要谁维护， 就写成谁看得懂的形态。
自测三问（点开对答案） 1. 硬约束和成本，为什么必须先过约束？ —— 因为约束是「能不能」，成本是「值不值」。 做不到的方案再便宜也没用，先筛掉能省掉大量无意义的对比。 2. 「改一次要动哪里」为什么比「代码多少行」更能反映维护成本？ —— 行数是静态的，改动的频率和位置才是动态的。 一个四百行的配置如果只改一个字段，比五十行代码好维护得多。成本要看变动时的代价，不是看存量。 3. 为什么说从轻往重走容易，从重往轻走要命？ —— 轻方案升级是加东西，已有的配置和规则可以保留； 重方案降级等于把沉淀的逻辑丢掉，而逻辑往往比代码值钱。

骨架讲完了，下一章从最底层那层开始：模型没有记忆，那 CLAUDE.md 到底在替它记什么。

相关笔记