agent-harness-construction Skill 是 Everything Claude Code 面向生产环境的核心能力之一，专注于系统性设计和优化 AI Agent 的 action space、工具定义与观测输出格式。通过精细化工具粒度、规范化输入输出、完善错误恢复和上下文预算管理，该 Skill 能大幅提升 AI 编程助手（如 Claude Code、Codex、Cursor 等）在复杂任务下的完成率、稳定性和可维护性。本文将结合实战场景，手把手教你如何用好 agent-harness-construction Skill，打造高质量、可持续演进的 AI Agent Harness 体系。

Everything Claude Code Agent Harness Construction：设计 AI Agent action space 和 tool definitions 提升任务完成率

在 AI 编程助手日益普及的今天，如何让 Agent 在面对复杂、长链路任务时稳定输出高质量结果，成为生产级应用的关键。agent-harness-construction Skill 正是为此而生——它帮助开发者系统性设计 Agent 的 action space（动作空间）、tool definitions（工具定义）和 observation（观测）输出格式，显著提升任务完成率和自动化闭环能力。

相比传统的“堆工具、拼接口”做法，agent-harness-construction 强调结构化、可控、易于恢复和度量的 Agent Harness 设计思路，尤其适用于多 Agent 协作、自动化 Hook、MCP 流水线等高复杂度场景。你可以在 Everything Claude Code 完全指南 了解全局架构，本文聚焦于 agent-harness-construction Skill 的落地实践。

适用场景与激活时机

你应该在以下场景主动启用 agent-harness-construction Skill：

• 新建或重构 AI Agent Harness 时，需系统性规划 action space、工具粒度和错误恢复机制
• 现有 Agent 任务完成率低、经常卡死或输出不稳定，需要优化工具定义和观测格式
• 多 Agent/Skill 协作下，发现工具语义重叠、输出混乱、上下文超载等问题
• 需要为 Agent 增加自动恢复、智能重试和上下文压缩能力，实现端到端闭环

在实际项目中，agent-harness-construction Skill 常与 Autonomous Agent Harness Skill、Verification Loop Skill、Hooks 自动化体系 等配合，形成高可靠性的 AI 编程自动化链路。

分步操作指南

步骤 1：梳理 Agent 的 Action Space

目标：让 Agent 的每一步操作都明确、可控、易于追踪。

• 明确每个工具（Tool）的功能边界，避免语义重叠
• 工具命名要稳定、显式，便于 Agent 规划和调用
• 输入参数采用 schema-first 设计，类型严格、范围窄化
• 输出格式保持确定性，便于后续自动处理

示例

// 不推荐：模糊工具定义
tools: [
  { name: "do_something", input: "any", output: "string" }
]

// 推荐：结构化、精细化工具定义
tools: [
  { 
    name: "edit_file", 
    input: { path: "string", content: "string" }, 
    output: { status: "success|error", summary: "string", artifacts: ["string"] } 
  },
  { 
    name: "run_tests", 
    input: { test_suite: "string" }, 
    output: { status: "success|error", summary: "string", next_actions: ["string"] } 
  }
]

步骤 2：合理划分工具粒度

目标：根据任务风险和复杂度，选择合适的工具颗粒度。

• 高风险操作（如部署、迁移、权限变更）用 micro-tool，单一职责、最小化影响面
• 常规编辑/查阅/搜索等用 medium-tool，兼顾效率与可控性
• 仅在 round-trip 成本极高时才用 macro-tool，防止 Agent 失控

实践建议

• 不要为同一语义设计多个近似工具，防止 Agent 选择混乱
• 工具粒度可随 Agent 进化动态调整，配合 Hooks 实现自动化升级

步骤 3：规范 Observation（观测）输出格式

目标：每次工具调用后，Agent 都能获得结构化、可追踪的反馈，便于后续决策和恢复。

• 输出字段建议包含：
  • status: success | warning | error
  • summary: 一句话描述结果
  • next_actions: 推荐后续动作（可选）
  • artifacts: 产物路径或 ID（如生成的文件、报告等）

输出示例

{
  "status": "error",
  "summary": "测试用例 test_login 失败，原因：数据库连接超时",
  "next_actions": ["检查数据库服务状态", "重试 run_tests"],
  "artifacts": []
}

步骤 4：完善 Error Recovery（错误恢复）机制

目标：让 Agent 在遇到错误时能给出明确的根因、恢复建议和终止条件，提升闭环能力。

• 每个错误路径都应包含：
  • root cause hint（根因提示）
  • safe retry instruction（安全重试建议）
  • explicit stop condition（明确终止条件）

实践要点

• 错误输出不应只有“error”，必须有“下一步怎么做”
• 可结合 Verification Loop Skill 实现自动恢复与多轮验证

步骤 5：优化 Context Budget（上下文预算）

目标：让 Agent 在有限 token 内最大化信息密度，避免上下文溢出导致失控。

• 系统提示（system prompt）保持最小且不变
• 大量指导信息按需加载为 Skill，不直接塞进 prompt
• 长文档用文件引用而非全文 inline
• 只在阶段边界做上下文压缩，而非随意丢弃 token

配套建议

• 配合 Context Budget Skill 自动审计 token 占用
• 结合 Iterative Retrieval Pattern 优化多 Agent 上下文窗口

步骤 6：选择合适的架构模式

• ReAct（推理-行动循环）：适合探索性、路径不确定的任务
• Function-calling（函数调用）：适合结构化、流程确定的任务
• 推荐混合模式：ReAct 规划 + Typed Tool 执行，兼顾灵活性与可控性

步骤 7：度量与持续优化

• 持续追踪以下指标：

  • 任务完成率（completion rate）
  • 每任务重试次数（retries per task）
  • pass@1、pass@3（一次/三次内成功率）
  • 单次成功任务的成本（cost per successful task）

• 定期用 Agent Eval Skill 横向对比不同 Harness 设计的表现

输出示例

假设你为一个自动化代码审查 Agent 设计了新的 action space 和工具定义，Agent 调用工具后的标准输出如下：

{
  "status": "success",
  "summary": "已完成对 PR #123 的 TypeScript 代码质量审查，发现 2 处潜在问题",
  "next_actions": ["修复变量命名不规范", "优化异步处理逻辑"],
  "artifacts": ["reports/pr123_review.md"]
}

如遇到错误：

{
  "status": "error",
  "summary": "代码分析失败，原因：依赖包缺失",
  "next_actions": ["运行 npm install", "重试代码分析"],
  "artifacts": []
}

常见配套 Agent 与 Skill 协作关系

• 与 Harness Optimizer Agent 协作，自动诊断并优化本地 Harness 配置
• 与 Verification Loop Skill 联动，提升端到端验证与恢复能力
• 与 Hooks 自动化体系 配合，实现 PreToolUse/PostToolUse/Stop 等事件驱动自动化
• 与 Agentic Engineering Skill 结合，支持复杂任务分解与多 Agent 协作

反模式与注意事项

• 工具数量过多且语义重叠，导致 Agent 选择混乱、效率低下
• 工具输出不透明，无恢复线索，遇错即停
• 错误输出无“下一步”，Agent 无法自愈
• 上下文中塞入无关引用，token 浪费导致 Agent 失控

FAQ

Q: agent-harness-construction Skill 和普通工具链设计有何本质区别？
A: 它强调结构化、可恢复、可度量和上下文友好的设计，远超简单的“工具堆叠”，更适合生产级 AI Agent 自动化。

Q: 需要多大工程量迁移到 agent-harness-construction 风格？
A: 通常只需梳理现有工具定义、输出格式和错误处理逻辑，逐步替换即可，无需推倒重来。

Q: 这个 Skill 适合多大规模的团队或项目？
A: 适用于从个人项目到大型多 Agent 系统，尤其在任务复杂度提升、Agent 协作增多时效果最显著。

---