# 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**: 2
- **Created**: 2026-06-11
- **Last Updated**: 2026-07-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

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

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

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

---

## 📖 目录

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

---

## 🚀 快速开始

### 1. 理解 Harness 是什么

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

- 🤖 **专业智能体协作** - 6+ 个专业 AI 智能体,各司其职
- 📋 **标准化文档模板** - 5 种核心文档模板,确保一致性
- 🛠️ **自动化脚本** - 创建、归档、度量,全流程自动化
- 📊 **度量指标追踪** - 5 大核心指标,持续改进流程

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

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

**示例提示词**:

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

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

项目经理会:
1. ✅ 分析需求复杂度
2. ✅ 创建需求目录 (使用脚本)
3. ✅ 分派给需求分析智能体
4. ✅ 质量审查 (自动)
5. ✅ 分派给开发智能体
6. ✅ 测试验证
7. ✅ 代码审查
8. ✅ 归档完成

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

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

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

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

**Harness 会自动完成**:
1. 创建 `.harness/change/csv-export/` 目录
2. 生成 `proposal.md` (需求提案)
3. 生成 `design.md` (设计文档)
4. 生成 `task.md` (任务文档)
5. 实现代码
6. 编写测试
7. 运行验证
8. 代码审查
9. 归档到 `.harness/change/archive/`

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

---

## ✨ 核心特性

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

| 智能体 | 职责 | 触发条件 |
|--------|------|----------|
| 🎯 **项目经理** | 任务入口、决策、协调 | 所有任务的唯一入口 |
| 📝 **需求分析** | 需求挖掘、提案编写 | 新功能、模糊需求 |
| 💻 **代码开发** | 设计、编码、测试 | 需求审批后 |
| 🧪 **测试执行** | 单元/集成测试 | 代码开发完成 |
| 🔍 **代码审查** | 质量、安全审查 | 测试通过后 |
| 🛡️ **安全审计** | 安全扫描 | 涉及认证/敏感数据 |
| ✅ **质量审查** | 模板合规检查 | 每个阶段完成后 |

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

5 种核心模板,确保所有文档一致、完整:

- 📋 [proposal.md](.harness/templates/proposal.md) - 需求提案
- 🏗️ [design.md](.harness/templates/design.md) - 设计文档
- 📝 [task.md](.harness/templates/task.md) - 任务文档
- 🔍 [review-report.md](.harness/templates/review-report.md) - 审查报告
- ✅ [verification-report.md](.harness/templates/verification-report.md) - 验证报告

### 3. 自动化脚本库

| 脚本 | 功能 | 平台 |
|------|------|------|
| `create-change.sh/ps1` | 创建需求目录和文档 | Bash/PowerShell |
| `archive-change.sh` | 归档已完成需求 | Bash |
| `collect-metrics.sh` | 收集度量指标 | Bash |
| `list-changes.sh` | 列出所有变更 | Bash |

### 4. 度量指标系统

5 大核心指标,持续改进流程:

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

---

## 🔄 工作流程

### 完整工作流程图

```mermaid
graph TB
    A[用户需求] --> B[项目经理]
    B --> C{需求复杂度?}
    
    C -->|简单| D[直接修复]
    C -->|中等| E[简化流程]
    C -->|复杂| F[完整流程]
    C -->|关键| G[完整流程+安全审计]
    
    F --> H[Phase 1: 需求分析]
    H --> I[质量审查]
    I -->|通过| J[Phase 2: 代码开发]
    I -->|失败| B
    
    J --> K[质量审查]
    K -->|通过| L[Phase 3: 测试验证]
    K -->|失败| B
    
    L --> M[Phase 4: 代码审查]
    M -->|通过| N[Phase 5: 归档]
    M -->|失败| B
    
    N --> O[完成报告]
    
    D --> P[测试]
    P --> O
    
    E --> Q[最小文档]
    Q --> P
```

### 五阶段详细流程

#### Phase 1: 需求分析

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

**步骤**:
1. 需求挖掘 (听 → 挖 → 列 → 排 → 写)
2. 创建需求目录: `.harness/change/<name>/`
3. 编写 `proposal.md` (使用模板)
4. 质量审查 (quality-reviewer)
5. 项目经理审批

**产出**: `.harness/change/<name>/proposal.md`

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

#### Phase 2: 代码开发

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

**步骤**:
1. 阅读 `proposal.md`
2. 创建 `design.md` (使用模板)
3. 创建 `task.md` (使用模板)
4. 质量审查 (quality-reviewer)
5. 按 `task.md` 逐步实施
6. 编写单元测试
7. 运行测试和 lint

**产出**: 
- `.harness/change/<name>/design.md`
- `.harness/change/<name>/task.md`
- 代码实现

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

#### Phase 3: 测试验证

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

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

**产出**: 更新后的 `task.md` (包含验证结果)

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

#### Phase 4: 代码审查

**目标**: 确保代码质量和安全性

**步骤**:
1. 文档审查 (proposal, design, task)
2. 代码审查 (安全、正确性、测试、设计、可读性)
3. 确认所有验证通过
4. 生成审查报告
5. Metrics 评分

**产出**: `.harness/change/<name>/review-report.md`

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

#### Phase 5: 归档

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

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

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

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

---

## 📚 使用案例

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

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

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

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

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

**Harness 会自动**:
1. ✅ 创建 `.harness/change/user-authentication/`
2. ✅ 生成需求提案 (包含用户故事、验收标准)
3. ✅ 生成设计文档 (架构图、API 设计、安全设计)
4. ✅ 生成任务文档 (详细实施步骤)
5. ✅ 实现代码 (注册、登录、密码重置)
6. ✅ 编写测试 (单元测试、集成测试)
7. ✅ 运行验证
8. ✅ 代码审查 (安全性、质量)
9. ✅ 归档

**你可以查看**:
- [proposal.md](.harness/templates/proposal.md) - 查看需求是否完整
- [design.md](.harness/templates/design.md) - 查看架构设计
- [task.md](.harness/templates/task.md) - 追踪实施进度
- [review-report.md](.harness/templates/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
.harness/scripts/collect-metrics.sh
```

---

## 📁 目录结构

```
harness/
├── AGENTS.md                          # 📍 项目入口 (详细工作流指南)
├── README.md                          # 📘 项目说明 (你在这里)
├── LICENSE                            # 开源许可证
│
├── .claude/
│   └── agents/                        # 🤖 智能体定义
│       ├── project-manager.md         # 项目经理 (任务入口)
│       ├── requirement-analyst.md     # 需求分析智能体
│       ├── code-developer.md          # 代码开发智能体
│       ├── test-runner.md             # 测试执行智能体
│       ├── code-reviewer.md           # 代码审查智能体
│       ├── security-auditor.md        # 安全审计智能体
│       └── quality-reviewer.md        # 质量审查智能体 ⭐ NEW
│
├── .harness/
│   ├── change/                        # 📝 需求变更目录
│   │   ├── archive/                   # 已归档的需求
│   │   │   └── <change-name>/         # 完成的需求
│   │   │       ├── proposal.md
│   │   │       ├── design.md
│   │   │       ├── task.md
│   │   │       ├── review-report.md
│   │   │       └── verification-report.md
│   │   └── <active-change>/           # 正在进行的需求
│   │       ├── proposal.md
│   │       ├── design.md
│   │       └── task.md
│   │
│   ├── templates/                     # 📋 文档模板 ⭐ NEW
│   │   ├── proposal.md                # 需求提案模板
│   │   ├── design.md                  # 设计文档模板
│   │   ├── task.md                    # 任务文档模板
│   │   ├── review-report.md           # 审查报告模板
│   │   └── verification-report.md     # 验证报告模板
│   │
│   ├── scripts/                       # 🛠️ 自动化脚本 ⭐ NEW
│   │   ├── create-change.sh           # 创建需求 (Bash)
│   │   ├── create-change.ps1          # 创建需求 (PowerShell)
│   │   ├── archive-change.sh          # 归档需求
│   │   ├── collect-metrics.sh         # 收集度量指标
│   │   └── list-changes.sh            # 列出所有变更
│   │
│   ├── skills/                        # 🎓 技能文档
│   │   ├── requirement-analysis.md    # 需求分析技能
│   │   ├── code-development.md        # 代码开发技能
│   │   ├── code-review.md             # 代码审查技能
│   │   ├── unit-testing.md            # 单元测试技能
│   │   ├── quality-review.md          # 质量审查技能 ⭐ NEW
│   │   ├── metrics-collector.md       # 度量指标技能 ⭐ NEW
│   │   └── integration-deployment.md  # 集成部署技能
│   │
│   ├── rules/                         # 📏 规范和标准
│   │   ├── behavior-standards.md      # 行为标准
│   │   ├── coding-standards.md        # 编码标准
│   │   └── security-standards.md      # 安全标准
│   │
│   └── metrics-report.md              # 📊 度量指标报告 (自动生成)
│
└── .qoder/                            # Qoder 配置
    ├── agents/
    ├── commands/
    └── skills/
```

---

## 🤖 智能体团队

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

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

**职责**:
- 📥 **所有任务的唯一入口**
- 🎯 分析需求,决定工作流
- 📋 分派任务给专业智能体
- 🔍 审查各阶段产出
- 📊 向用户汇报进度
- 🚨 错误处理和决策

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

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

### 2. 📝 需求分析智能体 (Requirement Analyst)

**文件**: [.claude/agents/requirement-analyst.md](.claude/agents/requirement-analyst.md)

**职责**:
- 📋 分析模糊需求
- 📝 创建 proposal.md (使用模板)
- ✅ 定义验收标准 (Given-When-Then)
- 🔍 影响范围分析

**产出**: `.harness/change/<name>/proposal.md`

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

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

**职责**:
- 🏗️ 创建 design.md (使用模板)
- 📝 创建 task.md (使用模板)
- 💻 按照 task.md 实施代码
- 🧪 编写单元测试
- 📊 更新文档

**产出**: 
- `.harness/change/<name>/design.md`
- `.harness/change/<name>/task.md`
- 代码实现

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

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

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

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

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

**职责**:
- 🔍 代码质量和安全审查
- 📋 文档完整性审查
- 📊 Metrics 评分
- 📦 归档已完成需求

### 6. 🛡️ 安全审计智能体 (Security Auditor)

**文件**: [.claude/agents/security-auditor.md](.claude/agents/security-auditor.md)

**职责**:
- 🔒 安全漏洞扫描
- 🛡️ OWASP Top 10 检查
- 🔑 敏感信息检测

**何时使用**: 涉及认证、敏感数据、网络通信时

### 7. ✅ 质量审查智能体 (Quality Reviewer) ⭐ NEW

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

**职责**:
- 📋 模板合规性检查
- 📊 文档质量评分
- 🚨 不合规项打回
- 📈 Metrics 收集

**何时使用**: 每个阶段完成后自动触发

---

## 📋 文档模板

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

**用途**: 描述需求、验收标准、影响范围

**核心章节**:
- 问题描述 (Why)
- 目标与验收标准 (Given-When-Then)
- 非功能性需求
- 影响分析
- 风险评估

**模板**: [.harness/templates/proposal.md](.harness/templates/proposal.md)

### 2. design.md - 设计文档

**用途**: 详细设计、架构决策、API 设计

**核心章节**:
- 架构设计 (Mermaid 图)
- 关键决策及理由
- 数据模型
- API 设计
- 安全设计
- 性能设计

**模板**: [.harness/templates/design.md](.harness/templates/design.md)

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

**用途**: 实施步骤、验证步骤、进度追踪

**核心章节**:
- 实施计划 (分阶段任务)
- 验证步骤 (逐项验证)
- 测试执行结果
- 完成检查清单
- 返工记录

**模板**: [.harness/templates/task.md](.harness/templates/task.md)

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

**用途**: 代码审查结果、质量评分

**核心章节**:
- 审查概要
- 文档审查评分
- 代码审查问题
- Metrics 评分
- 审查决策

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

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

**用途**: 功能验证结果、测试报告

**核心章节**:
- 验证概要
- 验收标准验证
- 功能测试
- 性能测试
- 测试覆盖率

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

---

## 🛠️ 自动化脚本

### 1. create-change - 创建需求

**Bash**:
```bash
.harness/scripts/create-change.sh user-authentication
```

**PowerShell**:
```powershell
.harness/scripts/create-change.ps1 user-authentication
```

**功能**:
- ✅ 创建需求目录
- ✅ 从模板复制文档
- ✅ 替换占位符
- ✅ 验证命名规范

### 2. archive-change - 归档需求

```bash
.harness/scripts/archive-change.sh user-authentication
```

**功能**:
- ✅ 验证文档完整性
- ✅ 移动到 archive 目录
- ✅ Git 提交

### 3. collect-metrics - 收集指标

```bash
.harness/scripts/collect-metrics.sh
```

**功能**:
- ✅ 计算 5 大核心指标
- ✅ 生成改进建议
- ✅ 输出报告到 `.harness/metrics-report.md`

### 4. list-changes - 列出变更

```bash
# 列出所有
.harness/scripts/list-changes.sh all

# 只列出进行中
.harness/scripts/list-changes.sh active

# 只列出已归档
.harness/scripts/list-changes.sh archived
```

**功能**:
- ✅ 显示所有变更
- ✅ 文档状态
- ✅ 时间信息

---

## 📊 度量指标

### 核心指标说明

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

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

**目标**: ≤ 3 天

**计算方法**:
```bash
.harness/scripts/collect-metrics.sh
```

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

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

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

**目标**: 100%

**评分标准**:
- proposal.md (20%)
- design.md (30%)
- task.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
# 生成最新报告
.harness/scripts/collect-metrics.sh

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

---

## 💡 最佳实践

### 对于用户

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

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

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

### 对于项目经理

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

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

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

### 对于开发者

1. **使用模板**
   - 始终从 `.harness/templates/` 复制
   - 填写所有章节
   - 不删除模板章节

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

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

---

## ❓ 常见问题

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

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

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

**A**: ❌ **不需要**。项目经理会根据复杂度决定:
- 简单 (typo, 单行): 直接修复
- 中等 (单文件, 明确): 简化流程
- 复杂 (新功能, 多文件): 完整流程
- 关键 (安全, 架构): 完整流程 + 安全审计

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

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

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

**A**: ❌ **不可以**。每个阶段都有其价值:
- 需求分析: 确保理解正确
- 代码开发: 规范实现
- 测试验证: 确保功能正确
- 代码审查: 保证质量
- 归档: 保存记录

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

**A**: 以下情况需要安全审计:
- 涉及认证、授权
- 涉及敏感数据处理
- 涉及网络通信
- 用户特别要求

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

**A**: 通过质量审查智能体 (quality-reviewer):
- 检查模板合规性
- 计算文档质量分
- 不合规项打回重写
- 持续改进文档质量

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

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

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

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

---

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

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

### 智能体协作状态机

```mermaid
stateDiagram-v2
    [*] --> 项目经理: 用户需求
    项目经理 --> 需求分析智能体: 分派需求分析
    需求分析智能体 --> 项目经理: 提交 proposal.md
    项目经理 --> 项目经理: gate-1 PM 自检 + validate ≥80
    项目经理 --> 代码开发智能体: gate-1 通过后分派开发
    代码开发智能体 --> 测试执行智能体: design + task + 代码
    测试执行智能体 --> 代码审查智能体: 测试全部通过
    代码审查智能体 --> 项目经理: gate-2 审查通过
    代码审查智能体 --> 代码开发智能体: 审查不通过
    项目经理 --> 归档: 确认归档
    归档 --> [*]: 完成
```

### 上下文传递规范

| 从阶段 | 到阶段 | 传递内容 |
|--------|--------|----------|
| 需求分析 | PM gate-1 | proposal.md |
| PM gate-1 | 代码开发 | proposal.md |
| 代码开发 | 测试执行 | proposal.md + design.md + task.md |
| 测试执行 | 代码审查 | task.md（含验证结果）+ verification-report.md |
| 代码审查 | 归档 | 所有文档 + review-report.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[项目经理报告用户]
```

### 跨变更冲突处理

`create-change` 自动调用 `check-conflicts`。PM 在 `list-changes` 看到冲突时按下表决策：

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

---

## 🔗 相关资源

- [AGENTS.md](AGENTS.md) - 跨工具入口与速查（导航 + 索引）
- [文档模板](.harness/templates/) - 所有文档模板
- [自动化脚本](.harness/scripts/) - 所有脚本
- [技能文档](.harness/skills/) - 智能体技能说明
- [规范标准](.harness/rules/) - 项目规范
- [度量报告](.harness/metrics-report.md) - 最新指标

---

## 📝 版本历史

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

**重大更新**:
- ✅ 新增质量审查智能体 (quality-reviewer)
- ✅ 新增 5 种标准化文档模板
- ✅ 新增自动化脚本库 (创建、归档、度量)
- ✅ 新增度量指标系统 (5 大核心指标)
- ✅ 新增质量评分和反馈机制
- ✅ 优化智能体协作流程
- ✅ 完善文档和示例

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

- 基础工作流引擎
- 5 个核心智能体
- 基础文档结构

---

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE)

---

## 🙏 致谢

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

---

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