Harness（脚手架）

⚠️ 源单薄性声明 本页虽然引用了多条本地资料，但主要还是围绕 Claude Code 体系展开。 也就是说，这里讲清楚的是“Claude Code 视角下 harness 由什么构成、为什么重要”，还不是跨产品的行业定本。

一句话

Harness = AI 在你项目里运行时依赖的整套脚手架。
它不只是一句 prompt，而是 prompt、工具、权限、记忆、上下文规则、恢复机制、多 agent 组织方式等组件的总和。

在本 wiki 里，可以把它先理解成：让 AI 从“能回答”变成“能稳定交付”的运行环境。

为什么重要

how-claude-code-works.md 有一句很关键：
Claude Code 是围绕 Claude 的 agentic harness。

这句话的重点是：
同一个底层模型，套上不同 harness，用户体验会差很多。

本地橙书的判断也很直接：

• 模型决定能力上限
• harness 决定这个上限能兑现多少

所以，很多时候不是“模型不行”，而是：

• 权限设计太乱
• 上下文管理太差
• 工具接入不稳
• 没有恢复手段
• 角色和边界没定义

Harness 由什么构成

1. 说明书层

• [[CLAUDE.md]]
• path-scoped rules
• output style / system prompt 的长期约束

它负责回答：
“这个 AI 在这个项目里应该按什么方式做事？”

2. 工具层

• [[skill]]
• [[MCP]]
• hooks
• slash commands

它负责回答：
“这个 AI 能做什么、连什么、自动触发什么？”

3. 角色与组织层

• [[agent]]
• [[subagent]]
• [[workflow]]

它负责回答：
“谁负责什么、什么时候分工、什么时候隔离执行？”

4. 权限与隔离层

• permission modes
• settings.json
• [[Sandboxing 入门]]

它负责回答：
“哪些动作可以直接做，哪些要审批，哪些物理上做不了？”

5. 上下文与记忆层

• [[上下文]]
• [[上下文工程]]
• [[CLAUDE.md]]
• auto memory

它负责回答：
“AI 当前看见什么、长期记住什么、该忘掉什么？”

6. 恢复与控制层

• [[Checkpointing 与 /rewind]]
• [[Plan Mode 起手法]]

它负责回答：
“走偏了怎么回、动手前怎么先看后做？”

和 agent / skill / CLAUDE.md / sandboxing 的关系

这几个词最容易被拆散看，但实际上它们是 harness 的不同层：

• [[CLAUDE.md]]：说明书层
• [[skill]]：能力包层
• [[agent]] / [[subagent]]：角色与组织层
• [[Sandboxing 入门]]：权限与隔离层

只看其中一个都会失真。
比如：

• 只有 CLAUDE.md，没有权限边界，AI 还是可能乱跑
• 只有 skill，没有上下文管理，session 还是会被塞爆
• 只有 sandbox，没有说明书，AI 只是“安全地胡来”

最小可跑通例子

一个最小可用的 harness，至少要回答四个问题：

1. AI 是谁、怎么做事？
   • CLAUDE.md
2. AI 能用哪些能力？
   • skill / MCP / commands
3. AI 能动到哪里？
   • settings + permissions + sandboxing
4. AI 走偏了怎么回来？
   • plan mode + checkpointing

对应到项目里，最小形态通常像这样：

.claude/
  CLAUDE.md
  settings.json
  agents/
  skills/

上面这棵树不一定都要写满，但如果四个问题一个都没回答，那就几乎谈不上 harness，只能算“裸奔调用模型”。

场景与反例

场景：同一个模型，不同 harness，体验完全不同

一个新人第一次开 Claude Code，什么都不配，直接上来让它改项目。
另一个人则已经配好：

• 项目 CLAUDE.md
• 常用 skill
• 基本 sandbox
• subagent 分工
• /rewind 与 plan mode 习惯

底层模型可能一样，但两人的“稳定性、速度、返工率”会明显不同。
这差别主要就来自 harness。

反例：harness 越堆越重

如果一个项目一上来就堆：

• 20 个 agent
• 50 个 skill
• 一堆 MCP server
• 很长的 CLAUDE.md
• 复杂 hook 链

那它也可能变成反效果：启动更慢、上下文更重、调试更难。
harness 的目标不是“堆组件”，而是让工作流更稳、更清楚。

常见误解

误解 1：Harness = 提示词工程

不对。
prompt 只是 harness 的一个层面，不是全部。

误解 2：Harness 越复杂越好

不对。
过度设计的 harness 很容易把可控性变成配置黑魔法。

误解 3：Harness = IDE / 编辑器

不对。
编辑器只是承载界面；真正的 harness 还包括权限、记忆、工具、恢复机制和组织方式。

误解 4：Claude Code 就等于 harness

半对。
Claude Code 提供了一个现成 harness 的基础设施，但你项目里的 CLAUDE.md、skills、rules、sandbox 配置，仍然需要你自己补齐。

与其他术语的关系

• [[提示词工程]]：harness 的 prompt 层。
• [[上下文]] / [[上下文工程]]：harness 的内存管理层。
• [[CLAUDE.md]]：harness 的说明书层。
• [[skill]] / [[MCP]]：harness 的工具接入层。
• [[agent]] / [[subagent]] / [[workflow]]：harness 的组织层。
• [[Sandboxing 入门]]：harness 的安全隔离层。
• [[Checkpointing 与 /rewind]] / [[Plan Mode 起手法]]：harness 的恢复与控制层。

延伸阅读

• [[CLAUDE.md]]
• [[Sandboxing 入门]]
• [[subagent]]
• [[Checkpointing 与 /rewind]]
• raw/2026-04-18/claude-code-docs/how-claude-code-works.md
• raw/2026-04-18/huasheng-orange-books/pdfs-text/02-source-code.txt

needs_sources（明确待补）

• Claude Code 之外的 harness 对比
• harness 过度设计的真实失败案例
• 中文语境里更稳定的术语边界

---

🎬 3 个场景（读者最可能用到的情境）

场景 1 · Claude Code 作为 harness

写作者打开 Claude Code 处理一个长期项目：CLAUDE.md + .claude/agents/ + .claude/skills/ + settings + git 历史 + MCP——这一整套围绕 Claude 的运行环境就是 harness。同一个 Claude 模型，用 harness 和不用 harness，产出的稳定性差一个量级。

集景 2 · Aider / Cursor / OpenHands 对比

Aider 是 terminal + git 流派，Cursor 是 IDE 集成流派，OpenHands 是开源 autonomous 流派。都是 harness，但风格不同：Aider 强调 git safety，Cursor 强调 UX，OpenHands 强调 headless 自主。

场景 3 · 裸跑模型 vs 套 harness

散户在网页 chat.openai.com 粘代码问问题，没项目规则、没权限、没记忆，每次重新解释。换成 Claude Code + 配好的 CLAUDE.md + skill，同样的模型，返工率立刻下降。

⚖️ 和最像的邻居比

术语	本质区别	适用边界
harness	模型之外的整套运行脚手架	讨论”怎么让模型稳定兑现能力”
agent	有目标/角色的执行体	谁来做、做什么
IDE / 编辑器	承载界面	只是 harness 的前端
prompt engineering	harness 的一个层面	单层优化

🚫 反例（不该这么用）

反例 1 · 混淆 harness 与 agent

“Claude Code 就是一个 agent”——不对。Claude Code 是 harness，它承载的 agent 是你在 .claude/agents/ 里定义的那些。正确认知：harness = 运行环境，agent = 在这个环境里工作的角色。

反例 2 · harness 越堆越重

项目一上来就配 20 个 agent、50 个 skill、10 个 MCP server、长达 5000 字的 CLAUDE.md、复杂 hook 链。结果启动变慢、调试地狱、可控性反而下降。正确做法：从”最小 harness”开始——CLAUDE.md + 2 个 skill + 基本 settings，按需长。

❓ 常见误解

• 误解 1：“harness 就是 IDE” → 实际：IDE 只是承载界面，真正的 harness 还包括权限（sandbox）、记忆层（CLAUDE.md / MEMORY）、工具接入（skill / MCP）、恢复机制（checkpointing / plan mode）。
• 误解 2：“Claude Code = harness 的全部” → 实际：Claude Code 只是提供了 harness 的基础设施，你项目里的 CLAUDE.md、skills、rules、sandbox 配置才让它真正成形。
• 误解 3：“harness 复杂度 = 能力” → 实际：harness 目标是”让工作更稳”，不是”堆更多组件”；过度设计反而会把可控性变成配置黑魔法。

---

🧬 历史坐标（最早谁提 · 本质 · 分型 · git）

最早谁提

“Test harness” 是计算机工程古老概念（xUnit 时代就有）。“Agentic harness” 作为 AI 术语在 2025 年 Claude Code 文档《how-claude-code-works》中被官方定调——“Claude Code is an agentic harness around Claude”。Anthropic 后续在 Claude Agent SDK 中把 harness 表述为”general-purpose agent harness”。官方文档：https://code.claude.com/docs/en/how-claude-code-works

本质（一句话 · 20 字内）

让模型从”能回答”变”能交付”的运行脚手架。

分型 / 演化（2-4 行主线）

• 早期 · Python/Node REPL 给了”交互式 AI 壳”的最简原型
• 2023 中 · Aider（paul-gauthier 首发）把 terminal + git + LLM 串成 AI pair programming harness
• 2023-24 · Cursor 把 harness 做进 IDE（supervised 流派），Claude Code / Aider / Devin 走 autonomous 流派
• 2025+ · “harness” 正式成为行业术语：模型决定上限，harness 决定兑现率（权限、记忆、工具、恢复机制的总和）

代表 git / 文档

• anthropics/claude-code · Anthropic · 最完整的开源 agentic harness 参考实现
• Aider-AI/aider · Paul Gauthier · terminal + git 的 harness 先驱
• How Claude Code works · Anthropic · “agentic harness” 术语官方来源