claude-code-harness
为 Claude Code 量身定制的开发工作流增强插件，通过「计划→工作→审查→发布」闭环解决 agent 工作漂移问题。相比直接使用 Claude Code，它强制生成规范文档、独立审查和可验证的交付证据，避免测试遗漏和记忆幻觉。支持跨会话记忆（可选 harness-mem）和 Codex/OpenCode 等工具的兼容适配。适合追求代码质量和流程可复现的团队，MIT 许可。
README
Claude Code Harness
规划. 执行. 审查. 发布.
为 Claude Code 打造的一套纪律严明的交付循环，同时为 Codex 和 OpenCode 提供受控路径。
中文 | 日本語
Claude Code 功能强大，但原始 agent 工作容易跑偏：计划停留在对话中、测试变成可选、审查发生得太晚、发布证据依靠记忆重建。Harness 将这一切转化为一条可重复的操作路径。
安装后，默认行为从“让 agent 写代码”变为：
- 编写规范与计划，
- 仅实现已批准的部分，
- 验证结果，
- 独立审查，
- 打包证据用于 PR 或发布。
快速开始
新用户应从他们已使用的工具入手。现有用户在清理或重新安装前应运行迁移报告。
| 路径 | 起点 |
|---|---|
| 新用户 | 以工具为导向的入门 |
| 现有用户 | 迁移检查 |
| Claude Code 快速路径 | 30 秒安装 |
| 触发器验证 | 技能触发器关卡 |
30 秒安装
claude
/plugin marketplace add Chachamaru127/claude-code-harness
/plugin install claude-code-harness@claude-code-harness-marketplace
/harness-setup
接下来：用一个小请求运行 /harness-plan。
/harness-plan 改进 README 的入门流程
前 15 分钟
- 通过你的工具路径安装。
- 运行
/harness-setup或等效的设置脚本。 - 用一个简单请求运行
/harness-plan；Harness 会生成spec.md和Plans.md草稿供你检查。小的拼写、文档和状态更新保持轻量。 - 批准生成的合约，或回复你想要的修正。
- 运行最小的已批准任务，例如
/harness-work 1.1.1。 - 运行
/harness-review并保留验证输出。
你的工作不是手写计划。而是在执行继续之前批准或修正生成的合约。
工作原理
Harness 在 agent 工作周围增加了一个事实来源循环。5 个动词技能保持这个表面简洁：plan、work、review、sync、release。
- 你用自然语言描述期望结果。
/harness-plan草拟或更新spec.md和Plans.md，包含范围、验收标准、未知项和停止条件。- 非平凡的计划会记录
team_validation_mode，并通过团队/子 agent 或人工检查视角对计划进行验证，以确保 spec/Plans 对齐、记忆复用、产品适配、安全适配以及实践可行性。 - Harness 将这些文件视为事实来源。agent 未看到的数据保持为
unknown，而非被默默编造。 /harness-work以 TDD 和验证方式实现已批准的部分。/harness-review将审查与实现分开。/harness-release仅打包已验证的证据。
命令
| 命令 | 内部行为 |
|---|---|
/harness-setup |
安装项目指南、命令表面、钩子和检查，使工作流从一个已知基线开始。 |
/harness-plan |
将意图转化为 spec.md 和 Plans.md，包括范围、验收标准、依赖、未知项、停止条件以及非平凡计划验证。 |
/harness-work |
执行一个已批准的任务或范围，必要时添加测试，运行验证，并将工作保持在计划内。 |
/harness-work all |
运行完整的已批准计划，经历实现和审查路径；在计划明确且仓库基线已知后使用。 |
/harness-review |
独立于实现审查结果，并将重大发现视为阻塞项。 |
/harness-release |
在实现和审查完成后，检查发布就绪状态、CHANGELOG/标签边界以及证据打包。 |
bin/harness doctor --migration-report |
盘点旧的插件缓存、Codex 技能、OpenCode 文件、符号链接和记忆状态，而不删除数据。 |
基本工作流
| 阶段 | 输出 | 关卡 |
|---|---|---|
| 调查 | 证据和未知项 | 不要将未被观察的数据提升为声明。 |
| 计划 | spec.md + Plans.md |
用户批准或修正生成的合约。 |
| 执行 | 代码和测试 | 当任务要求时，必须使用 TDD。 |
| 审查 | 独立判决 | 重大发现阻塞完成。 |
| PR | 证据包 | PR 就绪不等于发布就绪。 |
| 发布 | 标签/发布工件 | 必须在发布路径上通过发布预检。 |
按工具安装
| 工具 | 层级 | 路径 |
|---|---|---|
| Claude Code | supported |
Claude 插件市场，然后 /harness-setup。 |
| Codex CLI | internal-compatible |
scripts/setup-codex.sh --user；直接插件冒烟测试单独跟踪。 |
| Codex app | candidate |
仅候选冒烟测试；不要复用 Codex CLI 的证据。 |
| OpenCode | internal-compatible |
scripts/setup-opencode.sh；不声称运行时对等性。 |
| Cursor | candidate |
仅限 PM 移交或适配器研究。 |
| GitHub Copilot CLI | candidate |
仅限手动配置文件研究。 |
| Antigravity CLI | future/unsupported |
此阶段无最终用户安装路径。 |
现有用户迁移
在更改现有设置前，运行 bin/harness doctor --migration-report。该报告会盘点过时的 Claude 插件缓存、重复的 Codex 技能、旧的符号链接、OpenCode 备份路径和 harness-mem 状态，但不删除任何内容。
支持边界
Harness 可以描述候选路径，但不继承来自 Superpowers、Hermes Agent 或任何其他项目的支持声明。只有当 Harness 拥有自己的 bootstrap、触发器、运行时和发布证据时，主机才会升级。
not_observed != absent：缺少本地证据意味着“在此处未证明”，而非“不可能”或“受支持”。
需求
- Claude Code v2.1+（用于受支持的 Claude 路径）。
- 一个具有写权限的项目仓库（用于本地设置）。
- Go 原生护栏引擎不需要 Node.js。
- 可选 harness-mem 用于跨会话记忆（在配置且健康时）。
高级用法
在基本触发器路径可见后再使用这些功能。
| 能力 | 新增内容 | 边界 |
|---|---|---|
| Breezing | 针对较大任务列表的规划者/评论者/工作者风格的团队执行。 | 仍受计划质量和审查的约束。 |
| Codex 伴侣审查 | 通过 scripts/codex-companion.sh 提供基于模式的 Codex 第二意见。 |
原生的 codex exec 不是 Harness 伴侣路径。 |
| OpenCode 引导 | 将 Harness 指导镜像到 OpenCode 兼容表面。 | 不声称真正的运行时对等性。 |
| harness-mem | 跨会话的项目级记忆和回忆功能。 | 可选伴侣；清除仍然是显式的。 |
文档
| 资源 | 描述 |
|---|---|
| 以工具为导向的入门 | 根据主机工具从哪里开始。 |
| 安装路径 | 每种工具的设置和支持层级边界。 |
| 迁移检查 | 现有用户影响、兼容性和回滚路径。 |
| 技能触发器关卡 | 如何验证安装成功。 |
| 能力矩阵 | 受支持、内部兼容、候选和不受支持的主机声明。 |
| Claude Code 兼容性 | 当前 Claude Code 的需求和兼容性说明。 |
| Cursor 集成 | Cursor 移交边界和候选路径说明。 |
| 分发范围 | 包含路径 vs 兼容性路径 vs 仅开发路径。 |
| 强化对等性 | Claude 钩子与 Codex 关口之间的运行时安全差异。 |
| Work All 证据包 | 全计划执行的成功/失败验证合约。 |
| 变更日志 | 面向用户的版本历史。 |
贡献
欢迎提交 Issue 和 PR。参见 CONTRIBUTING.md。
致谢
许可证
MIT 许可证。参见 LICENSE.md。