Harness 工程

约 2074 字大约 7 分钟

2026-03-30

Harness：把 AI 从"大脑"变成"全副武装"的 Agent

什么是 Claude Code Harness

Harness（线束/挽具） 是围绕 AI 模型构建的完整基础设施——工具调用、上下文管理、权限控制、执行环境、记忆系统和扩展点，将语言模型从一个"大脑"变成一个有"身体"的可用 Agent。

类比来说：AI 模型是马（强大但不可控），Harness 就是缰绳和鞍具，通过结构和边界将这股力量引导到正确方向。

Claude Code 的 Harness 架构可以概括为：

一个 Agent Loop + 工具集（Bash、Read、Write、Edit、Glob、Grep、Browser...）+ 按需加载的 Skills + 上下文压缩 + Subagent 派生 + 任务系统 + 团队协作 + Worktree 隔离 + 权限治理

Harness 工程（Harness Engineering）

Harness Engineering 作为一门新兴学科，关注的是如何设计系统、约束和反馈循环，使 AI Agent 在生产环境中可靠运行。它有五个核心支柱：

支柱	说明
Tool Orchestration	工具编排——定义 Agent 能使用哪些工具、如何组合
Guardrails & Safety	安全护栏——权限控制、操作限制、危险行为拦截
Error Recovery	错误恢复——失败重试、回退策略、反馈循环
Observability	可观测性——日志、指标、Agent 行为追踪
Human-in-the-Loop	人机协作——关键决策点的确认机制

六大扩展面

Claude Code 的 Harness 由六个核心扩展面组成，它们协同工作：

┌─────────────────────────────────────────────┐
│              Claude Code Harness             │
│                                              │
│  ┌──────────┐  ┌──────────┐  ┌───────────┐  │
│  │  Hooks   │  │  Skills  │  │ Subagents │  │
│  │ 生命周期  │  │ 可复用   │  │ 专业化    │  │
│  │ 自动化    │  │ 工作流   │  │ AI 助手   │  │
│  └────┬─────┘  └────┬─────┘  └─────┬─────┘  │
│       │              │              │         │
│  ┌────┴─────┐  ┌────┴─────┐  ┌─────┴─────┐  │
│  │   MCP    │  │ Plugins  │  │ CLAUDE.md │  │
│  │ Servers  │  │ 可分发   │  │ + Memory  │  │
│  │ 外部工具  │  │ 扩展包   │  │ 持久上下文 │  │
│  └──────────┘  └──────────┘  └───────────┘  │
│                                              │
│  ┌──────────────────────────────────────┐    │
│  │         settings.json 配置层          │    │
│  │    权限 · Hooks · MCP · 环境变量      │    │
│  └──────────────────────────────────────┘    │
└─────────────────────────────────────────────┘

组件	职责	配置位置
Hooks	在生命周期事件点执行确定性自动化	`settings.json` 的 `hooks` 块
Skills	可复用的提示词 / 工作流，通过斜杠命令调用	`.claude/skills/<name>/SKILL.md`
Subagents	拥有独立上下文的专业化 AI 助手	`.claude/agents/<name>.md`
MCP Servers	外部工具集成（数据库、API、浏览器等）	`.mcp.json` 或 `settings.json`
Plugins	可分发的扩展包，捆绑 skills + agents + hooks + MCP	Plugin Marketplace
CLAUDE.md + Memory	持久化的项目上下文和指令	项目各级 `CLAUDE.md` 文件

Hooks：确定性自动化

Hooks 是 Harness 中最重要的机制之一。与 Skills 不同，Hooks 提供的是确定性控制——确保特定操作总是发生，而不是依赖 LLM 的判断。

24 个生命周期事件

截至 2026 年 3 月，Claude Code 支持 24 个 Hook 事件：

类别	事件
会话	`SessionStart`、`SessionEnd`
用户输入	`UserPromptSubmit`
工具调用	`PreToolUse`、`PostToolUse`、`PostToolUseFailure`
权限	`PermissionRequest`
通知	`Notification`
完成	`Stop`、`StopFailure`
子 Agent	`SubagentStart`、`SubagentStop`
任务	`TaskCreated`、`TaskCompleted`
团队	`TeammateIdle`
配置	`InstructionsLoaded`、`ConfigChange`
工作区	`CwdChanged`、`FileChanged`、`WorktreeCreate`、`WorktreeRemove`
上下文	`PreCompact`、`PostCompact`
MCP	`Elicitation`、`ElicitationResult`

四种 Hook 类型

// 1. command — 执行 shell 命令
{ "type": "command", "command": "prettier --write $FILE" }

// 2. http — POST 事件数据到 HTTP 端点
{ "type": "http", "url": "https://hooks.example.com/events" }

// 3. prompt — 单轮 LLM 评估（默认 Haiku）
{ "type": "prompt", "prompt": "Is this edit safe? Return JSON" }

// 4. agent — 多轮子 Agent 验证，最多 50 轮工具调用
{ "type": "agent", "prompt": "Review this change for security" }

退出码语义

退出码	效果
0	操作继续。stdout 可注入上下文
2	阻断操作。stderr 作为反馈返回给 Claude
其他	操作继续。stderr 仅记录日志

实用场景

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "prettier --write \"$CLAUDE_FILE\""
      }]
    }],
    "PreToolUse": [{
      "matcher": "Edit",
      "hooks": [{
        "type": "command",
        "command": "node scripts/check-protected-files.js"
      }]
    }],
    "Notification": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "osascript -e 'display notification \"$CLAUDE_NOTIFICATION\"'"
      }]
    }]
  }
}

更多 Hooks 细节参见 Hooks 钩子

Subagents：专业化分工

Subagents 是运行在独立上下文窗口中的专业 AI 助手，拥有自定义系统提示、特定工具访问和独立权限。

内置 Subagents

Agent	模型	工具权限	用途
Explore	Haiku	只读	代码搜索和分析
Plan	继承	只读	Plan 模式下的调研
General-purpose	继承	全部	复杂多步任务
Bash	继承	终端	在隔离上下文中执行命令

自定义 Subagent

在 .claude/agents/<name>.md 中定义：

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Grep, Glob, Bash
disallowedTools: Write, Edit
model: sonnet
maxTurns: 50
memory: project
isolation: worktree
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./validate.sh"
---

你是一个代码审查专家。审查代码时关注...

关键能力

持久记忆：memory: user | project | local，通过 MEMORY.md 跨会话保留知识
后台执行：Ctrl+B 将 Agent 放入后台，继续其他工作
Worktree 隔离：isolation: worktree 在独立 Git 工作树中运行
会话恢复：Subagent 可带完整对话历史恢复
并行运行：最多同时 10 个 Subagent

Agent Teams（实验性）

需要 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1，支持 2-16 个 Agent 协作：

共享任务列表：~/.claude/tasks/{team-name}/，支持状态、负责人、依赖关系
邮箱系统：Agent 间通过 SendMessage 直接通信
文件锁：防止任务认领时的竞争条件
自动解锁：前置任务完成后自动解锁依赖任务

Plugin 系统与生态

Plugins 是可分发的扩展包，将 Skills、Agents、Hooks 和 MCP 配置捆绑为一个可安装单元。

Plugin 结构

my-plugin/
├── skills/          # Skill 目录
│   └── my-skill/
│       └── SKILL.md
├── agents/          # Subagent 定义
│   └── reviewer.md
├── hooks/
│   └── hooks.json   # Hook 配置
└── README.md

安装方式

# 添加 Marketplace
/plugin marketplace add <marketplace-url>

# 安装插件
/plugin install <plugin-name>@<marketplace>

生态现状（2026 年初）

43 个 Marketplace
834+ 插件
官方市场：anthropics/claude-plugins-official

安全提示：Plugin 的 Subagent 不能使用 hooks、mcpServers、permissionMode 字段（安全限制，会被忽略）。

社区 Harness 项目

Superpowers

最流行的社区 Harness 框架（123,000+ stars），提供完整的软件开发方法论。

核心 Skills：Brainstorming → Writing-plans → Test-driven-development → Executing-plans → Systematic-debugging → Verification-before-completion → Code-review → Finishing-a-development-branch

理念：测试先行、系统化 > 随意、降低复杂度、证据 > 断言

/plugin install superpowers@claude-plugins-official

oh-my-claudecode

团队优先的多 Agent 编排插件，包含 19 个专业 Agent、28 个 Skills 和 31 个生命周期 Hooks。

特色：团队协作编排（v4.1.7+ team 为主入口）、插件化模块架构、从想法到代码的全自动执行。

/plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode

claude-code-harness

专用开发 Harness，实现 Plan-Work-Review-Ship 工作周期，配备 TypeScript 安全引擎。

护栏规则（R01-R13）：13 条声明式安全规则，包括阻断 sudo、保护 .git/.env、要求项目外写入确认、阻断 force-push、防止 --no-verify 提交等。

/plugin marketplace add Chachamaru127/claude-code-harness

其他值得关注的项目

项目	说明
awesome-claude-skills	社区 Skills 精选列表
claude-code-config (Trail of Bits)	安全导向的默认配置
awesome-claude-code-subagents	100+ 专业 Subagent 定义
claude-code-hooks-mastery	Hooks 进阶教程

HaaS：Harness as a Service

随着 Claude Code SDK 的推出，出现了 HaaS（Harness as a Service） 概念——从 client.chat.completions.create() 演进到 agent.query()。

核心转变：

Before：开发者自己组装工具、权限、循环
After：构建者创建定制 Harness，使用者直接接入

这意味着 Harness 不再只是本地开发工具，而是可以作为服务提供的 Agent 执行环境。

最佳实践

配置层面

项目配置 (.claude/settings.json) 用于团队共享规则；本地配置 用于个人偏好
将 .claude/skills/ 和 .claude/agents/ 提交到版本控制，让团队共享工作流
SKILL.md 保持 500 行以内，参考材料放到辅助文件中

Hooks 层面

Hooks 用于确定性操作（格式化、阻断、通知）；Skills 用于需要判断的任务
Matcher 写窄——空 matcher 在 PermissionRequest 上会自动批准所有操作
Stop hooks 中检查 stop_hook_active 防止无限循环
Shell profile 中的 echo 语句用 [[ $- == *i* ]] 包裹，避免 JSON 解析失败

Subagents 层面

每个 Subagent 聚焦一项专业任务
遵循最小权限原则，只授予必要的工具访问
只读探索用 Haiku（更快更便宜），复杂推理用 Opus
并行修改代码时使用 isolation: worktree

安全层面

不硬编码密钥——MCP 配置中使用 ${env:VAR_NAME}
Plugin Subagent 不能使用 hooks/mcpServers/permissionMode（安全限制）
Deny 规则始终覆盖 Hook 的自动批准
生产环境考虑使用护栏框架（如 claude-code-harness 的 R01-R13）

Claude Code

OpenAI

Qwen Code