第15章：设计精华 —— 四种 harness 哲学对照

第15章：设计精华 —— 四种 harness 哲学对照

收尾章。四种哲学的完整对照、Claude Code 独有的六个观察、前十四章 29 条可迁移判断的汇总、哪些不该抄，以及对本仓的具体启示。

一、四个问题，四个答案

同一道题："给模型套一个外壳，让它能在真实代码库里干活"。四种答案。

1.1 四个"不做"的对照

看一个系统不做什么，比看它做什么更能看清它的立场。

最有意思的是"让扩展改内核"这一格：dsh 允许，Claude Code 明确不允许。

Claude Code 花最大力气优化的东西——缓存边界、五层压缩、附件预算、fork 前缀——恰恰是它不让扩展碰的。这不是保守，是产品承诺：如果扩展能改这些，"上下文永不受限"和"fork 很便宜"这两个承诺就守不住了。

二、Claude Code 独有的六个观察

2.1 缓存经济学是一条贯穿全系统的主线

前十四章数下来，为保护 prompt cache 前缀而做的设计至少有 12 处：

数据层的哨兵常量、DANGEROUS_ 前缀 + 不被读取的理由参数、agent 列表搬进附件、fork 的固定占位符、附件头部预计算、1h TTL 资格闩锁、只打一个消息级 cache_control、系统提示词 section 注册表的默认 memoize、时间触发的 microcompact、缓存编辑式 microcompact、fork 透传父进程渲染好的提示词字节、压缩走 forked agent 复用缓存。

它们散布在 12 个互不相干的子系统里，但是同一句话的 12 个变体。

而且有一整套配套设施：约定（哨兵）+ 类型（DANGEROUS_ 命名与强制理由）+ 观测（727 行的断裂检测，逐维度 hash + 逐工具 hash + 可读 diff）。

只做其中一样的团队很多，三样都做的极少。

2.2 决策依据是机队级的成本数字

这份源码里的注释反复出现同一种论证形式：

• agent 列表内嵌工具描述 → 占机队 10.2% 的 cache_creation token
• 只读 agent 砍掉 CLAUDE.md → 每周省 50–150 亿 token
• 只读 agent 砍掉 gitStatus → 每周省 10–30 亿 token
• 一次性 agent 省掉 SendMessage 尾巴 → 135 字符 × 每周 3400 万次
• 数字长度锚点 vs "be concise" → 多省 1.2% 输出 token
• 压缩不走 forked agent → 98% 缓存未命中
• autocompact 断路器 → 全球每天浪费 25 万次 API 调用
• 77% 的工具侧缓存断裂来自"描述变了但工具没增没减"

这些不是估算，是 BigQuery 查出来的。 注释里甚至带日期（BQ 2026-03-10、BQ 2026-03-22）。

一个系统能不能做这类优化，取决于它有没有机队级的可观测性。 第 9 章数过：工具执行链上每一道关都打点，而且带 queryChainId / queryDepth。没有那些埋点，上面每一条都无从谈起。

2.3 提示词是被当作有版本、有实验、有失败率的工程产物在管理

第 5 章那些 @[MODEL LAUNCH] 标记：

// @[MODEL LAUNCH]: capy v8 assertiveness counterweight (PR #24302) — un-gate once validated on external via A/B
// @[MODEL LAUNCH]: False-claims mitigation for Capybara v8 (29-30% FC rate vs v4's 16.7%)
// @[MODEL LAUNCH]: Update comment writing for Capybara — remove or soften once the model stops over-commenting by default

"虚假声明率 v8 是 29–30%，v4 是 16.7%" —— 这是一个被测量的模型行为指标，提示词是针对这个回归写的缓解措施，而且标了"等模型改好就删"。

第 6 章那个 smoosh 甚至为"消息数组的形状"做了 A/B（sai-20260310-161901, Arm B）。第 7 章那段"不许调工具"的压缩前言给了失败率数据（0.01% → 2.79%）。

提示词在这里不是文案，是有基线、有实验、有回滚计划的代码。

2.4 "让危险操作难写"出现了四个变体

第二个最聪明：它把"解释清楚"从代码评审的社会规范变成了编译器要求。

第三个最实用：每一次赋值都要显式写出那个又长又刺眼的名字，作者不可能不注意到自己在声明什么。

2.5 用 prompt 构造问责结构

第 13 章那个验证 agent 是本教程见到的最完整的例子：

验证 agent 侧                          主 agent 侧
─────────────────────────────         ─────────────────────────────
命名自己的两种失败模式                  触发条件量化（3+ 文件 / 后端 / 基建）
逐字列出六句托词并反驳                  不许自己给自己判决
每个 PASS 必须带 Command run 块         不许告诉验证者测试结果（防锚定）
PARTIAL 只给环境限制                    PASS 之后要重跑 2–3 条命令核对
                          ↑                              ↓
            "调用方可能会重跑你的命令来抽查"  ←──────  抽查机制

两边的提示词互相引用、互相约束，形成闭环。

关键在最后一环：自律 + 他律。前四条是自律（模型要求自己诚实），最后一条是他律（调用方会抽查，而且被检查者知道）。只有自律的验证会随着任务变难而退化。

2.6 "机制 + 告知"成对出现

这个模式在书里出现了至少七次：

规律是：机制能挡住的用机制，机制挡不住的（模型的理解、模型的选择）用提示词。而且两边措辞要对得上。

三、29 条可迁移的判断

前十四章标了 29 条。按主题重排，标 ★ 的是本教程认为优先级最高的 10 条。

上下文与缓存

循环与状态

工具与执行

安全与治理

提示词与多 agent

四、一个反复出现的模式：预算 + 降级 + 打点

Codex 教程第 15 章总结出的模式是"自由的策略 + 硬性的上限"。Claude Code 的对应物是一个三段式：

显式预算（百分比，不是绝对值）
      ↓  超了
明确的降级顺序（谁先被牺牲）
      ↓
每次降级都打点

出现的地方：

第三段（打点）最容易被省掉，也最重要。 没有它你永远不知道有多少用户的技能列表其实是残缺的、有多少会话在静默地丢工具结果。

五、哪些不该抄

5.1 不要抄缓存优化的强度

第 4 章那段"只打一个 cache_control 标记"的注释引用了推理服务的 KV page 淘汰算法。这种优化只有在你同时控制客户端和服务端、而且机队规模足够大时才有意义。

对绝大多数项目：做到"静态/动态分离"和"不要把会变的东西放进前缀"就够了，不需要去研究服务端的显存管理。

同理，第 6 章那个"预先计算'3 天前保存'这个字符串"——如果你的会话量不到百万级，这个优化的收益是零。

5.2 不要抄 29 条判断里那些依赖规模的

上面那张表里，⑧⑨⑬ 三条都隐含"你有机队级数据"这个前提。没有数据就照抄，会变成用直觉伪装成的工程决策——比抄之前更糟，因为它看起来有理有据。

判断方法：如果你抄的那条判断，在源码里的理由是一个数字（10.2%、77%、3400 万次/周），而你拿不出对应的数字，那就先别抄。

5.3 不要抄五层压缩

第 7 章那五层里，四层是 feature-gated 的实验。它们并存说明的不是"五层都必要"，而是"他们还在试哪几层组合最好"。

对一般项目：一层摘要 + 一个"清老工具结果"的机制，加起来能覆盖绝大部分场景。 五层的复杂度需要五层的运维能力（断路器、递归守卫、跨层短路逻辑），而那些复杂度本身就是 bug 来源——第 7 章那三条事故注释都出在层间交互上。

5.4 不要在没有可观测性的项目里抄它的复杂度

第 9 章数过：工具执行链上十几个打点，每个带 queryChainId / queryDepth。

Claude Code 敢做这么复杂的系统，是因为它每一层都能被单独观测。 一个没有埋点的项目照抄这个复杂度，等于给自己造了一个无法调试的黑箱。

顺序应该反过来：先有可观测性，再有复杂度。

5.5 不要抄"扩展不能改内核"——除非你也有对应的承诺

Claude Code 不让扩展碰缓存边界和压缩策略，是因为它对用户有"上下文不受限"和"fork 很便宜"的承诺。如果你没有这类承诺，那把内核锁死只是在给用户添堵。

dsh 的选择在很多场景下更合适。

六、对本仓的具体启示

本仓（VariFlightWork）是一个 Obsidian 知识库 + 35 个以上自定义技能 + 大量 CLAUDE.md 规则的重度 Claude Code 使用场景。前十四章有六条能直接落地。

6.1 立刻能做：查一遍自己的钩子在倒多少垃圾

[实测] 本机 48 个会话里 hook_non_blocking_error 附件 2249 条，占全部附件的 64%——来自四个把解释器写死成 powershell.exe 的 PowerShell 钩子（本机其实装了 pwsh，只是名字不叫 powershell.exe）。已于 2026-08-25 修复：命令改成运行时解析，找不到解释器就静默 no-op。

这条之前没被记录过。 本仓 CLAUDE.md 里那条 "Rule (Linux/macOS)" 处理的是功能缺失（目录级 CLAUDE.md 不会被注入），但没提到上下文开销这一面，而实测显示后者是更大的代价。

建议：把 inject-dir-claude-md.ps1 的注册从入库的 settings.json 挪到 Windows 侧的 settings.local.json，或者把它改写成跨平台脚本（Python，本仓有 .venv）。

自查脚本在第 6 章和第 11 章末尾。

6.2 技能的 frontmatter 还有大量没用上的字段

本仓的技能大多只用了 name / description / allowed-tools / disable-model-invocation。第 14 章那 17 个字段里，至少四个对本仓有直接价值：

context: 'fork' 那条收益最直接：第 12 章讲过 fork 共享缓存、输出不进主上下文。本仓几个"跑一遍产出一堆中间数据"的技能正是它的目标场景。

6.3 技能清单已经在挤压 1% 的预算了

[实测] 本会话的技能列表里有 40+ 个条目（本仓 35+ 个 + bundled 若干）。第 6 章那个预算是上下文窗口的 1%（默认 8000 字符），超了之后：

① 全量描述能塞下 → 全量
② 塞不下 → bundled 保全量，其余按剩余预算平分并截断
③ 平分后每条不足 20 字符 → 非 bundled 只留名字

本仓的技能描述普遍很长（prd-to-tapd 的 description 有 500 多字，od-lowprice-batch 也有 400 多字），而单条硬上限是 MAX_LISTING_DESC_CHARS = 250。

这意味着本仓多数技能的描述在清单里已经被截断了。 而 skill-creator 那套"description 决定触发准确率"的方法论，前提是描述完整地出现在模型面前。

建议：把每个技能 description 的前 250 字符当成真正的触发文案来写——最关键的触发词放最前面，详细说明放后面（反正会被截）。

6.4 CLAUDE.md 的 progressive disclosure 已经在做对的事

本仓 CLAUDE.md 用的模式是：

**Trigger:** When X, **read** `.claude/references/foo.md` for detail.

这和第 14 章那个"技能 token 只算 frontmatter，正文按需加载"是同一个模式，也和第 6 章那个"技能清单只放描述"一致。

继续保持。 而且可以更进一步：CLAUDE.md 本身是每轮都在上下文里的（userContext.claudeMd），它的每一行都在花常驻预算。第 12 章那个"只读 agent 砍掉 CLAUDE.md 每周省 50–150 亿 token"说明这个成本是真实的。

6.5 fork 的"不要偷看"和"不要抢跑"是本机远程协作的直接对照

第 12 章那两条规则，在本仓的 130 远程协作流程里有直接对应：

• 不要偷看 ↔ 本机 Claude 不应该在 PR 提交后自己去 gh pr view --comments 拉评论（CLAUDE.md 里已有这条："不要主动去 gh pr view --comments 拉评论"）
• 不要抢跑 ↔ 本机 Claude 不应该预测 Windows Claude 的审核结果

已有的规则和 Claude Code 内部的 fork 协议是同构的。 这不是巧合——它们解决的是同一个问题：异步委派中，委派方对结果的无知必须被显式承认。

6.6 验证 agent 那套方法论可以搬进本仓的审核流程

本仓有 remote-branch-review 技能（审核远程 Claude 提交的分支）。第 13 章那五条可以直接加进去：

1. 命名失败模式——"审核回避：读 diff、说'看起来没问题'、通过"
2. 逐字反驳托词——"这个改动很小"、"提交者说测过了"、"格式问题不影响"
3. 规定证据格式——每个通过项要带"我实际做了什么检查"
4. 堵死逃生口——"有条件通过"只给环境限制用
5. 抽查机制——用户会随机重看一两条

第 5 条在本仓天然成立：用户本来就在看。把它写进技能里，让审核方知道自己会被抽查。

七、这套教程没讲的

诚实地列一下边界。

因为 DCE 看不到的（第 2 章 §2.4）：reactive compact、snip、context-collapse、cached microcompact 的实现；proactive/Kairos 那整条自主运行产品线；coordinator 模式；workflow 脚本；REPL 模式；DiscoverSkills；auto 模式分类器的提示词模板。

因为篇幅没展开的：TUI 层（components/ + ink/，485 个文件）；sessionStorage.ts 的 5105 行（恢复、分叉、远程会话水合）；LSP 集成；MCP 的 2465 行认证；遥测与 Perfetto 追踪；SessionMemory 子系统；teammate / 团队机制的完整形态。

因为没有 git 历史做不了的：时间线考古。Codex 教程能说"Guardian 2026-03-15 进的仓库"，本教程说不了任何"什么时候加的"。

因为只有一个横截面做不了的：演进方向。快照停在 Opus 4.6 时代，本机跑的 2.1.241 已经不一样了（第 6 章那个 total_tokens_reminder、第 13 章那个 Explore 描述都对不上）。

八、结语

读完四份 harness 教程，最大的收获不是任何一处具体设计，而是一个判断框架：

一个 harness 的架构，是它的约束条件的函数。

• Pi 是一个库，用户是开发者 → 可以说"这个我不做，你自己扩展"
• dsh 要支持多部署形态与厂商替换 → 一切做成接缝
• Codex 要装进静态二进制跑在几百万台开发机上 → 必须自己解决每个操作系统的沙箱
• Claude Code 的 token 直接计费给自己，机队大到"省 10% 缓存创建 token 就值得专门重构" → 缓存经济学成了第一性问题

所以"该抄哪个"这个问题本身问错了。 该问的是：我的约束是什么？

如果你的 agent 一天跑十次，缓存优化毫无意义，Pi 的减法更合适。 如果你要给不同客户换不同的模型后端和存储，dsh 的接缝架构是对的。 如果你要跑在不可信的代码库上，Codex 的隔离优先是对的。 如果你的 agent 会话很长、上下文是主要成本、而且你能测量它——那 Claude Code 这 12 处缓存设计值得逐个抄。

最后引一句本教程读到的、最能概括这个系统的注释。它在讲那个只允许一个 cache_control 标记的地方：

With two markers the second-to-last position is protected and its locals survive an extra turn even though nothing will ever resume from there.

"哪怕不会有任何东西从那里恢复" —— 为了几个不会被用到的 KV page，写了 12 行注释和一处非直觉的实现。

这就是这个系统的性格。

九、动手复核

cd claude-code-deep-dive/extracted-source

# 1. 把全书引用的机队级数字一次性捞出来
grep -rn 'fleet\|Gtok/week\|per week\|/day globally\|BQ 2026' src/ | grep -v node_modules

# 2. 「让危险操作难写」的四个变体
grep -rn 'DANGEROUS_' src/ | head
grep -rn 'I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS' src/ | wc -l
grep -n 'SYSTEM_PROMPT_DYNAMIC_BOUNDARY' src/constants/prompts.ts src/utils/api.ts

# 3. 所有 @[MODEL LAUNCH] —— 针对具体模型版本的提示词补丁
grep -rn '@\[MODEL LAUNCH\]' src/

# 4. 所有 A/B 实验编号与 GrowthBook flag
grep -rno "tengu_[a-z_0-9]*" src/ | sed 's/.*://' | sort -u | wc -l

# 5. 「预算 + 降级 + 打点」三段式的六处
grep -rn 'BUDGET_CONTEXT_PERCENT\|AUTO_TOOL_SEARCH_PERCENTAGE\|MAX_MEMORY_BYTES\|maxResultSizeChars\|AUTOCOMPACT_BUFFER' src/ | head

本机侧：

# 本章 §6.1 的自查（换成你自己的项目目录）
D=~/.claude/projects/$(pwd | sed 's#/#-#g')
python3 -c "
import json, collections, glob, sys
c = collections.Counter()
for f in glob.glob(sys.argv[1] + '/*.jsonl'):
    for line in open(f):
        try: d = json.loads(line)
        except: continue
        if d.get('type') == 'attachment': c[(d.get('attachment') or {}).get('type')] += 1
tot = sum(c.values())
for k, v in c.most_common(): print(f'{v:6d}  {v*100//max(tot,1):3d}%  {k}')
" "$D"

十、总结

1. 四种哲学是四组约束的解：减法（库）、全插件化（多部署）、工程完备（静态二进制 + 不可信代码库）、上下文经济学（长会话 + 自己付 token + 有机队数据）
2. Claude Code 为保护缓存前缀做了至少 12 处设计，散布在 12 个子系统里；配套三层设施：约定（哨兵）+ 类型（DANGEROUS_ 与强制理由）+ 观测（727 行断裂检测）
3. 决策依据是 BigQuery 查出来的机队级数字，注释里带日期；没有可观测性就没有这类优化
4. 提示词被当作有基线、有 A/B、有失败率、有回滚计划的工程产物管理
5. "让危险操作难写"有四个变体，其中"强制传一个代码里不读的理由参数"把解释义务从社会规范变成了编译器要求
6. 验证 agent 那套是"用 prompt 构造问责结构"的完整范例，关键在自律 + 他律的闭环
7. "机制 + 告知"成对出现七次：机制能挡的用机制，挡不住的用提示词，两边措辞要对得上
8. 29 条可迁移判断，10 条标星；"预算 + 降级 + 打点"三段式出现在六处资源上，第三段最容易被省掉也最重要
9. 不该抄的五类：缓存优化的强度、依赖机队数据的判断、五层压缩、没有可观测性时的复杂度、"扩展不能改内核"（除非你也有对应承诺）
10. 对本仓六条启示，其中最立刻能做的是查一遍钩子——[实测] 2249 条 hook_non_blocking_error 占全部附件的 64%，一笔之前没被记录过的持续开销，已于 2026-08-25 修复
11. "该抄哪个"问错了，该问"我的约束是什么"

Related Documents

• README-教程总览
• 第14章-扩展面-Skills-Plugins-MCP-Commands
• 第1章-开篇-Claude-Code-Harness总览 —— 那五个缓存经济学例子的出处
• Claude Code Harness 研究摘要 —— 不读 15 章的话读这一篇
• Pi 教程第 13 章
• dsh 教程第 13 章
• Codex 教程第 15 章
• Harness Engineering 研究报告