# harness

**Repository Path**: dont-touch-my-code/harness

## Basic Information

- **Project Name**: harness
- **Description**: harness引擎使用以及规范沉淀
- **Primary Language**: Python
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 3
- **Created**: 2026-06-11
- **Last Updated**: 2026-09-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Harness Engine - AI 驱动的开发工作流引擎

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

> **AI 驱动的智能开发工作流** - 通过专业智能体协作、标准化文档模板、自动化脚本和度量指标,实现高质量、可追踪的软件交付。

> 🔌 **openspec 依赖**：本工程依赖 OpenSpec CLI **≥ 1.4.1**（`npm i -g @fission-ai/openspec`，兼容 ≥1.4.1、实测 1.10.0）。
> 变更生命周期（创建/列表/校验/归档）由统一 CLI `python .harness/scripts/harness.py spec-*` 包装 openspec 实现，
> 工件落在 `openspec/changes/<name>/`；harness 增强层（质量门禁/事件/指标）保留叠加。
> 历史 `.harness/change/archive/` 原地只读保留。完整命令清单见 `.harness/scripts/SCRIPTS.md` 与 `harness.py --list`。

---

## 📖 目录

- [快速开始](#-快速开始)
- [核心特性](#-核心特性)
- [工作流程](#-工作流程)
- [使用案例](#-使用案例)
- [目录结构](#-目录结构)
- [智能体团队](#-智能体团队)
- [文档模板](#-文档模板)
- [自动化脚本](#-自动化脚本)
- [度量指标](#-度量指标)
- [最佳实践](#-最佳实践)
- [常见问题](#-常见问题)

---

## 🚀 快速开始

### 1. 理解 Harness 是什么

Harness 是一个 **AI 驱动的开发工作流引擎**,通过以下方式提升开发效率和质量:

- 🤖 **专业智能体协作** - 4 个核心专业 AI 智能体,各司其职
- 📋 **标准化文档模板** - proposal/design/tasks + review/verification 报告模板,确保一致性
- 🛠️ **自动化脚本** - 变更生命周期（spec-create/archive 等）与度量收集,全流程自动化
- 📊 **度量指标追踪** - 变更周期、文档完整度、首次通过率、Bug 逃逸率、返工率等核心指标,持续改进流程

### 2. 如何使用 (3 步开始)

#### 步骤 1: 向项目经理描述需求

**示例提示词**:

```
我想添加一个用户认证功能,支持邮箱注册、登录、密码重置。
要求:
- 用户使用邮箱和密码注册
- 登录成功后返回 JWT token
- 支持密码重置邮件
- 需要防止暴力破解
```

#### 步骤 2: 项目经理自动协调

项目经理会:
1. ✅ 分析需求复杂度
2. ✅ 创建变更目录 (`spec-create`)
3. ✅ 直产 proposal（gate-1 自检 + validate ≥80）
4. ✅ 用户确认门（proposal + gate-1 + validate ≥80 后暂停等待用户确认，确认后继续；确认前不进入实现）
5. ✅ 分派给开发智能体
6. ✅ 测试验证
7. ✅ 代码审查（含合规 + 安全透镜）
8. ✅ 归档完成 (`spec-archive`)

#### 步骤 3: 等待完成报告

你会收到:
- 📊 完整的变更摘要
- 📁 归档的文档链接
- ✅ 测试报告
- 🔍 审查报告

### 3. 第一个任务 (实战演练)

**你的提示词**:
```
我想添加一个 CSV 导出功能,可以导出用户列表为 CSV 文件。
```

**Harness 会自动完成**:
1. 创建 `openspec/changes/csv-export/` 目录（`spec-create`）
2. 生成 `proposal.md`（需求提案，经用户确认门）
3. 生成 `tasks.md`（任务文档；design.md 仅 complex/critical 才产出）
4. 实现代码
5. 编写测试
6. 运行验证
7. 代码审查
8. 归档到 `openspec/changes/archive/`（`spec-archive`）

**你可以**:
- 在每个阶段查看文档
- 提出修改意见
- 追踪进度

---

## ✨ 核心特性

### 1. 智能体协作系统

| 智能体 | 职责 | 触发条件 |
|--------|------|----------|
| 🎯 **项目经理** | 任务入口、直产 proposal、决策、协调 | 所有任务的唯一入口 |
| 💻 **代码开发** | 设计（complex/critical）、编码 | proposal 确认后 |
| 🧪 **测试执行** | 单元/集成测试、验证 | 代码开发完成 |
| 🔍 **代码审查** | 质量、安全、合规审查（高危触发 dual-review 双盲审） | 测试通过后 |

> 原「需求分析 / 安全审计 / 质量审查」角色已吸收：需求分析并入项目经理（直产 proposal），
> 安全与合规透镜并入 code-reviewer 审查（详见下方智能体团队与 code-reviewer 双盲审章节）。

### 2. 标准化文档模板

proposal / design / tasks 模板已交给 openspec（项目级覆盖模板在
`openspec/schemas/spec-driven/templates/`）；harness 仅保留 verdict/评分类模板
（review-report / verification-report，位于 `.harness/templates/`）：

- 🔍 [review-report.md](.harness/templates/review-report.md) - 审查报告
- ✅ [verification-report.md](.harness/templates/verification-report.md) - 验证报告

### 3. 自动化脚本库

| 命令 | 功能 |
|------|------|
| `harness.py spec-create` | 创建 openspec 变更 + worktree + 事件 + 基线 |
| `harness.py spec-list` / `spec-show` | 纯透传 openspec list / show |
| `harness.py spec-validate` | harness verdict/评分门禁 + openspec validate |
| `harness.py spec-archive` | harness 前置门禁 + openspec archive |
| `harness.py metrics` | 收集度量指标 |

> 主链命令一览，完整命令集见 `python .harness/scripts/harness.py --list` 与
> [`.harness/scripts/SCRIPTS.md`](.harness/scripts/SCRIPTS.md)。阶段推进 / 测试 / 合并等命令
> （spec-advance / run-tests / worktree-merge / check-skills 等）以指针提及，不在此逐条列举。

### 4. 度量指标系统

核心过程与质量指标（变更周期 / 文档完整度 / 首次通过率 / Bug 逃逸率 / 返工率）,持续改进流程:

| 指标 | 目标 | 说明 |
|------|------|------|
| ⏱️ **变更周期** | ≤ 3 天 | 从需求到归档的时间 |
| 📚 **文档完整度** | 100% | 文档齐全度评分 |
| ✅ **首次通过率** | ≥ 70% | 一次审查通过比例 |
| 🐛 **Bug 逃逸率** | ≤ 5% | 归档后发现 Bug 比例 |
| 🔄 **返工率** | ≤ 20% | 需要返工的比例 |

---

## 🔄 工作流程

### 完整工作流程图

```mermaid
graph TB
    A[用户需求] --> B[项目经理]
    B --> C{需求复杂度?}
    
    C -->|简单| D[直接修复]
    C -->|中等| E[简化流程]
    C -->|复杂| F[完整流程]
    C -->|关键| F
    
    F --> H[Phase 1: Proposal（PM 直产 + gate-1 自检 + 用户确认门）]
    H --> J[Phase 2: 代码开发]
    J --> L[Phase 3: 测试验证]
    L --> M[Phase 4: 代码审查（合规+安全透镜，高危触发双盲审）]
    M -->|通过| N[Phase 5: spec-archive 归档]
    M -->|不通过| J
    
    N --> O[完成报告]
    
    D --> P[测试]
    P --> O
    
    E --> Q[最小文档]
    Q --> P
```

### 五阶段详细流程

#### Phase 1: Proposal（PM 直产）

**目标**: 将模糊需求转化为清晰提案

**步骤**:
1. 需求挖掘 (听 → 挖 → 列 → 排 → 写)（PM 直产，原 requirement-analyst 职责吸收）
2. 创建需求目录: `openspec/changes/<name>/`
3. 编写 `proposal.md` (使用模板)
4. gate-1 PM 自检 + `validate` 硬校验（≥80）
5. **用户确认门**: proposal + gate-1 + validate ≥80 后暂停并展示提案摘要，等待用户确认；
   确认前不委派 code-developer、不进入实现（与「快速开始」步骤 2 一致）

**产出**: `openspec/changes/<name>/proposal.md`

**示例提示词**:
```
分析以下需求并创建提案:
"我需要一个用户导出功能,可以批量导出用户数据"
```

#### Phase 2: 代码开发

**目标**: 按照设计实现代码

**步骤**:
1. 阅读 `proposal.md`
2. 创建 `design.md` (使用模板；仅 complex/critical，medium 不含 design.md)
3. 创建 `tasks.md` (使用模板)
4. 按 `tasks.md` 逐步实施
5. 编写单元测试
6. 运行测试和 lint

**产出**: 
- `openspec/changes/<name>/design.md`
- `openspec/changes/<name>/tasks.md`
- 代码实现

**示例提示词**:
```
根据已审批的 proposal,创建设计文档和任务文档,然后开始实现。
```

#### Phase 3: 测试验证

**目标**: 验证所有功能正确实现

**步骤**:
1. 读取 `tasks.md` 验证步骤
2. 逐项执行测试
3. 记录测试结果
4. 运行完整测试套件
5. 生成测试报告

**产出**: `verification-report.md`（overall_verdict=PASS）+ 更新后的 `tasks.md`（含验证结果）

**示例提示词**:
```
运行所有验证步骤,确保所有功能正确实现。
```

#### Phase 4: 代码审查

**目标**: 确保代码质量、合规与安全性（审查含代码/合规/安全透镜；高危变更触发 dual-review 双盲审）

**步骤**:
1. 文档审查 (proposal, design, tasks，按 profile required_docs 条件化)
2. 模板合规审查（原 quality-reviewer 职责，机械部分由 validate 脚本承接）
3. 代码审查 (安全、正确性、测试、设计、可读性)
4. 安全透镜（原 security-auditor 职责，安全审查并入 review-report.md，无独立 security-report.md）
5. 确认所有验证通过
6. 生成审查报告；高危变更（risk-signal 信号非空）触发 dual-review 双盲审：双审实例独立产出
   `review-report-b.md`，差异由 PM 仲裁（详见 code-reviewer 双盲审章节，指针不展开）
7. Metrics 评分

**产出**: `openspec/changes/<name>/review-report.md`（高危双盲审另产出 `review-report-b.md`）

**示例提示词**:
```
审查代码和文档,生成审查报告,包括 Metrics 评分。
```

#### Phase 5: 归档

**目标**: 保存完整记录,保持工作区整洁

**步骤**:
1. 确认所有审查通过
2. 执行归档脚本（`harness.py spec-archive`）
3. 移动到 `openspec/changes/archive/`
4. Git 提交

**产出**: 归档的完整文档

**示例提示词**:
```
所有审查通过,执行归档。
```

---

## 📚 使用案例

### 案例 1: 新功能开发

**场景**: 添加用户认证功能

**提示词**:
```markdown
我想添加用户认证功能,具体要求:
1. 邮箱注册和登录
2. JWT token 认证
3. 密码重置功能
4. 防止暴力破解 (登录失败限制)
5. 记住我功能

技术栈:
- 后端: Node.js + Express
- 数据库: PostgreSQL
- 缓存: Redis

请按照完整流程实现。
```

**Harness 会自动**:
1. ✅ 创建 `openspec/changes/user-authentication/`
2. ✅ 生成需求提案 (frontmatter AC + Why/What Changes/Capabilities/Impact)
3. ✅ 生成设计文档 (Context / Goals-Non-Goals / Decisions / Risks-Trade-offs；仅 complex/critical)
4. ✅ 生成任务文档 (分组任务 + 验证步骤)
5. ✅ 实现代码 (注册、登录、密码重置)
6. ✅ 编写测试 (单元测试、集成测试)
7. ✅ 运行验证
8. ✅ 代码审查 (安全性、质量)
9. ✅ 归档

**你可以查看**:
- `openspec/changes/user-authentication/proposal.md` - 查看需求是否完整
- `openspec/changes/user-authentication/design.md` - 查看架构设计
- `openspec/changes/user-authentication/tasks.md` - 追踪实施进度
- `openspec/changes/user-authentication/review-report.md` - 查看审查结果

### 案例 2: Bug 修复

**场景**: 导出功能在大数据量时超时

**提示词**:
```markdown
Bug 报告:
- 功能: 用户导出为 CSV
- 问题: 当用户数超过 10000 时,导出超时
- 错误信息: "Request timeout after 30s"
- 影响: 无法导出大量用户数据

请修复这个性能问题。
```

**Harness 会**:
1. 分析复杂度 (可能是简单修复,也可能是架构问题)
2. 如果是简单修复: 直接修复 → 测试 → 完成
3. 如果需要重构: 完整流程

### 案例 3: 代码审查

**场景**: 审查最近的用户管理模块改动

**提示词**:
```markdown
请审查我最近的用户管理模块改动:
- 分支: feature/user-management
- 关注点: 
  1. 安全性 (权限控制)
  2. 性能 (数据库查询)
  3. 代码质量

生成完整的审查报告。
```

### 案例 4: 查看度量指标

**场景**: 查看项目整体质量指标

**提示词**:
```markdown
收集并展示 Harness 工程的度量指标报告。
```

**或使用脚本**:
```bash
python .harness/scripts/harness.py metrics
```

---

## 📁 目录结构

```
harness/
├── AGENTS.md                          # 📍 跨工具入口 (导航 + 速查)
├── CLAUDE.md                          # 🚦 Claude Code 铁律入口（自动加载）
├── README.md                          # 📘 完整说明 / 案例 / FAQ（你在这里）
├── LICENSE                            # 开源许可证
│
├── .claude/
│   ├── agents/                        # 🤖 4 核心智能体定义
│   │   ├── project-manager.md         # 项目经理（唯一入口，直产 proposal）
│   │   ├── code-developer.md          # 代码开发智能体
│   │   ├── test-runner.md             # 测试执行智能体
│   │   └── code-reviewer.md           # 代码审查智能体（高危触发 dual-review 双盲审）
│   └── commands/                      # slash 命令（audit/review/test/spec-*）
│
├── openspec/                          # 🔌 OpenSpec 项目目录（新变更）
│   ├── config.yaml                    # schema: spec-driven
│   ├── schemas/spec-driven/templates/ # 项目级模板覆盖（proposal/design/tasks，含 harness frontmatter）
│   ├── changes/                       # 进行中的变更
│   │   └── <name>/{proposal,design,tasks}.md + specs/
│   └── changes/archive/               # 已归档变更（只读）
│
└── .harness/                          # 🔧 harness 引擎（规范 / 脚本 / 校验）
    ├── change/archive/                # 📝 历史变更目录（只读，不再新增）
    ├── templates/                     # 📋 verdict/评分类模板（review-report / verification-report）
    ├── schemas/                       # ✅ verdict/评分/事件/state 等 frontmatter 校验 schema
    ├── workflows/                     # 🧭 DAG profile（trivial / hotfix / standard / critical）
    ├── scripts/                       # 🛠️ 统一 CLI：harness.py（命令清单见 SCRIPTS.md / harness.py --list）
    ├── skills/                        # 🎓 技能文档（agent 运行时按需读）
    ├── rules/                         # 📏 规范与标准（行为 / 编码 / 安全）
    ├── worktrees/                     # 🔀 变更隔离工作树（spec-create 自动创建）
    ├── backlog.jsonl                  # 📒 范围延期 / backlog 账本
    ├── trivial-index.jsonl            # ✏️ trivial 直通记录
    └── metrics-report.md              # 📊 度量指标报告（自动生成）
```

---

## 🤖 智能体团队

### 1. 🎯 项目经理 (Project Manager)

**文件**: [.claude/agents/project-manager.md](.claude/agents/project-manager.md)

**职责**:
- 📥 **所有任务的唯一入口**
- 🎯 分析需求,决定工作流（复杂度路由：trivial / hotfix / standard / critical）
- 📝 **直产 proposal.md**（需求分析 + 模板撰写 + gate-1 自检 + validate ≥80；原 requirement-analyst 职责吸收）
- ✅ 用户确认门通过后分派下游 agent
- 🔍 协调与审查各阶段产出
- 📊 向用户汇报进度
- 🚨 错误处理和决策

**产出**: `openspec/changes/<name>/proposal.md`（其余阶段文档由下游 agent 产出）

**何时使用**: **所有任务都必须先找项目经理**

**示例提示词**:
```
我想添加 xxx 功能,请分析需求并开始实施。
```

### 2. 💻 代码开发智能体 (Code Developer)

**文件**: [.claude/agents/code-developer.md](.claude/agents/code-developer.md)

**职责**:
- 🏗️ 创建 design.md（使用模板；仅 complex/critical）
- 📝 创建 tasks.md（使用模板）
- 💻 按照 tasks.md 实施代码
- 🧪 编写单元测试
- 📊 更新文档

**产出**: 
- `openspec/changes/<name>/design.md`（complex/critical）
- `openspec/changes/<name>/tasks.md`
- 代码实现

### 3. 🧪 测试执行智能体 (Test Runner)

**文件**: [.claude/agents/test-runner.md](.claude/agents/test-runner.md)

**职责**:
- 🧪 执行单元/集成测试
- ✅ 按 tasks.md 验证步骤验证
- 📊 生成验证报告 verification-report.md
- 🐛 诊断失败原因

### 4. 🔍 代码审查智能体 (Code Reviewer)

**文件**: [.claude/agents/code-reviewer.md](.claude/agents/code-reviewer.md)

**职责**（审查含代码/合规/安全三部分；原 security-auditor + quality-reviewer 职责吸收）:
- 🔍 代码质量和安全审查（安全透镜）
- 📋 模板合规审查（原 quality-reviewer 职责，机械部分由 validate 脚本承接）
- 📊 Metrics 评分
- 📦 归档已完成需求（spec-archive）

**高危变更**: risk-signal 信号非空时触发 dual-review 双盲审——双审实例独立产出
`review-report-b.md`，差异由 PM 仲裁（详见 `.claude/agents/code-reviewer.md` 双盲审章节，指针不展开）。

**安全敏感变更**: 安全审查并入 review-report.md，不产生独立 security-report.md

---

## 📋 文档模板

> harness 的文档模板分两类：**业务工件模板**（proposal / design / tasks，openspec 项目级覆盖模板，
> 位于 `openspec/schemas/spec-driven/templates/`）与 **verdict/评分类模板**（review-report /
> verification-report，位于 `.harness/templates/`）。

### 1. proposal.md - 需求提案

**用途**: 描述动机（Why）、变更内容（What Changes）、能力（Capabilities）、影响（Impact）与验收标准

**结构**: harness frontmatter（complexity / priority / security_sensitive / touches / acceptance_criteria）+ openspec 正文

**核心章节**:
- Why（为什么现在做）
- What Changes（改什么 / 删除 / 破坏性）
- Capabilities（新 / 改能力，声明时须配 specs delta）
- Impact（受影响文件 / 非目标 / 风险 / 依赖）

**模板**: openspec 项目级模板 `openspec/schemas/spec-driven/templates/proposal.md`

### 2. design.md - 设计文档（仅 complex / critical）

**用途**: 记录设计上下文、目标边界、关键决策与风险权衡

**核心章节**:
- Context
- Goals / Non-Goals
- Decisions
- Risks / Trade-offs

**模板**: openspec 项目级模板 `openspec/schemas/spec-driven/templates/design.md`

### 3. tasks.md - 任务文档

**用途**: 分组实施步骤 + 验证步骤 + AC 交叉引用 + 范围变更记录

**核心章节**:
- 分组任务清单（`- [ ]` 逐条勾选）
- 范围变更记录（scope.discovered / absorbed / deferred 账本）
- 验证步骤（`### Verify N`，每条标注覆盖的 AC-<id>）

**模板**: openspec 项目级模板 `openspec/schemas/spec-driven/templates/tasks.md`

### 4. review-report.md - 审查报告

**用途**: 代码审查结果、质量评分（frontmatter `scores` 机器可读，`overall ≥ 80` 才可归档）

**核心章节**:
- 审查概要（verdict: APPROVE / REQUEST_CHANGES / REJECT）
- 文档审查（proposal / design / tasks 评分）
- 代码审查（安全 / 正确性 / 测试覆盖 / 设计质量 / 可读性）
- 审查决策与审查历史

**模板**: [.harness/templates/review-report.md](.harness/templates/review-report.md)

### 5. verification-report.md - 验证报告

**用途**: 功能验证结果、验收标准逐条映射到 evidence

**核心章节**:
- 验证概要（overall_verdict: PASS / FAIL）
- 验收标准验证（ac_results 逐条 + evidence，必填非空）
- 验证决策

**模板**: [.harness/templates/verification-report.md](.harness/templates/verification-report.md)

---

## 🛠️ 自动化脚本

> 以下为主链命令示例（非 exhaustive）；完整命令清单与细节见
> [`.harness/scripts/SCRIPTS.md`](.harness/scripts/SCRIPTS.md) 与 `python .harness/scripts/harness.py --list`。

### 1. spec-create - 创建变更

```bash
python .harness/scripts/harness.py spec-create user-authentication
```

**功能**:
- ✅ 调用 openspec new change 创建变更目录
- ✅ git worktree 隔离
- ✅ 记录 change.created 事件
- ✅ 冻结验证基线（AC-6）

### 2. spec-archive - 归档变更

```bash
python .harness/scripts/harness.py spec-archive user-authentication
```

**功能**:
- ✅ harness 前置门禁（评分/verdict/冲突/基线 B−A）
- ✅ openspec archive 归档 + spec 合并
- ✅ 记录 change.archived 事件 + metrics

### 3. metrics - 收集指标

```bash
python .harness/scripts/harness.py metrics
```

**功能**:
- ✅ 计算核心过程与质量指标，输出报告到 `.harness/metrics-report.md`
- ✅ 生成改进建议

### 4. spec-list / spec-show - 列出/查看变更

```bash
# 列出所有变更（纯透传 openspec list）
python .harness/scripts/harness.py spec-list --json

# 查看单个变更
python .harness/scripts/harness.py spec-show user-authentication
```

**功能**:
- ✅ 纯透传 openspec list/show
- ✅ 输出 JSON 供程序化使用

---

## 📊 度量指标

### 核心指标说明

#### 1. 平均变更周期时间 (Cycle Time)

**定义**: 从需求创建到归档的平均时间

**目标**: ≤ 3 天

**计算方法**:
```bash
python .harness/scripts/harness.py metrics
```

**改进建议**:
- > 5 天: 简化流程
- 3-5 天: 优化任务分解
- < 3 天: 保持现状

#### 2. 文档完整度 (Documentation Completeness)

**定义**: 文档齐全度和质量评分

**目标**: 100%

**评分标准**:
- proposal.md (20%)
- design.md (30%)
- tasks.md (25%)
- review-report.md (15%)
- verification-report.md (10%)

#### 3. 首次审查通过率 (First Review Pass Rate)

**定义**: 第一次审查就通过的比例

**目标**: ≥ 70%

**改进建议**:
- < 50%: 加强自测
- 50-69%: 增加检查清单
- ≥ 70%: 保持质量

#### 4. Bug 逃逸率 (Bug Escape Rate)

**定义**: 归档后发现的 Bug 比例

**目标**: ≤ 5%

**改进建议**:
- > 10%: 增加测试覆盖
- 5-10%: 改进测试用例
- < 5%: 保持质量

#### 5. 返工率 (Rework Rate)

**定义**: 需要返工修改的比例

**目标**: ≤ 20%

**改进建议**:
- > 30%: 改进需求分析
- 20-30%: 加强前期沟通
- < 20%: 保持流程

### 查看指标报告

```bash
# 生成最新报告（完整命令见 SCRIPTS.md / harness.py --list）
python .harness/scripts/harness.py metrics

# 查看报告
cat .harness/metrics-report.md
```

---

## 💡 最佳实践

### 对于用户

1. **清晰描述需求**
   - ❌ "我想加个功能"
   - ✅ "我想添加用户导出功能,支持 CSV 格式,可以按日期筛选"

2. **提供上下文**
   - 技术栈信息
   - 现有系统架构
   - 约束条件

3. **及时审查产出**
   - 查看 proposal.md 确认需求理解正确
   - 查看 design.md 确认架构合理
   - 查看 tasks.md 追踪进度

### 对于项目经理

1. **严格遵循流程**
   - 所有任务都通过你
   - 不跳过任何阶段
   - 确保质量审查通过

2. **及时决策**
   - 需求不清晰时立即询问
   - 发现风险时及时调整
   - 审查不通过时打回重做

3. **关注指标**
   - 每周查看度量报告
   - 发现指标恶化时干预
   - 持续优化流程

### 对于开发者

1. **使用模板**
   - proposal/design/tasks 走 openspec 项目级模板（`openspec/schemas/spec-driven/templates/`，含 harness frontmatter）
   - review/verification 报告走 `.harness/templates/` verdict 模板
   - 从对应模板目录生成/复制，填写所有章节，不删除模板章节

2. **小步提交**
   - 每 10-30 分钟一个可验证状态
   - 频繁运行测试
   - 及时更新文档

3. **质量优先**
   - 先让它能跑,再让它好看
   - 测试是说明书,不是保险
   - 边界条件必须检查

---

## ❓ 常见问题

### Q1: 我应该直接调用专业智能体吗?

**A**: ❌ **不应该**。所有任务都必须通过项目经理,由项目经理决定使用哪些智能体。

### Q2: 简单任务也需要完整流程吗?

**A**: ❌ **不需要**。项目经理按复杂度路由（对应 profile 见 AGENTS.md）:
- trivial（typo / 单行）: 直接修复，不建 change
- simple（单文件 / 明确）: hotfix 精简流程
- medium（多文件 / 新功能）: standard 流程（medium 不含 design.md）
- complex / critical（复杂 / 安全架构）: 完整流程 + design.md；审查含安全透镜，高危变更触发 dual-review 双盲审

### Q3: 文档真的那么重要吗?

**A**: ✅ **非常重要**。文档是:
- 事实来源 (Source of Truth)
- 团队协作的基础
- 未来维护的关键
- 质量审查的依据

### Q4: 可以跳过某个阶段吗?

**A**: ❌ **不可以**（profile 要求的阶段须全部走完）。每个阶段都有其价值:
- Proposal（PM 直产 + gate-1 + 用户确认门）: 确保理解正确
- 代码开发: 规范实现
- 测试验证: 确保功能正确
- 代码审查: 保证质量（高危触发 dual-review 双盲审）
- 归档: 保存记录

### Q5: 什么时候需要安全审查?

**A**: 安全审查以**安全透镜**形式并入 code-reviewer 审查（review-report.md，不产独立 security-report）:
- 涉及认证、授权
- 涉及敏感数据处理
- 涉及网络通信
- 用户特别要求

另：dual-review 双盲审仅在 risk-signal 高危信号清单非空 **且** 单审 verdict==APPROVE 时才放行
（任一不满足脚本拒绝推进；非高危走单审）；`security_sensitive=true` 只在单审内加深安全透镜、不触发
双盲审（详见 `.claude/agents/code-reviewer.md` 双盲审章节）。

### Q6: 如何确保文档质量?

**A**: 机械检查下沉到 validate 脚本 + code-reviewer 合规透镜：
- `validate-artifact.py` 检查 frontmatter 字段与章节完整性（机械部分）
- code-reviewer 审查含模板合规部分（原 quality-reviewer 职责；高危变更双盲审）
- 不合规项打回重写
- 持续改进文档质量

### Q7: 度量指标多久收集一次?

**A**: 建议:
- **每周**: 快速收集,查看趋势
- **每月**: 详细分析,制定改进计划

### Q8: 如果我认为审查评分不公平怎么办?

**A**: 可以:
- 向项目经理申诉
- 项目经理可以决定重新审查
- 提供具体理由说明为什么评分不公平

---

## 🔄 进阶参考（从 AGENTS.md 迁入）

> 以下内容为工作流的详细参考，AGENTS.md 仅保留速查。按需阅读。

### 智能体协作状态机

```mermaid
stateDiagram-v2
    [*] --> 项目经理: 用户需求
    项目经理 --> 项目经理: PM 直产 proposal + gate-1 自检 + validate ≥80
    项目经理 --> 用户确认门: 展示提案摘要待确认
    用户确认门 --> 代码开发智能体: proposal.confirmed 后分派
    用户确认门 --> 项目经理: proposal.rejected → 返回澄清
    代码开发智能体 --> 测试执行智能体: design + tasks + 代码
    测试执行智能体 --> 代码审查智能体: 测试全部通过
    代码审查智能体 --> 项目经理: gate-2 审查通过（高危双盲审）
    代码审查智能体 --> 代码开发智能体: 审查不通过
    项目经理 --> 归档: 确认归档
    归档 --> [*]: 完成
```

### 上下文传递规范

| 从阶段 | 到阶段 | 传递内容 |
|--------|--------|----------|
| 项目经理（PM 直产） | 用户确认门 | proposal.md（gate-1 自检 + validate ≥80 后暂停待确认） |
| 用户确认门 | 代码开发 | 已确认 proposal.md（proposal.confirmed 事件） |
| 代码开发 | 测试执行 | proposal.md + design.md（complex/critical）+ tasks.md |
| 测试执行 | 代码审查 | tasks.md（含验证结果）+ verification-report.md |
| 代码审查 | 归档 | 所有文档 + review-report.md（高危双盲审另含 review-report-b.md） |

### 失败任务处理流程

```mermaid
graph TD
    A[任务失败] --> B{失败类型?}
    B -->|质量问题| C[返回项目经理]
    B -->|测试失败| D[返回开发智能体]
    B -->|审查不通过| D
    B -->|脚本错误| E[检查环境]
    C --> F{重试次数?}
    F -->|< 2次| G[重新分派]
    F -->|≥ 2次| H[用户介入]
    D --> I{重试次数?}
    I -->|< 2次| J[重新开发]
    I -->|≥ 2次| H
    E --> K{修复成功?}
    K -->|是| L[重新执行]
    K -->|否| H
    G --> M[继续流程]
    J --> M
    L --> M
    H --> N[项目经理报告用户]
```

### 跨变更冲突处理

`spec-create` / `spec-archive` 会做 touches/depends_on 冲突检查。PM 在 `spec-list` 看到冲突时按下表决策：

| 情况 | PM 动作 |
|------|--------------|
| touches 完全独立 | 并行进行 |
| touches 部分重叠，无 depends_on | (a) 串行 (b) 强制 depends_on (c) 拆分变更 |
| touches 完全重叠 | 必须串行或合并为一个变更 |
| depends_on 声明但前置未归档 | 阻塞当前变更，等前置完成 |
| 依赖的变更不存在 | 报错并要求作者修正 frontmatter |

---

## 🔗 相关资源

- [AGENTS.md](AGENTS.md) - 跨工具入口与速查（导航 + 索引）
- [CLAUDE.md](CLAUDE.md) - Claude Code 铁律入口
- [工件模板](openspec/schemas/spec-driven/templates/) - proposal/design/tasks（openspec 项目级模板）
- [verdict 模板](.harness/templates/) - review-report / verification-report
- [脚本清单](.harness/scripts/SCRIPTS.md) - 脚本用法（按需读）
- [技能文档](.harness/skills/) - 智能体技能说明
- [规范标准](.harness/rules/) - 项目规范
- [度量报告](.harness/metrics-report.md) - 最新指标

---

## 📝 版本历史

> 早期以 semver 记录版本里程碑；2026-08 openspec 集成后 harness 进入持续自演进阶段，
> 后续里程碑以**真实归档 change 名为锚**（见 `openspec/changes/archive/`；更早历史见
> `.harness/change/archive/`），不再为每个阶段发明新 semver 号。

### v3.0.0 (2026-08-23, streamline-agent-workflow)

**重大更新**:
- ✅ 变更流收敛为 4 个核心 agent（PM 直产 proposal / code-developer / test-runner / code-reviewer）
- ✅ 删除 requirement-analyst / quality-reviewer / security-auditor（职责吸收进 PM 与 CR）
- ✅ workflow DAG 精简：standard 无 requirement-analysis/quality-gate/test-design 节点；medium 去 design.md
- ✅ 单报告审查收口：review-report.md 含代码/合规/安全三部分，无独立 security-report.md
- ✅ 共享 phases/enums schema（单一事实来源）；validate 脚本承接章节完整性机械检查

### v2.0.0 (2026-06-13)

**重大更新**:
- ✅ 新增质量审查智能体 quality-reviewer（v3.0 已删除，职责并入 code-reviewer）
- ✅ 新增标准化文档模板体系
- ✅ 新增自动化脚本库 (创建、归档、度量)
- ✅ 新增度量指标系统 (核心过程/质量指标)
- ✅ 新增质量评分和反馈机制
- ✅ 优化智能体协作流程
- ✅ 完善文档和示例

### v1.0.0 (初始版本)

- 基础工作流引擎
- 5 个核心智能体（后收敛为 4 核心）
- 基础文档结构

### 2026-08 ~ 2026-09 自演进时间线（openspec 集成以来）

自 streamline-agent-workflow（v3.0.0）起，harness 以「变更即归档」方式持续自演进。以下按主题
概述（**非 exhaustive**，完整目录见 `openspec/changes/archive/`）：

- **openspec 集成（openspec-integration 2026-08-17~20 起，历史区）**：变更生命周期迁到
  OpenSpec CLI；后续经 openspec-wrapper-robustness / spec-explore-wrapper /
  fix-spec-schema-tasks-requires / fix-spec-archive-write-after-move / archive-lock-success-cleanup /
  unify-archive-single-track 等收敛为单轨并加固包装健壮性。
- **explore-first 会话流程（session-explore-flow / session-explore-on-demand）**：默认探索立场 +
  按需进入 explore；proposal 阶段随后落地「用户确认门」（CLAUDE.md 铁律#8）。
- **知识注入与技能一致性（knowledge-injection / knowledge-injection-keying / skill-consistency）**：
  agent 技能按 envelope 注入；check-skills 五查校验（存在性 / 双向性 / 覆盖性 / 文档地图 / 工具充分性）。
- **worktree 与归档守卫（archive-worktree-guardrail / spec-archive-worktree-cleanup /
  worktree-flow-closure / flow-closure-fixes / archive-dir-commit-guard）**：变更在隔离 worktree 实施，
  流程收口（phase 事件 + spec-advance），归档守卫防绕过。
- **范围守卫与交付物契约（scope-guardrail / developer-deliverables-contract /
  phase-advance-deliverable-check / flow-state-retry-integrity）**：范围外需求四类路由（A/B/C/D），
  重试计数 state.json 权威归约，phase 推进前置交付物检查。
- **质量门与 evidence 层（design-review-gate / implementation-quality-gate /
  review-evidence-layer / verification-evidence-layer / verification-integrity-format /
  review-gate-consistency）**：design/tasks 机器评分 rubric 门禁；验证 / 审查报告 evidence 证据要求。
- **backlog 账本机制（backlog-ledger-remediation / backlog-small-cleanup /
  backlog-list-open-default）**：范围延期与待办进 `backlog.jsonl` 统一账本追踪。
- **高危 dual-review 双盲审（high-risk-dual-review / phases-dual-review-enum /
  sync-code-reviewer-artifacts）**：高危变更双审实例独立报告，差异由 PM 仲裁。
- **委派模型等级路由（developer-capability-fixes 2026-08-27）**：复杂/关键变更以更高模型等级委派
  code-developer（complex/critical → opus 级；standard.json model_routing 由 plan-workflow 消费）。
- **PM 委派能力与 9 月收敛（pm-delegation-capability / reporting-agent-tools /
  retire-auto-evolution）**：project-manager frontmatter 增加子代理委派工具（Task）并强化委派纪律
  （pm-delegation-capability）；报告类 agent 最小工具集（Write/Edit）机器校验（reporting-agent-tools）；
  收编自动演进机制（retire-auto-evolution）。
- **入口文档与作者体验（dedupe-root-docs / entry-doc-consistency / design-tasks-chunked-write /
  harness-guard-fixes / settings-config-fixes）**：入口文档分层（CLAUDE 铁律 / AGENTS 速查 / README
  完整说明）并指针化去重；长文档分段撰写规则；脚本守卫修复。

---

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE)

---

## 🙏 致谢

感谢所有为 Harness 工程贡献的开发者!

---

**记住:向项目经理描述你的需求,剩下的交给专业团队!** 🚀