Claude Code Harness

规划. 开发. 评审. 交付.
适用于 Claude Code、Codex CLI、Cursor 和 Grok 的规范化交付流程

English | 日本語

问题所在

智能体编码容易偏离方向。计划停留在聊天记录中，然后就不见了。在截止日期压力下，测试成了可选项。代码合并后才进行评审。发布依据要靠回忆来重建。

Harness 将"让智能体编写代码"的模式转变为一条可重复的路径：

编写规范 → 仅实现已批准的部分 → 验证 → 独立评审 → 整理交付依据。

它不会让模型变得更智能。它改进的是围绕模型的流程和边界——因此即使模型发生变化，整个系统仍能正常工作。

本 README 中的所有功能描述均经过机器验证。 CI 检查确保所述组件实际已连接，任务记录保持一致，并且发布的二进制文件可从源代码重新构建。只有在检查确认功能可用后，才会在此处列出。写出来的不代表能工作的。

30秒快速安装

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

然后给它一些简单的东西：

/harness-plan Improve the README onboarding flow

Harness 会为你草拟 spec.md 和 Plans.md。你的工作不是编写计划，而是在继续执行前批准或修正它。

使用其他工具？请参见下方的按工具安装。

循环

5 个核心动词技能保持了简洁的操作界面：plan（计划）、work（执行）、review（审查）、sync（同步）、release（发布）。 （/harness-setup 在安装时运行一次，如上所述。）

命令	功能说明
/harness-plan	将意图转化为 spec.md + Plans.md：包括范围、验收标准、依赖项、未知项、停止条件。
/harness-work	执行一项已批准的任务或整个计划。当任务需要时添加测试。
/harness-work all	执行整个已批准的计划。在计划明确且仓库基线已知时使用。
/harness-review	独立于实现过程审查结果。重大问题将阻止完成。
/harness-sync	比较计划与实际实现内容，并报告偏差。
/harness-release	仅将经过验证的证据打包到 CHANGELOG、标签和发布版本中。

每个阶段都会为下一阶段留下所需的材料。

阶段	输出	关卡
计划	spec.md + Plans.md	你批准或修正生成的契约。
执行	代码和测试	任务要求时必须采用 TDD。
审查	独立评审意见	重大问题将阻止完成。
PR	证据包	PR 就绪不等同于发布就绪。
发布	标签和制品	发布预检必须通过。

代理未见过的数据会保持为 unknown（未知）状态，而不会被悄悄编造。

安全层

这正是 Harness 与提示模板的区别所在。每个工具调用在运行前都会由 Go 引擎进行裁决——而不是事后审查，因为文件差异无法反映网络发送或文件删除操作。

两层防护，强度刻意不同。

层级	决策内容	可覆盖性
运行时底线 — 5 个类别	直接拒绝	否。 无法通过任何配置、环境变量或权限模式覆盖
护栏规则 — R01–R15	拒绝 / 确认 / 警告	部分可通过项目配置调整

底线涵盖账单、网络出口、密钥读取、生产环境部署以及任务工作区外的删除操作。它位于独立的代码路径上，没有禁用开关，因此自主运行无法通过自我说服绕过它。

护栏是你可以调整的层级。直接推送到 main 分支、写入受保护路径、强制推送、历史重写——每一项都有明确的裁决，其中一些可按项目进行配置。

确认环节移至计划阶段。 Harness 不会在运行过程中打断你，而是会预先收集计划中需要的风险操作，并一次性询问。批准具有有效期、任务范围和使用限制——因此一次批准绝不会成为永久的漏洞。

每次拦截都有记录。 规则 ID、类别和裁决结果会记录到 JSONL 日志中。命令文本从不记录；仅记录哈希值和长度，对于密钥读取和账单操作，甚至连这些也不记录。你可以统计实际拦截的内容，而无需猜测。

非技术人员的决策界面

三个单屏 HTML 视图让非技术人员无需阅读代码即可进行判断。

界面	适用时机	显示内容
计划简报	计划最终确定后	理解、选项、风险、验收标准
进度	工作进行中	WIP/TODO/已完成数量及偏差警报，自动重新生成
验收	发布前	按标准显示通过/未通过，包含发布/等待/拒绝选项

按工具安装

四种安装途径并非提供四种相同的保证。安装脚本仅意味着工具具有入口路径，而非共享的产品承诺。

工具	层级	途径
Claude Code	supported	插件市场，然后执行 /harness-setup
Codex CLI	supported	scripts/setup-codex.sh --user
Cursor	supported	scripts/setup-cursor.sh — 控制在 harness 端，参见 说明
Grok	supported	scripts/setup-grok.sh
Codex app	candidate	仅候选版冒烟测试；CLI 验证未复用
OpenCode	internal-compatible	scripts/setup-opencode.sh；不保证运行时一致性
Hermes Agent	candidate	手动符号链接研究途径
GitHub Copilot CLI	candidate	手动配置文件研究
Antigravity CLI	future/unsupported	尚无最终用户安装途径

层级含义及严格划分原因

EN 层级	日语公开表述
supported	正式対応
internal-compatible	互換利用可 / 制限付き対応
candidate	試験対応 / プレビュー
future/unsupported	非対応 / 将来検討

Claude Code、Codex CLI、Cursor 和 Grok 在其已验证的声明路径上通过了 H1–H8（H4 实时验证 2026-07-17；H7 发布预检失败关闭线路 2026-07-19）。其他所有工具在通过各自的 H1–H8 之前，均保持列出的层级（docs/spec/planning-and-host-adapter.md，第 111 阶段）。

Harness 不继承 Superpowers、Hermes Agent 或任何其他项目的支持声明。只有当 Harness 拥有自己的引导程序、触发器、运行时和发布证据时，宿主工具才能升级。

not_observed != absent — 本地验证缺失意味着“此处未证明”。这并不表示不可能，也不表示受支持。

已在使用 Harness？请先运行迁移报告

bin/harness doctor --migration-report

它会清点过时的 Claude 插件缓存、重复的 Codex 技能、旧符号链接、OpenCode 备份路径以及 harness-mem 状态——不会删除任何内容。

高级功能

在基础功能正常运行后，可以使用这些功能。

功能	新增内容	边界限制
Breezing	规划师/评审师/工作者团队协作执行更大规模的任务列表	仍受计划质量和评审的限制
Codex 伴生评审	通过 scripts/codex-companion.sh 提供基于模式的第二意见	原始 codex exec 并非伴生路径
harness-mem	跨会话的项目范围内存与召回	可选功能；清除操作仍需显式进行
OpenCode 引导	将指导内容镜像到 OpenCode 兼容的界面	不保证运行时一致性
auto-approve（实验性）	HARNESS_AUTO_APPROVE=on 会将关卡结果记录到编排 ledger 中	默认关闭。暂未跳过审批提示

要求

• 支持 Claude 路径需要 Claude Code v2.1+
• 具有写入权限的仓库
• Go 原生防护引擎不需要 Node.js
• 可选：harness-mem 用于跨会话内存

文档

资源	描述
工具优先入门指南	按宿主工具划分的入门起点
安装路径	各工具的设置步骤和层级边界
迁移检查	现有用户影响和回滚方案
技能触发验证	安装成功的验证方式
功能矩阵	完整的宿主功能声明表
Claude Code 兼容性	版本要求和注意事项
Cursor 集成	交接边界和包含关系
分发范围	包含内容、兼容内容与仅开发内容的区别
强化一致性	不同宿主之间的安全差异
Work All 证据包	完整计划运行的验证约定
语言 / 国际化	切换输出语言
更新日志	用户可见的版本历史

贡献指南

欢迎提交问题报告和拉取请求。详情请参见 CONTRIBUTING.md。

致谢

• AI Masao — 分层技能设计
• Beagle — 测试篡改防护模式

许可证

采用 MIT 许可证。详见 LICENSE.md。