参考资源：

• NPM 包主页：https://www.npmjs.com/package/@sweetlemonai/harness-ai
• GitHub 仓库：https://github.com/sweetlemonai/harness-ai
• 有问题提 Issue：https://github.com/sweetlemonai/harness-ai/issues

注意：本文工具：@sweetlemonai/harness-ai → 只能用于 Node/TypeScript

从“写个任务单”到“自动创建 PR”，让 AI 替你跑完整个开发流程

前言：你是否有过这样的经历？

你让 AI 帮忙实现一个功能，它写完了代码，然后呢？

• 你需要手动跑测试，看看有没有把别的地方搞坏
• 你需要自己检查代码风格、类型错误
• 你需要手动创建 PR，写描述，找人审查
• 如果测试失败了，你得告诉 AI 去修，然后重复以上步骤

每个环节都不难，但加起来非常繁琐。

Harness 就是来解决这个问题的——它是一个 AI 工程化流水线，你只需要写一个任务单（像一张 Jira 工单），剩下的事情（写代码、跑测试、检查类型、创建 PR）全部自动完成。

一、Harness 是什么？

一句话解释： Harness 是一个把“任务单”自动变成“经过审查的 Git 分支”的流水线工具。

它的核心工作方式：你写一个 Markdown 文件描述要做什么（比如“加一个登录 API”），然后运行一条命令，Harness 会驱动 Claude Code 按照固定的 11 个阶段依次执行：写规范 → 写代码 → 跑测试 → 检查类型 → 跑 E2E → 创建 PR。

核心理念： 固定流水线 + 硬性质检门禁

• 固定流水线：每次执行都走相同的阶段（spec → context → build → reconcile → gates → QA → E2E → PR），不会因为任务不同而跳过关键步骤
• 硬性质检门禁：代码必须通过 tsc（TypeScript 类型检查）、eslint（代码风格）、vitest（单元测试）、storybook（组件测试），否则流水线会卡住并自动修复

为什么要叫“Harness”？

“Harness” 这个词的原意是“马具”或“安全带”。这个名字很形象：它像一套“束缚装置”，把 AI 的活动固定在一条可控的轨道上。没有 Harness 时，AI 可能想到哪写到哪；有了 Harness，AI 必须按固定流水线工作，每步都要经过质量检查。

二、Harness 的核心概念

在开始使用之前，你需要理解 3 个核心概念。

1. Task（任务）

Task 是一个 Markdown 文件，放在 harness/tasks/<项目名>/ 目录下。它描述了你想要 AI 完成的一件事。

一个典型的 Task 文件长这样：

---
type: logic
project: my-app
depends: []
---

# Task: 添加用户登录 API

## Acceptance criteria
- POST /api/login 接收 email 和 password
- 密码正确时返回 200 和 JWT token
- 密码错误时返回 401 和错误提示
- 密码错误 3 次后账户锁定 15 分钟

文件头（YAML Front Matter）的字段含义：

字段	含义	可选值
type	任务类型	logic（新功能）、bug（修 Bug）、chore（杂务）
project	属于哪个项目	你定义的任何项目名
depends	依赖哪些其他任务	任务 ID 数组，如 ["1-add-login"]

文件名的格式是固定的：<序号>-<简短描述>.md，例如 1-add-login.md。序号决定了任务的执行顺序。

2. Phase（阶段）

Harness 把整个开发过程拆成了 11 个固定阶段。每个阶段都输出一些产物，供下一阶段使用。

这是完整的阶段顺序：

preflight → spec → context → agentRequest → build → reconcile → gates → QA → e2e → prAssembly → approve

为了方便理解，可以把它们合并成 6 个大步骤：

大步骤	包含的阶段	AI 在做什么
1. 准备	preflight	检查环境、确保分支干净
2. 写规范	spec	阅读 Task，生成详细的实施规范
3. 补充上下文	context、agentRequest	读取项目文档，理解现有代码
4. 写代码	build	按规范写代码
5. 质检	reconcile、gates、QA、e2e	检查矛盾、跑单元测试、跑 E2E 测试
6. 收尾	prAssembly、approve	生成 PR 描述、创建 PR

关键点： 每个阶段失败时，Harness 会自动重试修复（重试次数可在 config.json 中配置）。只有重试用尽仍然失败时，流水线才会停止，等待你的介入。

3. Gate（质量门禁）

Gate 是 Harness 最硬的约束。代码必须通过以下检查，否则流水线不会继续：

• tsc：TypeScript 类型检查，确保没有类型错误
• eslint：代码风格检查，确保符合团队规范
• vitest：单元测试，确保代码逻辑正确
• storybook（React 项目）：组件测试，确保 UI 组件正常

门禁的工作原理：

1. AI 写完代码后，Harness 自动运行这些检查
2. 如果有任何检查失败，Harness 会把错误信息喂给 AI，让它修复
3. AI 修复后，再次运行检查
4. 重复直到通过（默认重试 3 轮）或重试用尽

为什么叫“硬性门禁”？ 因为这些检查不是可选的，不是“建议修复”，而是必须通过。不通过就无法进入下一阶段，更无法创建 PR。

三、安装与初始化（5 分钟）

环境要求

• Node.js ≥ 20（检查：node --version）
• Claude Code CLI（检查：claude --version，安装：npm install -g @anthropic-ai/claude-code）

安装 Harness

# 在你的项目中安装
npm install -D @sweetlemonai/harness-ai

# 或者用 pnpm
pnpm add -D @sweetlemonai/harness-ai

初始化项目

npx harness-ai init --framework react
# 或者如果是 Next.js 项目
npx harness-ai init --framework nextjs

初始化会创建以下文件：

.claude/
  CLAUDE.md              ← 编辑：告诉 AI 这个项目是做什么的
  context/               ← 添加：领域文档（比如业务术语解释）
  standards/
    tech-stack.md        ← 填写：项目允许使用哪些包和版本
harness/
  config.json            ← 配置：覆盖默认设置
  playwright.config.ts   ← E2E 测试配置
  tasks/                 ← 任务存放目录（你写的任务放这里）
.gitignore               ← 自动添加了 runs/、analytics/ 等忽略项

初始化后需要做的三件事：

1. 编辑 .claude/CLAUDE.md：用一两句话描述项目是什么（例如“这是一个电商网站的后台管理系统”）
2. 填写 .claude/standards/tech-stack.md：列出项目允许使用的包和版本（例如 react: 18.2.0，typescript: 5.0.0）
3. （可选）添加领域文档：在 .claude/context/ 下添加你的业务术语表、API 规范等

四、完整工作流：从任务到 PR

第 1 步：写一个 Task

在 harness/tasks/<你的项目名>/ 下创建一个文件，比如 1-add-login.md：

---
type: logic
project: my-app
depends: []
---

# Task: 添加用户登录 API

## Acceptance criteria
- POST /api/login 接收 email 和 password
- 密码正确时返回 200 和 JWT token
- 密码错误时返回 401 和错误提示

项目名是什么？ 就是你初始化时使用的名称，或者你在 harness/tasks/ 下创建的子目录名。如果只有一个项目，通常和仓库名一致。

第 2 步：运行流水线

npx harness-ai ship my-app/1-add-login

ship 命令会触发完整流水线。你会看到类似这样的输出：

▶ Preflight: checking environment
  ✓ Node version 20.10.0
  ✓ Claude Code CLI found
  ✓ Working directory clean

▶ Spec: generating specification
  Agent reading task: 1-add-login.md
  Generating spec... done

▶ Context: loading project standards
  Loaded tech-stack.md
  Loaded CLAUDE.md
  Loaded 3 context files

▶ Build: writing code
  Agent implementing login API... done
  Created: src/api/login.ts
  Created: src/api/__tests__/login.test.ts

▶ Gates: running quality checks
  tsc ... passed
  eslint ... passed
  vitest ... 3 passed, 0 failed
  ✓ All gates passed

▶ E2E: running end-to-end tests
  Playwright: 1 passed, 0 failed

▶ PR: assembling pull request
  Generated PR description
  Created branch: harness/my-app/1-add-login
  Created PR: #42

第 3 步：处理失败

如果某个门禁失败（比如测试没通过），Harness 会：

▶ Gates: running quality checks
  vitest ... 2 passed, 1 failed
  ✗ Gate failed: vitest

▶ Auto-fix attempt 1/3
  Agent fixing tests... done
  vitest ... 3 passed, 0 failed
  ✓ Gate passed after 1 attempt

如果重试用尽仍然失败，流水线会停止，你需要：

1. 查看错误日志：npx harness-ai debug my-app/1-add-login --run <runId>
2. 手动修复问题
3. 继续运行：npx harness-ai run my-app/1-add-login --resume

第 4 步：查看 PR

流水线成功后，Harness 会：

1. 创建一个新分支（命名格式：harness/<项目名>/<任务ID>）
2. 提交所有代码变更
3. 创建 Pull Request，PR 描述自动包含了任务摘要

五、常用命令速查

命令	作用	使用场景
npx harness-ai init --framework react	初始化项目	第一次使用
npx harness-ai ship <任务ID>	完整执行流水线	每天最常用的命令
npx harness-ai run <任务ID> --from build	从指定阶段继续	修复失败后断点续跑
npx harness-ai run <任务ID> --dry-run	预览计划，不执行	检查配置是否正确
npx harness-ai status	查看任务状态	了解当前进度
npx harness-ai debug <任务ID> --run <runId>	调试某次执行	查看 AI 的 prompt 输出和错误日志

任务 ID 格式： <项目名>/<文件名>，例如 my-app/1-add-login。

--from 参数的三种用法

形式	含义	示例
--from <阶段名>	从指定阶段重跑当前任务	--from build
--from <任务ID>	从指定任务开始（项目模式）	--from 2-fix-bug
--from <任务ID>/<阶段名>	从指定任务的指定阶段开始	--from 2-fix-bug/build

阶段名有哪些？ preflight、spec、context、build、gates、QA、e2e、prAssembly 等。

六、配置详解

配置文件位置

Harness 的配置采用“层层叠加”的方式，你只需要写自己要改的部分：

• 包默认配置：node_modules/@sweetlemonai/harness-ai/defaults/config.json（不要改这个）
• 项目覆盖配置：harness/config.json（改这个）
• 本机覆盖配置：harness/config.local.json（不提交 Git，用于个人设置）

最常用的配置项

在 harness/config.json 中写入：

{
  "retries": {
    "agent": 3,      // AI 写代码失败时的重试次数（默认 2）
    "gate": 3,       // 质量门禁失败时的自动修复轮数（默认 3）
    "e2e": 2,        // E2E 测试失败时的重试次数（默认 2）
    "reconcile": 2   // 矛盾检测失败时的修复次数（默认 2）
  },
  "git": {
    "createPR": true  // 是否自动创建 PR（默认 true）
  }
}

新手建议： 初期不需要改任何配置，跑通流程后再根据需要调整 retries.gate（门禁重试次数）即可。

七、最佳实践

1. 任务要拆得足够小

一个 Task 应该是一个开发者 1-2 小时能完成的工作。太大会导致：

• AI 生成的代码太长，容易出错
• 门禁失败时修复困难
• PR 难以审查

好的 Task 示例： “添加登录 API”（只涉及 2-3 个文件）
坏的 Task 示例： “实现整个用户系统”（包含登录、注册、找回密码、个人资料）

2. 充分利用 depends 字段

当多个 Task 有先后顺序时，用 depends 声明依赖：

# 2-add-register.md
---
type: logic
project: my-app
depends: ["1-add-login"]
---

这样 Harness 会先完成 1-add-login，再开始 2-add-register。

3. 填写 tech-stack.md

这是让 AI 不乱用包的关键。模板如下：

# Tech Stack

## Approved packages
- react: 18.2.0
- typescript: 5.0.0
- vitest: 0.34.0

## Prohibited packages
- moment.js (use date-fns instead)
- lodash (use native methods instead)

4. 先把一个简单任务跑通

不要第一次就用 Harness 做复杂功能。先写一个最简单的 Task（比如“添加一个返回 hello world 的 API”），把整个流程跑通，再逐步增加难度。

八、常见问题

Q：Harness 和 Claude Code 的关系是什么？

A：Harness 是一个编排层，它负责按照固定流水线调用 Claude Code。你的代码仍然是 Claude Code 写的，但 Harness 控制它何时写、写什么、写完做什么检查。

Q：ship 和 run 有什么区别？

A：

• ship：完整流水线（preflight → spec → … → approve），适合第一次执行任务
• run：更灵活，可以加 --from 参数从某个阶段继续，适合调试和恢复失败的任务

Q：门禁失败了怎么办？

A：Harness 会自动尝试修复（默认 3 轮）。如果自动修复失败：

1. 运行 npx harness-ai debug <任务ID> --run <runId> 查看错误日志
2. 根据日志手动修复代码
3. 运行 npx harness-ai run <任务ID> --resume 继续

Q：老项目能用吗？

A：可以。但建议先从新模块或独立功能开始试点。

1. 先跑 init 初始化
2. 填写 tech-stack.md（列出项目已有的主要依赖）
3. 写第一个 Task 时，在 context/ 中添加相关现有模块的说明文档

Q：不想自动创建 PR？

A：在 harness/config.json 中设置 "git": { "createPR": false }。流水线会停在最后一步，让你手动创建 PR。

九、总结

Harness 是什么？ 一个把“任务单”自动变成“经过审查的 Git 分支”的流水线工具。

它的核心价值：

你不需要手动做的事	Harness 自动做了
创建分支	✓ 自动创建 harness/项目名/任务ID 分支
写 PR 描述	✓ 自动从 Task 文件生成描述
跑类型检查	✓ 自动运行 tsc
跑代码风格检查	✓ 自动运行 eslint
跑单元测试	✓ 自动运行 vitest
跑 E2E 测试	✓ 自动运行 Playwright
修复简单的检查失败	✓ 自动重试修复（默认 3 轮）
创建 PR	✓ 自动创建

一个 Task 文件 + 一条命令 = 一个自动化的开发周期。

这个模式特别适合：

• 你清楚要做什么，但不想盯着 AI 一步步执行
• 你对代码质量有要求（类型、测试、风格都要过）
• 你想把“让 AI 写代码”这件事自动化、可重复

三句话总结：

1. 写一个 Task：用 Markdown 描述你要做什么
2. 运行 harness ship：让流水线自动跑完 11 个阶段
3. 审查 PR：代码已经写好、测试已过、PR 已创建，你只需要审查