Skill: cindypapa/openclaw-harness-engineering (version 1.0.0)

--- name: harness-engineering description: "Harness Engineering — Generator/Evaluator 双 Agent 编码工作流。用于任何需要规划、编码、评审、质量门禁的编程任务。将做事的 Agent 和评判的 Agent 分开，每个阶段通过质量门禁才能进入下一阶段。" --- # Harness Engineering — 编码工作流体系 > "如果它不能被机械化地执行，Agent 就会偏离。" ## 核心理念 Harness Engineering 是一套**项目约束体系**，用于规范化 AI 辅助编程流程。核心原则： 1. **Generator ≠ Evaluator** — 写代码的 Agent 和审代码的 Agent 必须分开 2. **质量门禁** — 每个阶段必须通过检查才能进入下一阶段 3. **变更审计链** — 每次需求都有完整的规划 → 编码 → 评审 → 交付记录 4. **工程化纠错** — 每发现一个错误，就消除它再次发生的可能性 --- ## 项目结构 每个使用 Harness 的项目，根目录下有 `.harness/` 目录： ``` project/ ├── .harness/ │ ├── rules/ # 编码规范、工作流、质量门禁（始终加载） │ │ ├── quality-gates.md # 各阶段门禁标准 │ │ └── <project>-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** | 边界情况、可维护性问题 | 强烈建议修复 | | **LOW** | 代码风格、小优化 | 建议修复 | | **INFO** | 观察、建议、未来改进 | 记录即可 | **质量门禁**： - [ ] 所有 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 — 任务分级 根据任务复杂度选择不同流程： | 级别 | 判断标准 | 流程 | |------|---------|------| | **SIMPLE** | <10 行代码，单文件 | 直接 spawn 执行 | | **MEDIUM** | 多文件，方案明确 | gstack-lite（规划 + 自审） | | **HEAVY** | 需要特定方法论 | 运行对应 gstack skill | | **FULL** | 完整功能，多日工作量 | 双 Agent（Generator + Evaluator） | | **PLAN** | 先规划后实现 | 只产出计划，不写代码 | ### 决策启发式 ``` <10 行代码？ → SIMPLE 多文件但方案明显？ → MEDIUM 用户指定了 skill（/qa, /review）？ → HEAVY 功能/项目/目标（不是任务）？ → FULL 用户只想规划不想实现？ → PLAN ``` --- ## gstack-lite 规划纪律 注入到所有编码 Agent 的基础纪律： ```markdown # 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 模板 ```markdown # 需求规格：{功能名} ## 目标 {一句话描述要实现什么} ## 范围 ### 包含 - {功能点 1} - {功能点 2} ### 不包含 - {明确排除的内容} ## 验收标准 1. {可验证的标准 1} 2. {可验证的标准 2} ## 非目标 - {不在此范围内的内容} ``` ### tasks.md 模板 ```markdown # 任务拆分清单 ## Task 1: {任务名} - **描述**: {具体做什么} - **输入**: {依赖什么} - **输出**: {产出什么文件/功能} - **验收标准**: - {可验证的检查点 1} - {可验证的检查点 2} ``` ### summary.md 模板 ```markdown # {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 模板 ```markdown # 代码评审报告 v1 **评审对象**: {功能名} **评审时间**: YYYY-MM-DD **评审 Agent**: 独立 Code Reviewer ## 评审结论 **状态**: APPROVED | REVISION_REQUIRED ## 发现的问题 ### 问题 N: {问题标题} - **严重程度**: MUST FIX / SHOULD FIX / LOW / INFO - **位置**: `文件路径` — 描述 - **描述**: {问题说明} - **当前代码**: ```{language} {当前代码} ``` - **建议**: ```{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 是**方法论层**： | gstack 技能 | 用途 | 在 Harness 中的位置 | |------------|------|-------------------| | `gstack-openclaw-office-hours` | 产品思考、需求分析 | 阶段 1（规划）前可选 | | `gstack-openclaw-ceo-review` | 战略挑战、范围审查 | 阶段 1 完成后可选 | | gstack-lite/full | 规划纪律、编码流程 | 嵌入阶段 2-3 | | `gstack-openclaw-investigate` | 系统化调试 | 阶段 4 发现问题时使用 | | `gstack-openclaw-retro` | 工程回顾 | 交付后复盘 |

path: _meta.json
content: name: harness-engineering
version: 1.0.0
description: Generator/Evaluator dual-agent coding workflow with quality gates and change audit chain
license: MIT

path: rules/project-rules.md
content: # {项目名} — 编码规则

> 项目特定的编码规范和约束。

---

## 1. 通用规则

- [ ] 修改前必须读现有代码，理解模式
- [ ] 每次改动只做一个事
- [ ] 代码风格与现有代码保持一致

## 2. 项目规则

{在此添加项目特定的规则}

## 3. 自审 Checklist

{在此添加项目特定的自审检查项}


path: rules/website-workflow.md
content: # {项目名} — 轻量工作流

> 适用于简单项目（单文件 HTML、配置文件等）。
> 3 步流程：规划 → 实施+自审 → 交付

---

## 流程

```
规划（说清楚改什么）→ 实施+自审（改完自查）→ 交付（git commit + 报告）
```

### 第 1 步：规划

收到改动需求后，先回答 3 个问题：

1. **改哪里**：涉及哪个/哪些文件？
2. **改什么**：具体要做什么改动？
3. **风险点**：可能影响哪些现有功能？

得到确认后进入第 2 步。

### 第 2 步：实施 + 自审

修改完成后，运行自审 Checklist。

### 第 3 步：交付

- git commit（语义化提交：type: 描述）
- 报告：改了什么、在哪里、效果如何

---

## 变更目录（可选）

对于较大改动：

```
.harness/changes/{type}-{简述}-{日期}/
└── summary.md    # 一句话记录：改了什么、为什么
```

对于小改动，直接 git commit 即可。


path: skills/evaluator.md
content: # Evaluator — 独立代码评审 SOP

> 作为独立的 Evaluator Agent，评审 Generator Agent 的产出。
> 你不是来挑刺的，你是来确保交付质量的。

---

## 评审流程

### 1. 理解需求

读取以下文件，理解需求背景：

- `.harness/changes/.../planning/spec.md` — 需求规格
- `.harness/changes/.../planning/tasks.md` — 任务拆分清单
- `.harness/changes/.../summary.md` — 变更摘要

### 2. 审查代码

- 检查 Generator 修改/新增的每个文件
- 对照 tasks.md 的验收标准逐条验证
- 运行健康检查 / API 测试（如适用）

### 3. 产出评审报告

写入 `.harness/changes/.../review/code_review_v1.md`

### 4. 给出结论

**APPROVED** — 所有检查通过，可以交付

**REVISION_REQUIRED** — 有需要修复的问题，返回 Generator 修复

---

## 问题分级

| 级别 | 何时使用 | 示例 |
|------|---------|------|
| **MUST FIX** | 安全漏洞、功能缺失、数据损坏 | XSS、SQL 注入、核心功能未实现 |
| **SHOULD FIX** | 边界情况、可维护性 | 未处理的异常、重复代码 |
| **LOW** | 代码风格、小优化 | 命名不规范、缺少注释 |
| **INFO** | 观察、建议 | "建议后续添加日志" |

---

## 评审 Checklist

### 安全性
- [ ] 无 XSS 漏洞（用户输入必须转义）
- [ ] 无 SQL 注入（参数化查询或白名单）
- [ ] 无命令注入
- [ ] 文件上传有类型限制
- [ ] 敏感信息未硬编码

### 功能完整性
- [ ] 每个任务都有对应实现
- [ ] 验收标准全部满足
- [ ] 错误处理完整

### 代码质量
- [ ] 与现有代码风格一致
- [ ] 无重复代码
- [ ] 命名清晰
- [ ] 无死代码/注释代码

### 健壮性
- [ ] 边界情况已处理
- [ ] 异常已捕获
- [ ] 超时/重试机制（如适用）
- [ ] 日志记录充分

---

## 评审报告格式

```markdown
# 代码评审报告 v{版本号}

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

## 评审结论

**状态**: APPROVED | REVISION_REQUIRED

## 发现的问题

### 问题 N: {标题}
- **严重程度**: {级别}
- **位置**: `文件路径`
- **描述**: ...
- **建议**: ...
```


path: templates/code_review.md
content: # 代码评审报告 v1

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

## 评审结论

**状态**: APPROVED | REVISION_REQUIRED

---

## 发现的问题

### 问题 1: {问题标题}

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

### 问题 2: {问题标题}

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


path: templates/quality-gates.md
content: # 质量门禁

> 每个阶段必须通过对应门禁才能进入下一阶段。

---

## 阶段 1 → 2：规划门禁

- [ ] spec.md 包含目标、范围、验收标准
- [ ] spec.md 明确排除非目标
- [ ] tasks.md 每个任务有描述、输入、输出、验收标准
- [ ] summary.md 已创建并填入基本信息表
- [ ] 变更目录命名符合 `{type}-{name}-{date}` 格式

## 阶段 2 → 3：编码门禁

- [ ] 每个任务都有对应的代码实现
- [ ] 已读取并理解现有代码模式
- [ ] coding_report.md 已产出
- [ ] self_review.md 所有检查项通过

## 阶段 3 → 4：独立评审门禁

- [ ] Evaluator 是独立的 Agent（不是 Generator）
- [ ] code_review.md 问题已分级（MUST FIX / SHOULD FIX / LOW / INFO）
- [ ] 每个问题有位置、描述、当前代码、建议
- [ ] 健康检查/API 测试通过

## 阶段 4 → 5：修复门禁

- [ ] 所有 MUST FIX 问题已修复
- [ ] SHOULD FIX 问题已修复或说明不修复理由
- [ ] revision_report.md 逐条对应评审意见
- [ ] 健康检查再次通过

## 阶段 5 → 交付：交付门禁

- [ ] Evaluator 确认修复通过（状态 APPROVED）
- [ ] git commit 已执行
- [ ] summary.md 状态更新为 DELIVERED
- [ ] 用户已收到交付报告

---

## 问题分级定义

| 级别 | 含义 | 处理要求 |
|------|------|---------|
| **MUST FIX** | 安全漏洞、功能缺陷、数据损坏 | 必须修复，否则不能交付 |
| **SHOULD FIX** | 边界情况、可维护性问题 | 强烈建议修复，不修复需说明理由 |
| **LOW** | 代码风格、小优化 | 建议修复 |
| **INFO** | 观察、建议、未来改进 | 记录即可 |


path: templates/revision_report.md
content: # Revision Report v{版本号}

**日期**: YYYY-MM-DD
**作者**: Generator Agent
**评审版本**: code_review_v{版本号-1}.md

## 修复摘要

根据 Evaluator Agent 的评审报告，共修复 **N 个问题**（X 个 MUST FIX + Y 个 LOW/INFO）。

---

## 🔴 MUST FIX 修复

### 1. {问题标题}

**影响文件**:
- `path/to/file`

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

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

---

## 🟡 LOW/INFO 修复

### N. {问题标题}

**影响文件**:
- `path/to/file`

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

**未修复的原因**: {如选择不修复，说明理由}


path: templates/spec.md
content: # 需求规格：{功能名}

## 目标

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

## 范围

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

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

## 验收标准

1. {可验证的标准 1}
2. {可验证的标准 2}
3. {可验证的标准 3}

## 非目标

- {不在此范围内的内容}

## 技术约束

- {技术限制或依赖}


path: templates/summary.md
content: # {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 |
| 创建时间 | {YYYY-MM-DD HH:MM} |
| 最后更新 | {YYYY-MM-DD HH:MM} |

## 阶段状态

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

## 评审记录

| 轮次 | 类型 | 状态 | 关键意见 |
|------|------|------|---------|
| v1 | 代码评审 | — | — |

## 最终交付物

```
{文件树}
```

## 例外情况

{如有跳过的门禁或特殊情况，在此说明}

## 已知问题

- {已知但未修复的问题}


path: templates/tasks.md
content: # 任务拆分清单

## Task 1: {任务名}

- **描述**: {具体做什么}
- **输入**: {依赖什么}
- **输出**: `path/to/output`
- **验收标准**:
  - {可验证的检查点 1}
  - {可验证的检查点 2}

## Task 2: {任务名}

- **描述**: {具体做什么}
- **输入**: {依赖什么}
- **输出**: `path/to/output`
- **验收标准**:
  - {可验证的检查点 1}


path: wiki/project-wiki.md
content: # 项目知识库

> 按需查询，记录项目特定的技术决策、架构说明、常见问题。

---

## 技术栈

{描述项目使用的技术栈}

## 架构决策

{记录重要的架构决策及原因}

## 常见问题

{记录开发过程中遇到的常见问题及解决方案}


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)