深度解读：AI Harness 工程实践——从理论到基于 Claude Code 的落地

背景

在大型语言模型（LLM）能力日益强大的当下，如何让模型稳定、可控地完成复杂、长时间运行的任务，成为 AI 工程化的核心挑战。传统的单轮对话或简单链式调用难以应对需要多步规划、迭代验证、状态管理的场景。为此，Anthropic 与 OpenAI 分别提出了“Harness”模式——一种引导智能体（Agent）自主完成复杂工作流的工程框架。本文源自 LINUX DO 论坛一位资深开发者的长帖，该帖系统分享了他个人基于 Claude Code 构建 Harness 的完整方法论，涵盖理论、架构、记忆、调度、状态设计及实际案例，是对前沿 AI 工程实践的一次详细拆解。

核心内容

1. Harness 的基本概念与理论来源

作者指出，Anthropic 当前所有产品均采用 Harness 模式，OpenAI 也在智能体优先的方向上利用 Codex 实现自举。Harness 的本质是“引导 AI 代替自己完成工作，而开发者只需持续优化 Harness 本身”。作者推荐了几篇理论文章（Anthropic Harness 工程实践、OpenAI 的 Harness Engineering、构建长时间高效运行的智能体），作为入门阅读材料。

2. 技术选型：基于 Claude Code 的路线

作者强调自己的 Harness 完全基于 Claude Code，因为 Claude Code 本身具备 SDK 所有功能，且提供了一个现成的“执行层”。他给出了两条路线的选择题：

• 路线 1（个人选择）：以 Claude Code 的插件或技能（skill）形式编写 Harness，要求熟读 Claude Code 相关文档。
• 路线 2（大厂选择）：以 OpenAI/Anthropic SDK、LangGraph、Spring AI、AgentScope 等纯原生形式编写，需要自行查找对应文档。

3. 记忆层设计——共识记忆

作者认为工程应先做“表关系”，即设计共识记忆（Consensus Memory）目录。以 Web 应用构建为例，他的 Harness 项目目录结构如下：

.web-builder/
├── feature_list.json    # 功能注册表 — 唯一可信来源
├── spec.md              # 产品规格
├── design_tokens.json   # 视觉标识（调色板、字体、反模式）
├── sprint_plan.json     # 冲刺分解
├── progress.md          # 持续构建日志
└── sprint_N_*.md        # 各冲刺的合约、交接、QA 报告

这些文件作为 Harness 各子智能体间共享的“共识状态”，保持所有组件对项目目标的一致理解。

4. 三层架构 + 协同调度

Harness 的核心架构分为三层，外加一个协同调度层（Orchestration）：

• 规划层（Planner）：解构用户需求，评估合理性，分解为多个 Sprint。
• 生成层（Generator / Executor）：根据规划结果生成代码、测试或其他产物。
• 评估层（Evaluator）：对生成结果进行 QA 审查（如运行 Playwright 测试），给出评分与 Bug 列表。
• 协同调度（Orchestration）：作者使用 Claude Code 的 command 作为调度开关，通过 subagent 依次调用三层，且命令始终阻塞等待子任务完成，避免跳步风险。特别注意：不能使用 background 模式，否则会导致上下文丢失或逻辑跳跃。

5. 长时间运行机制与流程调度

Harness 需要维护正向迭代循环。作者以 Planner 为例展示了典型循环：

1. 收集需求 → 2. 扩展验证 → 3. 评估合理性 → 不合理则撤销并回到步骤 2 → 合理则进入 4. 分配 Sprint → 若 Sprint 分配不合理则回退 → 合理则完成。

调度（Orchestration）的具体流程：

1. 启动 command。
2. 初始化环境（目录、Claude.md、settings.json、.git 等）。
3. 启动 Planner 解构需求，生成 Sprint 计划（6-8 个 Sprint），写入记忆文件。
4. 进入 Rahlp Loop（可能是作者自创的循环术语）：启动 Generator 读取记忆文件并生成代码 + Playwright 测试代码。
5. Generator 完成后启动 Evaluator，执行 Playwright，总结 Bug 列表，评分。若评分达到阈值（如 75/100）则进入下一循环；否则修复后再评估。
6. 重复直至所有功能的 passes 字段均为 true。

作者强调，git/PR 步骤并非 Harness 核心，可省略以节约 token，但 Anthropic 和 OpenAI 推荐保持工作区干净。

6. 状态设计

Harness 的状态是纵向的流程控制节点，示例状态链： 启动 → 初始化 → 初始化结束 → 规划 → 规划结束 → 生成 → 生成结束 → 评估 → 评估结束 → 完成。

也可细化到子节点，但作者不推荐过于复杂。状态的本质是流程节点数决定了关键状态数。

7. 能力设计（提示词编写）

作者给出了三个子智能体的提示词模板示例（英文原文，中文翻译版供理解，实际建议用英文以节省 token）：

• Planner Agent：读取 skill，创建 .web-builder/ 基础文件，按完成标准输出。
• Generator Agent：实现当前 Sprint 功能，按定向步骤、冲刺工作流、实现规则执行，输出交接信号。
• Evaluator Agent：严格测试，诚实评分，发现问题而非赞美。包含合约审查、QA 流程、评分维度（通过阈值 75/100）。

8. Skill 与 MCP 的引入

• Skill：Anthropic 设计，为上下文减负。运行时只加载每个 skill 的前 250 个字符，因此描述应一句话概括能力，详细逻辑放在 script 内。避免安装过多无意义的大型框架（如 agency-agent、superpower、everything-claude-code），否则会消耗大量 token。
• MCP（Model Context Protocol）：用于连接真实世界。作者推荐在 Harness 设计中引入 Figma MCP（增强页面设计能力）和 Playwright MCP（增强端到端验证能力），以补齐 AI 短板。但注意 Harness 本身的产物应先用于连接真实世界，MCP 只是辅助手段。

9. 工程实操示例与常见错误

作者给出了几个待完成的 Harness 主题（如 AI 知识库、AI 音频、AI 空间、AI 排版），同时分享了一个业务错误演示：他尝试构建一个基于 Claude Code 的 Chat Web 供同事使用，但由于需求描述过于抽象，Harness 错误地理解成使用 Claude 模型本身而非 Claude Code，虽然页面功能正常，但本质不符合预期。调整提示后，新生成结果完全可用。

关键要点

• Harness 本质：不是单一提示词，而是完整的工程框架，包含共识记忆、规划-执行-评估三层、协同调度、状态管理、能力提示词、外部工具集成（MCP、Skill）等组件。
• 核心原则：引导 AI 自主工作，开发者只优化 Harness 本身；流程必须正向迭代，不能出现逻辑跳步；状态设计要明确流程节点。
• 技术选型建议：个人开发者可用 Claude Code + skill 快速落地；大厂可用原生 SDK 或框架以获得更高控制力。
• 记忆文件是基础设施：功能注册表、规格、设计令牌、Sprint 计划、进度日志等构成共享上下文，是 Harness 稳定的基础。
• 调度器（Orchestration） 必须使用阻塞式命令（Claude Code 的 subagent），禁止 background 模式，否则容易导致上下文丢失或逻辑错误。
• 提示词（Agent 能力设计） 应写英文以节省 token，且每个 agent 职责单一：Planner 只做规划，Generator 只做生成，Evaluator 只做评估。
• Skill 与 MCP 是减负工具，但不可滥用：Skill 描述要精简，MCP 只用于补短板（如 Figma 设计、Playwright 测试），