Claude Code 专用开发环境：通过自主计划-工作-审查循环实现高质量开发

这是什么

claude-code-harness 是一个针对 Anthropic 的 Claude Code 智能体工作流进行规范化的开源工具项目。它并非一个独立的 AI 模型或新的编码代理，而是一个基于 Shell 脚本构建的“纪律性交付循环”（Disciplined Delivery Loop）框架。

该项目由 Chachamaru127 维护，在 GitHub 上已获得 1794+ Star。其核心理念是将原本松散、依赖对话上下文的 AI 编码工作，转化为一个结构化的、可重复的操作路径。它通过引入 spec.md（规格说明书）和 Plans.md（计划文件）作为“单一事实来源”（Source of Truth），强制 AI 代理在编码前进行规划、在编码后进行独立审查，并最终打包可验证的发布证据。

解决的问题

在直接使用 Claude Code 等 AI 编程助手时，开发者常面临以下痛点：

1. 工作漂移（Agent Drift）：AI 生成的代码往往偏离最初意图，因为“计划”仅存在于聊天窗口中，缺乏持久化的约束。
2. 测试缺失：测试常被视作可选步骤，导致代码质量不可控。
3. 审查滞后：代码审查通常在代码生成完成后才进行，此时修改成本极高。
4. 证据重建困难：发布版本时，缺乏自动化的、可追溯的验证证据，往往需要依靠人工记忆重新整理。
5. 幻觉与静默错误：AI 可能会“发明”未见过的项目数据，而不是诚实地标记为 unknown。

Harness 旨在通过强制性的流程步骤，解决上述问题，将 AI 从“自由发挥的 coder”转变为“严格执行契约的 worker”。

核心功能

Harness 通过五个核心动词技能（Verb Skills）构建其工作流：Plan（规划）、Work（执行）、Review（审查）、Sync（同步）、Release（发布）。

1. 结构化规划 (/harness-plan)

• 生成契约：用户只需输入自然语言描述的需求，/harness-plan 会自动起草 spec.md 和 Plans.md。
• 明确边界：文件中包含范围（Scope）、验收标准（Acceptance Criteria）、未知项（Unknowns）和停止条件（Stop Conditions）。
• 团队验证模式：对于非平凡的任务，它支持 team_validation_mode，通过模拟子代理或手动视角，从规格对齐、内存复用、产品契合度、安全性等多个维度验证计划。
• 单一事实来源：AI 代理严格以这些文件为基准。如果数据未在文件中体现，代理必须将其视为 unknown，严禁静默发明数据。

2. 受控执行 (/harness-work)

• 切片实施：AI 仅实施经过批准的特定任务切片（例如 /harness-work 1.1.1）。
• TDD 驱动：强制执行测试驱动开发（TDD）和即时验证，确保每一步实现都经过检验。

3. 独立审查 (/harness-review)

• 解耦审查与实现：审查过程独立于编码过程，避免 AI 在生成代码时自我审查导致的偏差。
• 验证输出保留：审查结果被明确记录，作为后续发布的依据。

4. 证据打包 (/harness-release)

• 最小化发布包：仅打包经过验证的证据（Verified Evidence），用于生成 Pull Request 或发布版本，确保发布内容的可追溯性。

5. 迁移与诊断 (bin/harness doctor)

• 迁移报告：在清理或重装前，运行 bin/harness doctor --migration-report 可盘点过期的 Claude 插件缓存、重复的 Codex 技能、旧的符号链接及 harness-mem 状态，而不删除任何数据。

亮点 / 与同类相比

• 从“对话式”到“契约式”： 大多数 AI 编程工具依赖多轮对话来澄清需求，容易导致上下文丢失。Harness 强制将需求固化为 spec.md 和 Plans.md，使 AI 行为具有可预测性和可审计性。

• 不继承其他项目的支持声明： 项目文档明确指出，Harness 不会继承 Superpowers、Hermes Agent 等其他项目的主张。它要求宿主环境具备独立的引导（Bootstrap）、触发器（Trigger）、运行时（Runtime）和发布证据。这是一种严谨的“不观察不等于不存在”（not_observed != absent）的哲学，强调本地证明的重要性。

• 原生 Go 引擎，无 Node.js 依赖： 尽管主语言为 Shell，但其护栏引擎（Guardrail Engine）由 Go 原生编写，无需安装 Node.js 环境，降低了依赖复杂度和启动开销。

• 支持多代理路径： 除了 Claude Code，Harness 还为 Codex 和 OpenCode 提供了有界路径（Bounded Paths），允许用户在不同 AI 工具间迁移或混合使用，同时保持工作流的一致性。

• 跨会话记忆 (harness-mem)： 可选的 harness-mem 模块支持跨会话记忆，当配置正确且健康时，可保持项目上下文的一致性，避免重复解释背景信息。

适合谁用 / 上手

适合人群

• Claude Code 重度用户：希望将 AI 编码工作标准化、流程化的开发者。
• 对代码质量有高要求的团队：需要强制 TDD、独立审查和可追溯发布证据的工程团队。
• 多 AI 工具使用者：同时使用 Claude Code、Codex 或 OpenCode，希望统一工作流规范的开发者。
• 已有复杂 AI 插件环境的用户：需要通过迁移报告清理缓存和冲突配置的资深用户。

上手指南

1. 环境要求：

   • Claude Code v2.1+（用于支持的 Claude 路径）。
   • 具有写权限的项目仓库。
   • 无需 Node.js（Go 原生引擎）。

2. 安装步骤： 在 Claude Code 环境中执行以下命令：

   /plugin marketplace add Chachamaru127/claude-code-harness
   /plugin install claude-code-harness@claude-code-harness-marketplace
   /harness-setup
   

3. 首次工作流示例：

   • 规划：运行 /harness-plan 并附带一个小请求（如 "Improve the README onboarding flow"）。AI 将生成 spec.md 和 Plans.md 草稿。
   • 审查与批准：人工检查生成的契约，批准或提出修正。
   • 执行：运行最小的已批准任务，例如 /harness-work 1.1.1。
   • 审查：运行 /harness-review 并保留验证输出。
   • 核心原则：用户的核心工作不是手写计划，而是批准或修正生成的契约，然后让 AI 执行。

4. 迁移建议： 现有用户在进行清理或重装前，务必先运行 bin/harness doctor --migration-report 以评估现有状态。