Better Harness

Better Harness 快速入门

给 AI 编码 Agent 装上”方向盘”——让它不再盲目改代码，而是有策略地迭代。

这是什么？适合谁？

Better Harness 是一个面向 AI 编码 Agent 的工程化测试与改进框架。它解决了一个核心痛点：当你让 Claude Code 或 Codex 改代码时，Agent 经常会陷入”改了又改、越改越乱”的循环——Better Harness 通过预定义的 Harness 模板和自动回归检查，让 Agent 每次修改都有靶心可瞄。

简单说：你给 Agent 一个任务（比如”重构这个模块”），Better Harness 会先跑一遍测试建立基线，然后 Agent 改代码时自动验证”改动是否破坏了现有功能？""新写的代码覆盖率够不够？“，最后给出一个可审计的改进报告。

适合这些用户：正在用 AI Agent 做日常开发的工程师，厌倦了 Agent “改完 A 坏了 B”的反复调试；技术 Leader 想在团队中推广 AI 辅助开发但担心代码质量下降；开源项目维护者需要自动化地评估 PR 质量。

核心差异：不是又一个 Agent 框架，而是给现有 Agent 加了测试安全带——支持 Claude Code、Codex、Cursor、Qoder 等多个 Agent，你不需要换工具。

准备工作

• Node.js 18+：框架基于 JavaScript/TypeScript，需要 Node 运行环境
• AI 编码 Agent：至少有一个可用的编码 Agent（Claude Code、Codex CLI、Cursor 任一），Better Harness 本身不包含 AI，它是 Agent 的”陪练”
• 一个测试项目：任何有测试框架的 Node.js / Python 项目都可以作为试验田
• Git：Harness 依赖 Git 管理代码变更和回滚
• 付费提示：Better Harness 本身免费开源（MIT），但 Agent 调用会产生费用（取决于你用的 Agent 定价）

3 步快速上手

第 1 步：安装

# 克隆仓库
git clone https://github.com/QoderAI/better-harness.git
cd better-harness

# 安装依赖
npm install

# 全局安装 CLI
npm link

第 2 步：初始化 Harness 配置

在你的项目根目录下初始化：

cd /path/to/your-project
better-harness init

这会在项目根目录创建 .better-harness/ 目录，包含默认的 Harness 模板和测试规则。配置文件 .better-harness/config.yaml 可以指定：

• agent: 使用的编码 Agent（如 claude-code、codex、cursor）
• testCommand: 测试运行命令（如 npm test）
• coverageThreshold: 最低覆盖率要求

第 3 步：运行第一个 Harness 任务

# 让 Agent 执行一个任务，同时用 Harness 监控
better-harness run "重构 src/utils/parser.js，提高可读性"

# Harness 会自动：
# 1. 运行测试建立基线
# 2. Agent 修改代码
# 3. 自动运行测试验证
# 4. 对比代码质量指标
# 5. 输出改进报告

预期结果：终端输出一个彩色报告，显示”测试通过率 100%""覆盖率从 72% 提升到 85%""复杂度下降 12%“。

踩坑指南

踩坑 1：Agent 没有自动安装，Harness 报”agent not found”

症状：运行 better-harness run 时报 agent not found: claude-code

原因：Better Harness 依赖系统中已安装的编码 Agent CLI，它不会自动帮你安装

解决：先确认 Agent CLI 已全局安装。以 Claude Code 为例：

npm install -g @anthropic-ai/claude-code
claude --version  # 确认安装成功

踩坑 2：大型项目首次运行超时

症状：项目有 500+ 测试用例时，Harness 在”建立基线”阶段卡住

原因：默认会运行全量测试，大型项目耗时较长

解决：在 .better-harness/config.yaml 中指定范围：

testCommand: "npm test -- --testPathPattern=src/utils"

踩坑 3：Agent 修改了 Harness 自己的文件

症状：Agent 在修改项目代码时，不小心改动了 .better-harness/ 下的配置

原因：Agent 的上下文窗口包含了项目所有文件，没有自动排除 Harness 目录

解决：在 Agent 的 .gitignore 或 prompt 中明确排除 .better-harness/：

echo ".better-harness/" >> .agentignore  # 如果 Agent 支持

踩坑 4：覆盖率阈值设太高导致任务永远失败

症状：coverageThreshold: 100，Agent 反复修改但永远达不到 100% 覆盖率

原因：100% 覆盖率在实际项目中几乎不可能，Agent 会陷入无限循环

解决：设置合理阈值。建议新手从 70% 开始，逐步提高：

coverageThreshold: 70  # 从 70 开始，别设 100

踩坑 5：多 Agent 同时跑同一项目导致 Git 冲突

症状：同时用 Claude Code 和 Codex 跑两个任务，Git 出现合并冲突

原因：Better Harness 每次都在当前分支上操作，并发修改会冲突

解决：一个项目同时只跑一个 Harness 任务。多任务用不同分支隔离：

git checkout -b harness/refactor-parser
better-harness run "重构 parser"  # 在这个分支上跑

初级用法

场景 1：重构单个函数

better-harness run "把 src/utils/formatDate.js 的 formatDate 函数改为 arrow function，不改行为"

Harness 会确保重构后所有测试仍然通过，且行为不变。

场景 2：批量修复 Lint 警告

better-harness run "修复 src/ 下所有 ESLint warning，不要改业务逻辑"

场景 3：为新功能写测试

better-harness run "给 src/api/users.js 的 getUserById 函数补充单元测试，覆盖所有分支"

高级玩法

玩法 1：自定义 Harness 规则

在 .better-harness/rules/ 下创建自定义规则文件，定义 Agent 必须遵守的约束：

// rules/no-console.js
module.exports = {
  name: 'no-console-in-production',
  check: (code) => !code.includes('console.log'),
  message: '生产代码中禁止使用 console.log',
};

玩法 2：CI/CD 集成

在 GitHub Actions 中集成 Better Harness，让 Agent 自动检查和修复 PR：

- name: Better Harness Auto-Fix
  run: |
    better-harness run "修复本次 PR 的代码审查意见" --agent claude-code
    git diff --exit-code || echo "Agent 进行了自动修复，请人工确认"

玩法 3：批量任务流水线

串联多个 Harness 任务形成质量流水线：

better-harness pipeline \
  "重构 src/" \
  "补充单元测试" \
  "优化 import 顺序" \
  "检查安全漏洞"

小技巧

1. 先跑 better-harness dry-run——不实际调用 Agent，只检查配置是否正确
2. 用 --verbose 看 Agent 的完整对话记录——了解 Agent 为什么做了某个修改
3. 定期 better-harness report --html 生成可视化报告发给团队
4. 给 Harness 任务写描述时越具体越好——“重构”太模糊，“把 3 个 if-else 改成 switch”才明确
5. 设置 maxIterations 防止死循环——默认 10 轮，复杂任务可调到 20

常见问题 FAQ

Q1: Better Harness 和其他 Agent 测试工具有什么区别？

A: 它专注于”给 Agent 加测试安全带”，而不是替代 Agent。类似的工具如 Sweep 更偏自动化 PR，Better Harness 更偏 Agent 工程化。对于中小项目，Better Harness 的配置更轻量。

Q2: 支持哪些编程语言？

A: 框架本身是语言无关的——它只是运行你指定的 testCommand。如果你能用命令行跑测试，Better Harness 就能用。Node.js、Python、Go、Rust 都经过验证。

Q3: 需要 API Key 吗？

A: Better Harness 本身不需要——它使用系统中已配置的 Agent（Agent 需要自己的 API Key）。免费开源，MIT 协议。

Q4: 每次运行 Agent 花费多少？

A: 取决于任务大小。一个典型的”重构一个文件 + 跑测试”任务，使用 Claude Sonnet 约 $0.05-0.20。建议先用小任务测试。

Q5: 如果 Agent 改坏了代码怎么办？

A: Better Harness 每次运行前自动创建 Git stash。如果测试失败，可以用 better-harness rollback 一键恢复。

参考链接

• 官方仓库
• MIT 开源协议
• Issues 讨论区

基于公开资料整理，AI 辅助生成 | 核验日期：2026-07-31