# Harness Workflow：AI 编程助手的工作流管理脚手架

> Harness Workflow 是一个面向 Codex、Claude Code、Qoder 等 AI 编程助手的 Harness Engineering 工作流脚手架，通过版本管理和结构化协作流程提升 AI 辅助开发的效率。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-04-09T03:40:31.000Z
- 最近活动: 2026-04-09T03:51:11.035Z
- 热度: 161.8
- 关键词: Harness Workflow, AI编程助手, 工作流管理, Codex, Claude Code, Qoder, 软件开发, 版本管理, 回归诊断
- 页面链接: https://www.zingnex.cn/forum/thread/harness-workflow-ai
- Canonical: https://www.zingnex.cn/forum/thread/harness-workflow-ai
- Markdown 来源: ingested_event

---

## 背景：AI 编程助手的工作流挑战

随着 Codex、Claude Code、Qoder 等 AI 编程助手的普及，开发者与 AI 的协作方式正在发生根本性变化。然而，这种协作也面临着新的挑战：

- **上下文管理困难**：AI 助手在长时间对话中容易丢失关键上下文
- **工作进度难以追踪**：缺乏系统化的方式来记录需求、变更和计划
- **多智能体协作混乱**：不同 AI 助手之间缺乏统一的协作规范
- **回归问题难以管理**：当实现效果不达标时，缺乏系统化的诊断流程

Harness Workflow 正是为解决这些问题而设计的工程化工作流框架。

## 什么是 Harness Engineering

Harness Engineering 是一种将 AI 编程助手纳入软件开发流程的工程方法论。其核心思想是：

> 不是让 AI 直接替开发者完成所有工作，而是通过结构化的工作流，让 AI 在正确的时机做正确的事情，并在关键节点停下来等待人工确认。

Harness Workflow 提供了实现这一方法论的具体工具和约定。

## 核心架构：四层能力模型

Harness Workflow 提供了四层能力，从全局到项目级逐步深入：

### 第一层：全局 CLI

安装后可直接使用 `harness` 命令，提供跨项目的统一入口：

```bash
pipx install git+https://github.com/togally/harness-workflow.git
```

### 第二层：三端项目级 Skill

`harness install` 会同时在三个主流 AI 编程助手的 skill 目录中安装工作流支持：

- `.codex/skills/harness`（Codex）
- `.claude/skills/harness`（Claude Code）
- `.qoder/skills/harness`（Qoder）

### 第三层：命令级提示入口

为常用操作生成独立的命令入口：

- `install`、`init`、`update`：环境管理
- `version`、`language`：配置管理
- `requirement`、`change`、`plan`：工作流核心
- `next`、`ff`、`regression`：执行控制
- `archive`、`rename`、`status`：状态管理

### 第四层：版本主容器工作流

`version` 是 requirement、change、plan 的主工作容器，所有工作都在特定版本的上下文中进行。

## 工作流核心概念

### Version（版本）

Version 是主工作容器，所有需求、变更和计划都归属于特定的版本：

```bash
harness version "v1.0.0"
```

### Requirement（需求）

Requirement 代表一个完整的功能需求或用户故事：

```bash
harness requirement "在线健康服务"
```

### Change（变更）

Change 是完成需求的具体工作项，可以独立存在，也可以关联到特定需求：

```bash
harness change "在线问诊预约" --requirement "在线健康服务"
harness change "修复登录按钮样式"  # 独立变更
```

### Plan（计划）

Plan 是变更的具体执行计划：

```bash
harness plan "在线问诊预约"
```

## 规则驱动的协作流程

Harness Workflow 通过以下文件驱动协作：

### workflow-runtime.yaml

记录当前工作状态：

```yaml
current_version: v1.0.0
stage: ready_for_execution
current_task: 在线问诊预约
next_action: 等待人工确认
```

### version meta.yaml

每个版本的元数据文件，记录：

- `stage`：当前阶段
- `current_task`：当前任务
- `next_action`：下一步动作
- `suggested_skill`：建议使用的 skill
- `assistant_prompt`：给 AI 助手的提示
- `approval_required`：是否需要人工确认

### development-flow.md

定义开发流程的规则文档，包括阶段转换条件和验收标准。

## 阶段与建议 Skill 的映射

Harness Workflow 预定义了以下阶段映射：

| 阶段 | 建议 Skill | 说明 |
|------|-----------|------|
| requirement_review | brainstorming | 需求评审阶段 |
| changes_review | brainstorming | 变更评审阶段 |
| plan_review | writing-plans | 计划评审阶段 |
| ready_for_execution | - | 等待人工确认，不自动执行 |
| executing | executing-plans | 执行阶段 |
| done | verification-before-completion | 完成前验证 |

## 回归诊断流程

当智能体完成开发但效果不达标，或用户对实现方向有疑问时，Harness Workflow 提供了系统化的回归诊断流程：

### 启动回归诊断

```bash
harness regression "按钮交互动效不符合预期"
```

### 诊断流程

1. **问题确认阶段**：与用户收敛"不满意点"与预期行为
2. **问题判断**：判断是否是真问题
3. **问题转换**：如果确认是问题，转成新的 change 或 requirement
4. **重新进入流程**：按正常流程执行修复
5. **经验沉淀**：修复完成后，沉淀经验到经验库

### 回归诊断的优势

- 避免盲目返工
- 确保问题被正确理解和定义
- 积累可复用的诊断经验
- 保持工作流的完整性

## 验收标准与质量门禁

Harness Workflow 在每个阶段都设置了明确的质量门禁：

### Change 完成标准

- 必须执行并记录 `mvn compile`（Java 项目）
- 编译失败必须先进入 regression 流程

### Requirement 完成标准

- 必须执行并记录项目启动测试成功
- 启动失败必须先进入 regression 流程

### 质量门禁的意义

这些看似严格的标准实际上保护了开发者和 AI 助手：

- 确保基础质量不被妥协
- 强制在问题早期被发现和处理
- 建立可追踪的质量记录

## 多智能体协作的统一入口

Harness Workflow 通过 `AGENTS.md` 提供跨智能体的共享入口，确保不同 AI 助手（Codex、Claude Code、Qoder）都能理解并遵循相同的工作流。

同时，每个智能体还有自己的专属入口：

- **Codex**：`.codex/skills/harness-*/SKILL.md`
- **Claude Code**：`.claude/commands/harness-*.md`
- **Qoder**：`.qoder/commands/harness-*.md` 和 `.qoder/rules/harness-workflow.md`

## 会话模式管理

Harness Workflow 引入了"会话模式"的概念：

```bash
harness enter  # 进入当前 workflow 节点对应的 harness 会话模式
harness exit   # 退出 harness 会话模式
```

在会话模式下，对话必须持续受当前锁定的 version/stage/节点约束，直到显式执行 `harness exit`。这确保了 AI 助手始终在当前工作流的上下文中工作，避免上下文漂移。

## 实际应用示例

### 完整的开发流程

```bash
# 1. 创建版本
harness version "v1.0.0"

# 2. 创建需求
harness requirement "在线健康服务"

# 3. 创建关联的变更
harness change "在线问诊预约" --requirement "在线健康服务"
harness change "健康档案管理" --requirement "在线健康服务"

# 4. 为变更制定计划
harness plan "在线问诊预约"

# 5. 推进工作流
harness next

# 6. 快速跳过中间讨论，直接到执行前确认
harness ff

# 7. 确认执行
harness next --execute

# 8. 查看状态
harness status
```

### 回归诊断示例

```bash
# 发现问题
harness regression "按钮交互动效不符合预期"

# 确认是真问题后，转成新的变更
harness regression --change "优化按钮交互反馈"

# 继续正常流程
harness plan "优化按钮交互反馈"
```

## 总结与展望

Harness Workflow 代表了 AI 辅助软件开发的一种工程化尝试。它通过版本管理、结构化协作流程和回归诊断机制，为 AI 编程助手提供了清晰的工作边界和质量保障。

随着 AI 编程助手能力的不断提升，类似 Harness Workflow 这样的工作流框架将变得越来越重要。它们不仅帮助开发者更好地利用 AI 的能力，也为 AI 助手提供了清晰的上下文和约束，使协作更加高效和可靠。