模型是支点，
harness 才是杠杆
Claude Code 把 agent 主循环替你写好了，循环之外那一圈得你自己搭。同一个 Claude，这一圈搭得好不好，决定它是只能改几行的工具，还是能扛 70 万行遗留系统的开发者。
同一个模型，
环境决定它的上限
把 Claude 当一名新入职开发者认真接入，原本搁置的工作会重新推进；而模型本身的能力又确实是天花板。两面合起来：harness 是可调的杠杆，模型是固定的支点。支点换不了，能动手的只有杠杆。
一条贯穿全文的纪律：harness 会随时间失效。模型一升级，此前搭的脚手架可能反成负担。所以下文每介绍一层，都要同时想它的退役时机，这点留到结语。
这篇只讲「配 Claude Code」
Claude Code 提供的是 Anthropic 已实现好的主循环，无需自己编写 agent 主循环。本文只讨论一件事：这个现成框架该怎么配。三类东西不要混：①模型给的（改不了，第〇层）、②你配的（本文主体）、③你从零建的（不在本文范围）。
底座选型、上下文管理、知识与工具的搭建顺序、用 subagent 与 Workflow 编排、把验证独立出来。全是在 Claude Code 里只配不建的东西。
另有 ①模型能力：给定项，改不了只能绕，是 harness 的地基（第〇层）。
prompt caching 设计规则、MCP server 实现、面向 agent 的命令行、单 loop 与多 agent 架构取舍、把产物改造成可验证接口。这些是用 API/SDK 从零搭 agent 才会碰到的。
遇到此类内容本文只点到为止、标明「不在本文范围」，不展开。
五层，自下而上盖
第〇层：你绕不开的地基
这层不是搭出来的，是给定的。但要先认清它，因为它决定了 harness 能精简到什么程度。
窗口是 100 万 token（系统提示词 + 完整对话 + 所有工具输出 + 已读文件），但窗口大不等于可以随意填。
实用 tip：给状态栏装个 context 进度条。不用反复敲 /context 打断手感，剩多少窗口一眼可见：
/compact 或开 subagent，不用再敲 /context 打断手感。当前最强编码模型是 Opus 4.8，但比版本号更重要的是几条不随升级过期的原则。
high，编码请手动调到 xhigh。Opus 4.8 在所有界面（含 Claude Code）都默认 high，这是质量与体验的平衡点。但官方明确推荐：编码、agentic、长时异步任务设到 xhigh（high 与 max 之间）。max 留给极难问题，易过度推理、token 失控，收益递减。（4.7 时 Claude Code 默认就是 xhigh，4.8 改回 high，这本身就是下面 C 点的例子。）| 这一代变了什么 | 具体 | 你要做的 |
|---|---|---|
| 默认 effort 变了 | 4.7 时 Claude Code 默认 xhigh，4.8 改回 high | 编码手动设回 xhigh |
| 长上下文检索回退（4.7 那代） | 多针检索 MRCR：256k 91.9%→59.2%、1M 78.3%→32.2%；连带重度联网研究 BrowseComp 约 −4.4pp | RAG / 长文 / 纯联网调研，升级前按场景 A/B，别只看版本号 |
| 默认语言偏好变了 | 4.8 默认中文输出偏弱、更倾向英文 | 中文团队在 CLAUDE.md 里显式要求「用中文回答」 |
4.8 这一代幻觉显著下降，直接改变你要在验证上花多少力气。同一套 fact-check 流程核 11 篇报告（独立 subagent 在干净上下文逐条比对原文、有问题就改、换新 subagent 复核到零问题），切到 Opus 4.8 那天是一道清晰的分水岭：
但别误读成「4.8 之后不用验证了」。变薄的是返工次数，不是验证本身。生成不等于评估、由独立 agent 验收而非执行者自评，这套分工制衡删不掉（详见第四层）。
prompt caching 是一层「不可见但花钱」的机制：前缀逐字节匹配，任何位置变一字节、其后缓存全失效。cache miss 让每轮全价重算、成本翻倍，进而把订阅计划的 rate limit 砍半，命中率直接决定 Pro/Max 给你多少配额。顺着它来即可：
caching 另有 5 条面向「从零搭 agent」的设计准则（tools 不中途增删、defer_loading、不跨模型、消息传递更新而非改 system prompt、compaction 伪装成父对话延续），不在本文范围，不展开。
上下文：你唯一真正在管的资源
loop 是现成的，你管的是输入什么、何时清。几乎所有使用差异都源于对窗口的管理。Claude 每完成一步，你都站在一个分支点上，5 个选择，4 个是为了管上下文质量：
compaction 是有损压缩：接近上限时把整段对话总结成摘要，模型在全新窗口里基于摘要继续。问题出在自动触发的时机，它恰好落在模型最弱的时刻：
场景：读了 5 个文件、试方案 A 失败、要换 B。
失败连同纠正都留着
「那个不行，试试 B」，失败的方案 + 你的纠正全留在上下文里，继续增加噪音、干扰判断。
回到岔路口，干净换路
退到「读完 5 文件、还没试 A」的点，再说「别用 A，foo 没暴露那接口，直接用 B」。留下文件读取，丢掉失败尝试。
配套 "Summarize from here"：让 Claude 把所学写成一条交接消息，相当于未来的 Claude 给过去的自己写信（「我试了 A，因……行不通」），避免后续会话重蹈覆辙。
/compact 与 /clear 都清上下文，区别在谁决定保留什么：
| 维度 | /compact | /clear |
|---|---|---|
| 工作量 | 低，Claude 自动总结 | 高，你手动提炼 |
| 控制精度 | Claude 决定保留什么 | 你决定携带什么 |
| Context Rot | 部分缓解 | 完全消除 |
| 适用 | 任务中途清冗余 | 开始全新任务 |
| 场景 | 推荐 | 原因 |
|---|---|---|
| 同任务，上下文仍相关 | Continue | 窗口内容都还在起作用 |
| Claude 走错了路 | Rewind | 留文件读取、丢失败尝试 |
| 会话堆满过时调试信息 | /compact + 指令 | 省力，你引导方向 |
| 开始全新任务 | /clear | 零 rot，你完全控制 |
| 下一步大量只需结论的输出 | Subagent | 中间噪音留子上下文 |
新任务 = 新会话。关联任务权衡：高度相关就继续（省去重读），否则 /clear。subagent 的心智测试，「我要的是工具输出本身，还是只要结论？」只需结论就派出去，更多用法见第三层。
知识与工具：7 层施工图
这层是全文核心框架。一个常被忽略的前提：harness 的重要性等于甚至超过模型本身。先说底层机制，Claude 找代码用的是 agentic search，不是 RAG：
| 维度 | RAG 工具 | Claude Code · agentic search |
|---|---|---|
| 索引维护 | 需 embedding pipeline | 不需要 |
| 时效性 | 滞后（小时/天/周） | 实时操作 live codebase |
| 失败模式 | 返回已删/改名的函数，无提示 | 无此问题 |
| 扩展性 | 数千人并发提交时跟不上 | 每个实例独立运行 |
代价：它需要足够起始上下文知道「从哪开始找」，导航质量取决于 setup 质量。结论:投入 codebase setup 的团队拿到更好的结果。
| 层 | 最常见的错误用法 |
|---|---|
| L1 CLAUDE.md | 塞可复用专业知识（该进 skill） |
| L2 Hooks | 用 prompt 实现本该自动跑的 |
| L3 Skills | 全塞 CLAUDE.md |
| L4 Plugins | 让好配置停在个人手里 |
| L5 LSP | 以为是自动的（要装 plugin 加 language server） |
| L6 MCP | 基础没搞好就先建 |
| L7 Subagents | 同一 session 同时探索与编辑 |
permissions.deny 提交进版本控制、全团队共享。很多人以为 Skill 就是一个 SKILL.md。其实它是一个文件夹，SKILL.md 只是入口，旁边还能挂脚本、参考资料、模板、甚至自己的 hooks，这正是它比一段提示词强的地方。
SKILL.md 给方法，scripts/ 给手脚，references/ 按需加载省上下文。官方把 Skills 的常见用途归成九类，从查文档一路覆盖到运维：
来自 Anthropic 内部上百个 Skills 的九条最佳实践：
把 skill 写对
- 不讲废话：聚焦能把 Claude 推出默认思维的信息（例：叮嘱避免 Inter 字体和紫色渐变）
- 建 Gotchas 章节：最值钱的内容，逐条记录失败点并持续更新
- 文件系统做渐进式揭露：细节拆进
references/api.md，要用才读 - 别过度限制灵活性；Description 是触发条件，不是摘要
让 skill 持久好用
- 存脚本让 Claude 组合，而非重建重复模板
- 按需 Hooks：
/careful拦rm -rf、DROP TABLE - 持久化用
CLAUDE_PLUGIN_DATA（skill 目录升级会被删） - 用户配置用
config.json，没设就让 agent 用 AskUserQuestion 问
分享：小团队签入 .claude/skills，规模化走 plugin marketplace（需筛选避免烂 skill）。用 PreToolUse hook 记调用量看哪些受欢迎。一条经验：好 skill 多从几行字开始、随踩坑完善。
MCP 把外部数据源和系统接入会话。本文只讲怎么接进来用，怎么设计一个 MCP server 不在本文范围。接入侧有两个降本开关，都是客户端能力，不是 server 设计：
MCP 与 Skills 互补：MCP 给工具和数据，Skills 给操作知识，最强的 agent 两者兼用。（MCP server 五大设计模式不在本文范围。）
早在 2024 年末，Claude 3.5 Sonnet 仅用 Bash 和 Text Editor 两个通用工具就拿下 49% 的 SWE-bench Verified，当时的 SOTA。Claude Code 的架构基础至今仍是这两个通用工具，Skills、Memory 都是它们的组合。
编排：计划该交给谁
问题变成：一个任务，让 Claude 自行逐回合承载整个计划，还是把计划交由他处持有。原则：小任务不拆分，大任务不让模型在上下文中独自记忆整个计划。
它是什么
- 三特性：全新起点（不继承历史）、并行、权限隔离（研究只读 / 实现可编辑）
- General-purpose：全工具，复杂多步
- Plan Agent：只读，研究加规划
- Explore Agent：只读，快速搜索
什么时候派出
- 研究密集（读几十个文件）
- 多个独立任务（并行）
- 需要全新视角（不继承假设/偏见）
- 提交前验证（独立检查）
- 流水线工作流（明确阶段/交接）
成熟度路径一句话：先对话，后自动化。先用自然语言，观察哪些反复出现，再固化：
.claude/agents/，description 写触发条件该用的姿势
- 先研究再实现（从摘要谈起，而非 20 个原始文件）
- 并行批量改（独立文件套同一模式）
- 独立代码审查（全新视角更客观）
- 流水线（设计/实现/测试，用文件交接）
别这么用
- 顺序依赖：单会话顺着做更干净
- 同文件编辑：并行改同一文件会冲突
- 小任务：委派有开销，直接做
- 专家 agent 过多：降低自动委派可靠性
- 需 agent 间协调：彼此不能通信，该用 Agent Teams
区分三者的不是规模，而是一个问题：那枚标着 PLAN 的方块在谁手里。Subagent/Skill 时由 Claude 逐回合持有、中间结果落进上下文；Workflow 让脚本持有，Claude 只看最终答案。
| Subagents | Skills | Workflows | |
|---|---|---|---|
| 谁决定下一步 | Claude，逐回合 | Claude，跟 prompt | 脚本 |
| 中间结果存哪 | Claude 的上下文 | Claude 的上下文 | 脚本变量 |
| 可复现什么 | worker 定义 | 指令 | 编排本身 |
| 规模 | 每回合几个 | 同 subagent | 每 run 几十到几百 |
| 中断时 | 重启该回合 | 重启该回合 | 同会话内可 resume |
Workflow 不是 Skill 的替代，两者正交：Skill 改变「模型知道什么」，Workflow 改变「如何确定性地编排」。一个 workflow 里 fan-out 的 agent 完全可以先挂 skill 再干活。
/workflows 选满意的 run，按 s 存成 command。收敛是退出条件而非固定轮数。触发：prompt 写 workflow / /effort ultracode / 跑已存 command；自带 /deep-research。可用性 Max/Team/API 默认开、Pro 需 /config、Enterprise 默认关。token 消耗远高于普通会话，先在小任务试手，大 run 前看 /model 把不需最强模型的阶段路由到小模型。
用 workflow 把 Bun 从 Zig 移到 Rust：约 75 万行、11 天、测试通过率 99.8%，四个串联 workflow（① 映射 Rust lifetime ② 逐文件翻译，数百 agent 并行、每文件两个 reviewer ③ 驱动 build/测试到双绿 ④ 夜间优化、每处单独 PR 等人审）。但前提极其特殊，不可理解为「任意迁移都能 11 天」：
- strangler-fig 渐进替换，不是推倒重建，Zig 与 Rust 全程链入同一 binary、按类逐个开关切换
- 每次切换都过 tests + shadow-diff + 不超过 2% 性能门禁，是验证驱动收敛而非「完成即信任」
- 极高既有测试覆盖（99.8% 的前提是套件够强）、单作者主导、尚未投入生产（99.8% 终究不是 100%）
正确读法：在有强测试与强验证门禁的高价值模块上，确定性脚本 + build/test 修复循环，能把按季度估的工程压到天级。先挑这样一块试点，而非照搬时间承诺。
默认 harness 把规划与执行挤在同一上下文，碰上长时间跑、大规模并行、对抗性任务就会塌，塌法有三种，这正是要把计划搬进脚本的原因：
偷懒
50 项审查做到 35 项就宣布「搞定」。
自我偏袒
评判自己刚做的东西时倾向回护。
目标漂移
多回合后忠实度流失，compaction 丢掉「别做 X」。
Workflow 从结构上治这三样：偷懒，脚本持有完整清单、循环不到末尾不算完；自我偏袒，验证交给另一个独立 agent；目标漂移，目标写在脚本里、不随 compaction 流失。
Classify-and-act
分类器判断任务属哪类，路由到不同 agent。给流水线装个分诊台。
Fan-out-and-synthesize
拆成多步各一 agent，合成是 barrier：唯一要等齐的。
Adversarial verification
每个干活 agent 配一个专门 agent 拿 rubric 对抗式验证，治自我偏袒。
Generate-and-filter
先发散一堆想法，按 rubric 筛、去重，只留最优几个。
Tournament
N 个 agent 各用不同打法做同题，两两比较直到分出胜者。
Loop until done
任务量未知时不设固定轮数，循环到停止条件成立。
成对比较（comparative judgment）比绝对打分更可靠，排序类任务尤其如此。
反直觉的是，它在非技术工作上常更有用。官方点名的九个用例，过半与写代码无关：
读取不可信公开内容的 agent 不得执行高权限动作，高权限动作交给另一批专责执行的 agent。读取与执行分离，这是防 prompt injection 的结构性手段。
什么时候别用：workflow 能在很多场景做出超常结果，但并非每个任务都需要、且烧多得多的 token。先问「这真需要更多算力吗」。多数传统编程任务并不需要一个五人评审团。窍门：详细 prompt 最关键；小任务可开 quick workflow；配 /loop /goal；写 use 10k tokens 封顶；按 s 存进 ~/.claude/workflows 或纳入 skill。把它当探索新用法的起点，不是终点。
验证：执行者不应评判自己的产出
代码编写成本已经很低，瓶颈后移到验证。核心一句：生成不等于评估，二者必须分离。让干活的 agent 评自己的产出，它几乎总自信地给好评，如同让开发者审自己的代码。一个工程现实：把独立 Evaluator 调严，比让 Generator 学会自我批评容易得多。
用独立 review subagent，或 Workflow 的对抗式验证 pattern，让验收与执行不是同一个、也不共享上下文。纯 Claude Code 用法，不写一行额外代码。
把产物改造成 agent 可读可验的接口（data-verify-* 契约、window.__verify API、.verify.ts）。核心论点是「经济学翻转」：agent 把验证的边际成本压到趋零，contract testing 才第一次在前端规模化可行。这是改造自有产品才会做的事。
70 万行遗留代码库的接入
把四层组合用在开篇提到的 Skyline 上。核心方法论：把 Claude 当新员工 onboard，像带实习生一样，解释足够背景让它完成一个有限项目，并为下一轮产出更好的 context。这是个五步闭环，每轮起点更高：
pwiz-ai，而非代码仓库，否则会被分支隔离，每个分支上的 Claude 成了「不同的人」。团队当正式工程产物维护、打版本。四条启示：scope 隔离是前提（大屎山不能一把梭，切片喂、逐步扩展）· debugging skill 必须硬约束（70 万行盲改一行可能连锁爆炸）· context 必须独立于代码分支 · MCP 打通测试基础设施。一个诚实的前提：这不是装上就能用的银弹，需要有人维护 context 层、渐进推进。但它在「最不适合 AI 的场景」里跑通了。
边搭边砍：harness 的半衰期
harness 不是一次搭就一劳永逸，它有半衰期。每个组件都编码了一个对模型能力的假设，而假设会过期。能删多少，取决于模型多强。
真实案例：Sonnet 4.5 近上限时会「上下文焦虑」提前结束任务，团队加了段 context reset 补偿；Opus 4.5 上线、这行为消失后，那段代码就成了纯负担。同理，一个为强制走 Perforce p4 edit 而拦截写文件的 hook,在原生支持后也变多余。正确心态不是「怎么让 Claude 更强」,而是「我能停止做什么」。
但有些东西删不掉。Planner 与 Evaluator 这类分工制衡保留了下来：没有 Planner，Generator 会 under-scope；没有 Evaluator，边界任务的 bug 会遗漏。可删减的(脚手架)与不可删减的(上下文纪律、分工验证)要分清。建议每 3 到 6 个月做一次 harness 审计。