Harness Engineering — 编码工作流体系

"如果它不能被机械化地执行，Agent 就会偏离。"

核心理念

Harness Engineering 是一套项目约束体系，用于规范化 AI 辅助编程流程。核心原则：

1. Generator ≠ Evaluator — 写代码的 Agent 和审代码的 Agent 必须分开
2. 质量门禁 — 每个阶段必须通过检查才能进入下一阶段
3. 变更审计链 — 每次需求都有完整的规划 → 编码 → 评审 → 交付记录
4. 工程化纠错 — 每发现一个错误，就消除它再次发生的可能性

项目结构

每个使用 Harness 的项目，根目录下有 .harness/ 目录：

project/
├── .harness/
│   ├── rules/              # 编码规范、工作流、质量门禁（始终加载）
│   │   ├── quality-gates.md  # 各阶段门禁标准
│   │   └── \x3Cproject>-rules.md # 项目特定规则
│   ├── skills/             # 可复用 SOP（如 evaluator.md 独立评审）
│   ├── wiki/               # 项目知识库（按需查询）
│   ├── changes/            # 变更审计链（每次需求自动创建）
│   │   └── {type}-{name}-{date}/
│   │       ├── planning/
│   │       │   ├── spec.md   # 需求规格
│   │       │   └── tasks.md  # 任务拆分清单
│   │       ├── review/
│   │       │   ├── code_review_v1.md  # Evaluator 评审报告
│   │       │   └── revision_report.md # Generator 修复报告
│   │       └── summary.md    # 变更摘要（SSOT）
│   └── agents/
│       └── project-agent.md  # Agent Index & Map（启动必读）
└── ...

变更目录命名规则

.harness/changes/{type}-{简述}-{日期}/

• type: feat | fix | refactor | chore | docs
• 简述: 短横线分隔的英文描述
• 日期: YYYYMMDD 格式

五阶段工作流

规划 → 评审 → 编码 → 自审 → 独立评审 → 修复 → 交付

阶段 1：规划（Planning）

Generator Agent 负责：

1. 需求规格（planning/spec.md）
   • 目标、范围、验收标准、非目标
2. 任务拆分（planning/tasks.md）
   • 每个任务：描述、输入、输出、验收标准
3. 变更摘要（summary.md）
   • 基本信息表、阶段状态表

质量门禁：

• spec.md 包含目标、范围、验收标准
• tasks.md 每个任务有明确的输入/输出/验收标准
• summary.md 已创建并填入基本信息

阶段 2：编码（Coding）

Generator Agent 按 tasks.md 逐条实现：

1. 先读现有代码，理解模式
2. 写代码前说明计划（改什么、为什么、风险）
3. 完成后产出 coding_report.md
4. 完成 self_review.md 自查

质量门禁：

• 每个任务都有对应的代码实现
• 自审 checklist 全部通过
• 没有遗漏文件、破损 import、未测试路径

阶段 3：独立评审（Review）

关键：必须用不同的 Agent（Evaluator）评审 Generator 的产出。

Evaluator Agent 负责：

1. 读取 spec.md、tasks.md 理解需求
2. 审查 Generator 的代码改动
3. 产出 review/code_review_v1.md，问题分级：

质量门禁：

• 所有 MUST FIX 问题必须修复
• SHOULD FIX 问题需说明不修复的理由
• 健康检查/API 测试通过

阶段 4：修复（Revision）

Generator Agent 根据评审报告修复：

1. 逐条修复 MUST FIX 和 SHOULD FIX 问题
2. 产出 review/revision_report.md，说明每个问题的修复方案
3. 最多 2 轮修复循环

质量门禁：

• 所有 MUST FIX 已修复并验证
• revision_report.md 逐条对应评审意见
• 健康检查再次通过

阶段 5：交付（Delivery）

1. Evaluator 确认修复通过 → 状态改为 APPROVED
2. Generator 执行 git commit + push
3. 更新 summary.md 为 DELIVERED 状态
4. 向用户报告交付结果

Dispatch Routing — 任务分级

根据任务复杂度选择不同流程：

决策启发式

\x3C10 行代码？ → SIMPLE
多文件但方案明显？ → MEDIUM
用户指定了 skill（/qa, /review）？ → HEAVY
功能/项目/目标（不是任务）？ → FULL
用户只想规划不想实现？ → PLAN

gstack-lite 规划纪律

注入到所有编码 Agent 的基础纪律：

# gstack-lite Planning Discipline

1. Read every file you will modify. Understand existing patterns first.
2. Before writing code, state your plan: what, why, which files, test case, risk.
3. When ambiguous, prefer:
   - completeness over shortcuts
   - existing patterns over new ones
   - reversible choices over irreversible ones
   - safe defaults over clever ones
4. Self-review your changes before reporting done.
   Check for: missed files, broken imports, untested paths, style inconsistencies.
5. Report when done: what shipped, what decisions you made, anything uncertain.

模板文件

spec.md 模板

# 需求规格：{功能名}

## 目标
{一句话描述要实现什么}

## 范围

### 包含
- {功能点 1}
- {功能点 2}

### 不包含
- {明确排除的内容}

## 验收标准
1. {可验证的标准 1}
2. {可验证的标准 2}

## 非目标
- {不在此范围内的内容}

tasks.md 模板

# 任务拆分清单

## Task 1: {任务名}

- **描述**: {具体做什么}
- **输入**: {依赖什么}
- **输出**: {产出什么文件/功能}
- **验收标准**:
  - {可验证的检查点 1}
  - {可验证的检查点 2}

summary.md 模板

# {type}-{name} — 变更摘要

> Single Source of Truth for this change.
> 创建时间: YYYY-MM-DD
> 状态: PLANNING | CODING | IN_REVIEW | FIXED | DELIVERED

## 基本信息

| 字段 | 值 |
|------|-----|
| 类型 | feat/fix/refactor/chore/docs |
| 需求描述 | {一句话} |
| 负责人 | Generator Agent + Evaluator Agent |
| 创建时间 | {时间} |
| 最后更新 | {时间} |

## 阶段状态

| 阶段 | 状态 | 完成时间 | 备注 |
|------|------|---------|------|
| 1. 规划 | ⏳ 进行中 | — | — |
| 2. 评审 | ⏸ 待开始 | — | — |
| 3. 编码 | ⏸ 待开始 | — | — |
| 4. 自审 | ⏸ 待开始 | — | — |
| 5. 独立评审 | ⏸ 待开始 | — | — |
| 6. 修复 | ⏸ 待开始 | — | — |
| 7. 交付 | ⏸ 待开始 | — | — |

code_review.md 模板

# 代码评审报告 v1

**评审对象**: {功能名}
**评审时间**: YYYY-MM-DD
**评审 Agent**: 独立 Code Reviewer

## 评审结论

**状态**: APPROVED | REVISION_REQUIRED

## 发现的问题

### 问题 N: {问题标题}

- **严重程度**: MUST FIX / SHOULD FIX / LOW / INFO
- **位置**: `文件路径` — 描述
- **描述**: {问题说明}
- **当前代码**:
  ```{language}
  {当前代码}

• 建议:

  {建议代码}
  

### revision_report.md 模板

```markdown
# Revision Report v2

**日期**: YYYY-MM-DD
**作者**: Generator Agent
**评审版本**: code_review_v1.md

## 修复摘要

根据 Evaluator Agent 的评审报告，共修复 **N 个问题**。

## 🔴 MUST FIX 修复

### 1. {问题标题}

**影响文件**:
- `path/to/file1`
- `path/to/file2`

**修复方案**: {说明}

**为什么选择这个方案**: {理由}

核心原则详解

1. Generator ≠ Evaluator

• Generator Agent：负责规划、编码、自审、修复
• Evaluator Agent：负责独立评审，发现 Generator 遗漏的问题
• 为什么分开：Generator 会对自己写的代码有盲点；独立的 Evaluator 能发现安全隐患、边界情况等

2. 质量门禁

每个阶段必须满足门禁标准才能进入下一阶段。不允许跳过门禁。

3. 变更审计链

每次需求都创建 .harness/changes/{type}-{name}-{date}/ 目录，包含：

• 规划文档（spec + tasks）
• 评审报告（code_review + revision_report）
• 变更摘要（summary.md = SSOT）

4. 工程化纠错

"每发现一个错误，就工程化地消除它再次发生的可能性。"

• 不只是修复 bug，而是修复产生 bug 的流程
• 例如：发现 XSS → 不只是修一处，而是添加 escapeHtml 工具函数并更新规则

使用方式

当用户要求执行编程任务时：

1. 判断任务级别（SIMPLE/MEDIUM/HEAVY/FULL/PLAN）
2. 创建变更目录（MEDIUM 及以上）
3. 按工作流执行
4. 每个阶段检查质量门禁
5. 交付后更新 summary.md

简单任务（SIMPLE）

直接执行，不需要创建变更目录和走完整流程。

中等任务（MEDIUM）

1. 创建变更目录
2. 写 planning/spec.md + planning/tasks.md
3. 编码 + 自审
4. 更新 summary.md

完整任务（FULL）

1. 创建变更目录
2. Generator Agent: spec.md + tasks.md
3. Generator Agent: 编码 + coding_report.md + self_review.md
4. Evaluator Agent: code_review_v1.md
5. 如果有 MUST FIX → Generator Agent 修复 → revision_report.md
6. Evaluator Agent: 确认通过
7. git commit + push
8. 更新 summary.md

轻量级变体：网站项目

对于单文件 HTML 网站等简单项目，使用轻量流程：

规划（3 个问题）→ 实施+自审 → 交付（git commit + 报告）

详见 .harness/rules/website-workflow.md。

常见错误

❌ 错误：Generator 自己评审自己的代码

正确做法：spawn 新的 Agent 作为 Evaluator

❌ 错误：跳过规划直接编码

正确做法：MEDIUM 及以上任务必须先写 spec.md

❌ 错误：评审报告没有分级

正确做法：必须按 MUST FIX / SHOULD FIX / LOW / INFO 分级

❌ 错误：修复后不验证

正确做法：修复后必须重新运行健康检查

❌ 错误：summary.md 不更新

正确做法：每个阶段完成后更新 summary.md 的阶段状态表

与其他 gstack 技能的关系

Harness Engineering 是工作流编排层，gstack 是方法论层：