template-artifacts.md

ReqPlan-v3 产物模板集合

本文档包含 ReqPlan-v3 Harness 系统中所有产物文件的模板

---

目录

1. _analysis.md 模板
2. _design.md 模板
3. _implementation.md 模板
4. _verification.md 模板
5. _baton.md 模板
6. 质量审核报告模板

---

一、_analysis.md 模板

# 需求分析报告

> 产物版本: v1.0 | 最后修改: {ISO 8601} | 修改记录: v1.0 初始版本

## 基本信息
- 分析时间: {ISO 8601}
- 分析者: Analyzer Agent
- 场景类型: {开发/分析/修复}
- 原始需求: {用户原始描述}

---

## 一、需求理解

### 1.1 核心功能
| # | 功能点 | 优先级 | 说明 |
|---|--------|--------|------|
| 1 | {功能1} | P0 | {说明} |
| 2 | {功能2} | P1 | {说明} |

### 1.2 涉及角色
| 角色 | 职责 | 权限 |
|------|------|------|
| {角色1} | {职责} | {权限} |

### 1.3 数据实体
| 实体名 | 核心字段 | 类型 | 说明 |
|--------|----------|------|------|
| {实体1} | {字段} | {类型} | {说明} |

---

## 二、技术栈

### 2.1 技术选型
| 层级 | 技术 | 版本 |
|------|------|------|
| 语言 | {Python} | {3.13} |
| 框架 | {Flask} | {3.x} |
| 数据库 | {PostgreSQL} | {15} |

### 2.2 项目结构

{项目目录结构}

---

## 三、涉及文件

### 3.1 需修改的文件
| 文件 | 修改内容 |
|------|----------|
| {文件1} | {修改1} |

### 3.2 需新增的文件
| 文件 | 用途 |
|------|------|
| {文件1} | {用途} |

---

## 四、约束条件

### 4.1 技术约束
- {约束1}

### 4.2 业务约束
- {约束1}

### 4.3 时间约束
- {约束1}

---

## 五、可复用资源

### 5.1 现有代码
| 资源 | 说明 | 可复用程度 |
|------|------|-----------|
| {资源1} | {说明} | {百分比} |

### 5.2 第三方库
| 库 | 版本 | 用途 |
|----|------|------|
| {库1} | {版本} | {用途} |

---

## 六、风险评估

| # | 风险 | 等级 | 缓解措施 |
|---|------|------|----------|
| 1 | {风险} | {中} | {措施} |

---

## ⚠️ 产物完成后的强制操作（Analyzer Agent 必须执行）

```markdown
## 完成后检查清单

- [ ] 1. 本产物已保存到 {项目路径}/.agent/harness/_analysis.md
- [ ] 2. 产物头部包含版本号（v1.0）
- [ ] 3. 已确认产物包含所有必需章节（基本信息、需求理解、技术栈、涉及文件、约束条件）
- [ ] 4. 已触发 Quality Auditor 独立质量审核
- [ ] 5. 质量审核已通过（或已降级为自检模式）
- [ ] 6. 已更新接力棒：状态 ANALYZE ✅，下一步 CONFIRM

**阻断规则**：以上任一未勾选 → 不能进入 CONFIRM 阶段

---

本文档由 Analyzer Agent 自动生成 版本: 4.6 (ReqPlan-v3 v4.6) 时间: {ISO 8601}

---

## 二、_design.md 模板

```markdown
# 技术设计文档

> 产物版本: v1.0 | 最后修改: {ISO 8601} | 修改记录: v1.0 初始版本

## 基本信息
- 设计时间: {ISO 8601}
- 设计者: Designer Agent
- 关联分析: _analysis.md
- 模式: {NORMAL/DESIGN_FIX}

---

## 一、技术方案概述

### 1.1 架构选型
{架构模式选择及理由}

### 1.2 技术栈
| 组件 | 技术 | 版本 |
|------|------|------|
| 语言 | {Python} | {3.13} |
| 框架 | {Flask} | {3.x} |

---

## 二、模块划分

### 2.1 模块结构图

{模块关系图}

### 2.2 模块职责
| 模块 | 职责 | 依赖 |
|------|------|------|
| {模块1} | {职责} | {依赖} |

---

## 三、接口定义

### 3.1 REST API 规范

| # | 路径 | 方法 | 参数 | 响应 |
|---|------|------|------|------|
| 1 | /api/users | POST | {body} | {201} |

### 3.2 数据格式
```json
{JSON Schema}

---

四、数据模型

4.1 数据表结构

表名	字段	类型	说明
{表1}	{字段}	{类型}	{说明}

---

五、任务列表

5.1 任务表格

#	任务	涉及文件	验证方式	依赖	优先级
1	{任务1}	{文件}	{验证}	{无}	P0
2	{任务2}	{文件}	{验证}	{任务1}	P0

5.2 实施顺序

1. {任务1}
2. {任务2}

---

六、验证方案

6.1 Layer 1: 静态检查

• 工具: pylint / ruff / mypy
• 命令: ruff check .
• 验收标准:
  • 无致命错误（Error）
  • 警告（Warning）数量 ≤ 5
  • 代码风格符合 PEP 8

6.2 Layer 2: 单元测试

• 框架: pytest
• 命令: pytest tests/ -v
• 验收标准:
  • 所有测试通过
  • 覆盖率 ≥ 80%（P0 功能）

6.3 Layer 3: 构建集成

• 命令: python -m py_compile app.py
• 复杂项目额外检查:
  • pip install -r requirements.txt
  • python setup.py check（如有 setup.py）
  • pip install -e .（如有 pyproject.toml）
• 验收标准:
  • 编译无错误
  • 依赖安装成功

6.4 Layer 4: 异常处理

• Web 项目测试场景:
  • 401 未授权 → {"error": "Unauthorized"}
  • 403 禁止访问 → {"error": "Forbidden"}
  • 404 资源不存在 → {"error": "Not Found"}
  • 400 参数错误 → {"error": "Bad Request"}
• 通用项目测试场景:
  • 空输入/空值处理
  • 类型错误处理
  • 边界条件处理
  • 资源不存在处理
• 验收标准:
  • 所有异常场景正确处理
  • 错误信息清晰

6.5 Layer 5: 流程合规

• 产物完整性检查:
  • _analysis.md 存在且完整
  • _design.md 存在且完整
  • _implementation.md 存在且完整
• 文档更新检查:
  • README 更新
  • API 文档更新
  • 代码注释完整

---

⚠️ 产物完成后的强制操作（Designer Agent 必须执行）

## 完成后检查清单

- [ ] 1. 本产物已保存到 {项目路径}/.agent/harness/_design.md
- [ ] 2. 已触发 Quality Auditor 独立质量审核（拉起子Agent审核 _design.md）
- [ ] 3. 质量审核已通过（或已降级为自检模式）
- [ ] 4. 已更新接力棒：状态 DESIGN ✅，下一步 IMPLEMENT
- [ ] 5. 已确认任务列表包含"涉及文件"和"验证方式"列
- [ ] 6. 已确认验证方案包含 Layer 1-5

**阻断规则**：以上任一未勾选 → 不能进入 IMPLEMENT 阶段

---

本文档由 Designer Agent 自动生成 版本: 4.6 (ReqPlan-v3 v4.6) 时间: {ISO 8601}

---

## 三、_implementation.md 模板

```markdown
# 实现摘要

> 产物版本: v1.0 | 最后修改: {ISO 8601} | 修改记录: v1.0 初始版本

## 基本信息
- 实现时间: {ISO 8601}
- 实现者: Implementer Agent
- 模式: {NORMAL/REVIEW_FIX/RETRY_FIX}

---

## 一、完成的任务

| # | 任务 | 状态 | 文件 | 备注 |
|---|------|------|------|------|
| 1 | {任务1} | ✅ | {文件} | {备注} |
| 2 | {任务2} | ✅ | {文件} | {备注} |

---

## 二、涉及的文件

### 2.1 新增文件
| 文件 | 用途 |
|------|------|
| {文件1} | {用途} |

### 2.2 修改文件
| 文件 | 修改内容 |
|------|----------|
| {文件1} | {修改} |

---

## 三、问题记录

### 3.1 已解决的问题
| # | 问题 | 解决方案 |
|---|------|----------|
| 1 | {问题} | {方案} |

### 3.2 未解决的问题
| # | 问题 | 影响 | 建议 |
|---|------|------|------|
| 1 | {问题} | {影响} | {建议} |

---

## ⚠️ 产物完成后的强制操作（Implementer Agent 必须执行）

```markdown
## 完成后检查清单

- [ ] 1. 本产物已保存到 {项目路径}/.agent/harness/_implementation.md
- [ ] 2. 已触发 Quality Auditor 独立质量审核（拉起子Agent审核 _implementation.md）
- [ ] 3. 质量审核已通过（或已降级为自检模式）
- [ ] 4. 已更新接力棒：状态 IMPLEMENT ✅，下一步 VERIFY
- [ ] 5. 已确认所有代码已保存到文件系统（不是只在对话中）
- [ ] 6. 已确认所有设计中的任务都已完成（或明确标记为未完成）
- [ ] 7. 修改/新增文件清单与实际写入的文件一致

**阻断规则**：以上任一未勾选 → 不能进入 VERIFY 阶段

---

本文档由 Implementer Agent 自动生成 版本: 4.6 (ReqPlan-v3 v4.6) 时间: {ISO 8601}

---

## 四、_verification.md 模板

```markdown
# 验证报告

> 产物版本: v1.0 | 最后修改: {ISO 8601} | 修改记录: v1.0 初始版本

## 基本信息
- 验证时间: {ISO 8601}
- 验证者: Verifier Agent
- 关联设计: _design.md

---

## Layer 1: 静态检查

### 1.1 工具结果
| 工具 | 命令 | 结果 |
|------|------|------|
| pylint | `pylint app.py` | ✅ 通过 / ❌ 失败 |
| ruff | `ruff check .` | ✅ 通过 / ❌ 失败 |
| mypy | `mypy app.py` | ✅ 通过 / ❌ 失败 |

### 1.2 违规列表
| # | 问题 | 文件 | 行号 | 类型 |
|---|------|------|------|------|
| 1 | {问题} | {文件} | {行号} | {WARNING/ERROR} |

---

## Layer 2: 单元测试

### 2.1 测试结果
- 测试框架: pytest
- 总测试数: {数量}
- 通过数: {数量}
- 失败数: {数量}
- 覆盖率: {百分比}

### 2.2 失败的测试
| # | 测试 | 错误 |
|---|------|------|
| 1 | {测试名} | {错误信息} |

---

## Layer 3: 构建集成

### 3.1 构建结果
| 命令 | 结果 |
|------|------|
| `python -m py_compile` | ✅ 通过 / ❌ 失败 |
| `pip install -r requirements.txt` | ✅ 通过 / ❌ 失败 |

### 3.2 失败详情

{错误信息}

---

## Layer 4: 异常处理

### 4.1 测试场景
| # | 场景 | 预期 | 实际 | 状态 |
|---|------|------|------|------|
| 1 | 401 未授权 | 401 | 401 | ✅ |
| 2 | 403 禁止访问 | 403 | 403 | ✅ |
| 3 | 404 资源不存在 | 404 | 404 | ✅ |
| 4 | 400 参数错误 | 400 | 400 | ✅ |

### 4.2 失败场景
| # | 场景 | 预期 | 实际 | 问题 |
|---|------|------|------|------|
| 1 | {场景} | {预期} | {实际} | {问题} |

---

## Layer 5: 流程合规

### 5.1 产物检查
| # | 产物 | 存在 | 完整 |
|---|------|------|------|
| 1 | _analysis.md | ✅ | ✅ |
| 2 | _design.md | ✅ | ✅ |
| 3 | _implementation.md | ✅ | ✅ |

### 5.2 文档检查
| # | 检查项 | 状态 |
|---|--------|------|
| 1 | README 更新 | ✅ |
| 2 | API 文档更新 | ✅ |

---

## 综合判定

### 判定结果
**状态**: ✅ PASS / ❌ FAIL

### 错误分类
| # | 错误类型 | 数量 | 详情 |
|---|----------|------|------|
| 1 | ARCHITECTURE_VIOLATION | 0 | 架构/分层违规 |
| 2 | REVIEW_VIOLATION | 0 | 代码规范问题 |
| 3 | RUNTIME_FAILURE | 0 | 测试/运行失败 |
| 4 | ENVIRONMENT | 0 | 环境问题 |

### 下一步
- PASS → JUDGE → DONE ✅
- ARCHITECTURE → JUDGE → DESIGN(修复)
- REVIEW → JUDGE → IMPLEMENT(修复)
- RUNTIME & retry < 2 → JUDGE → IMPLEMENT(重试)
- retry >= 2 → JUDGE → FAILED ❌

---

## ⚠️ 产物完成后的强制操作（Verifier Agent 必须执行）

```markdown
## 完成后检查清单

- [ ] 1. 本产物已保存到 {项目路径}/.agent/harness/_verification.md
- [ ] 2. 已触发 Quality Auditor 独立质量审核（拉起子Agent审核代码 + _implementation.md）
- [ ] 3. 质量审核已通过（或已降级为自检模式）
- [ ] 4. 已更新接力棒：状态 VERIFY ✅，下一步 JUDGE
- [ ] 5. 已确认综合判定为明确的 PASS 或 FAIL
- [ ] 6. 如果 FAIL，已确认错误分类（ARCHITECTURE/REVIEW/RUNTIME/ENVIRONMENT）

**阻断规则**：以上任一未勾选 → 不能进入 JUDGE 阶段

---

本文档由 Verifier Agent 自动生成 版本: 4.6 (ReqPlan-v3 v4.6) 时间: {ISO 8601}

---

## 五、_baton.md 模板

```markdown
# 🔄 ReqPlan-v3 接力棒

## 元信息

| 字段 | 值 |
|------|-----|
| 项目 | {项目名称} |
| 开始时间 | {ISO 8601} |
| 最后更新 | {ISO 8601} |
| 当前状态 | {START/ANALYZE/CONFIRM/DESIGN/IMPLEMENT/VERIFY/JUDGE/DONE/ABORT/FAILED} |
| 模式 | {NORMAL/DESIGN_FIX/REVIEW_FIX/RETRY_FIX} |
| 重试计数 | {0/1/2} |
| design_fix_retry | {0/1/2} |

## 质量审核追踪

| 审核阶段 | 状态 | 分数 | 重试次数 | 报告文件 |
|---------|------|------|---------|---------|
| quality_audit_analysis | 未审核/已通过/已打回 | - | 0/2 | - |
| quality_audit_design | 未审核/已通过/已打回 | - | 0/2 | - |
| quality_audit_implement | 未审核/已通过/已打回 | - | 0/2 | - |
| quality_audit_verify | 未审核/已通过/已打回 | - | 0/2 | - |
| quality_audit_judge | 未审核/已通过/已打回 | - | - | - |

## 进度追踪

### 阶段完成情况

- [ ] START - 启动
- [ ] ANALYZE - 分析
- [ ] CONFIRM - 确认
- [ ] DESIGN - 设计
- [ ] IMPLEMENT - 实现
- [ ] VERIFY - 验证
- [ ] JUDGE - 判断

### 产物清单

- [ ] `.agent/harness/_analysis.md` - 分析报告
- [ ] `.agent/harness/_quality_audit_analysis.md` - 分析质量审核报告
- [ ] `.agent/harness/_design.md` - 设计文档
- [ ] `.agent/harness/_quality_audit_design.md` - 设计质量审核报告
- [ ] `.agent/harness/_implementation.md` - 实现摘要
- [ ] `.agent/harness/_quality_audit_implement.md` - 实现质量审核报告
- [ ] `.agent/harness/_verification.md` - 验证报告
- [ ] `.agent/harness/_quality_audit_verify.md` - 验证质量审核报告
- [ ] `.agent/harness/_quality_audit_judge.md` - 最终全局判定报告

### ⭐ 任务追踪

> 所有任务状态统一在此管理。

| # | 任务名称 | 状态 | 完成时间 | 备注 |
|---|---------|------|---------|------|
| 1 | {任务1} | ✅ 完成 | {时间} | {备注} |
| 2 | {任务2} | 🔄 进行中 | - | {备注} |
| 3 | {任务3} | ⏳ 待开始 | - | {备注} |

## 当前阶段详情

### {状态名称}

**进度**: {百分比}%
**已完成任务**: {列表}
**进行中任务**: {任务}
**待完成任务**: {列表}

## 问题记录

### ⚠️ 阻塞问题
{问题列表}

### 💡 待确认事项
{待确认事项}

## 下一步行动

### 立即执行（Next）
1. {任务1}
2. {任务2}

---

*最后更新: {ISO 8601}*

---

---

六、质量审核报告模板

6.1 审核报告通用模板

# 质量审核报告 - {阶段名}

## 基本信息
- 审核时间: {ISO 8601}
- 审核对象: {产物文件路径}
- 审核轮次: {第N次审核}
- 审核等级: {L1/L2/L3}
- 模式: {正常审核 / 自检模式（降级）}

## 一、阻断检查结果
| # | 阻断项 | 状态 | 证据引用 |
|---|--------|------|---------|
| 1 | {阻断项描述} | ✅ 无阻断 / ❌ 有阻断 | {产物中的具体引用} |

## 二、各维度评分

### 维度①：{维度名}（权重{百分比}%）
- 得分: {分数}/100
- 扣分明细:
  | # | 扣分项 | 扣分 | 原因 | 引用来源 |
  |---|--------|------|------|---------|
  | 1 | {缺失内容} | -{分数} | {为什么是问题} | {产物中的对应段落} |

### 维度②：...
（以此类推）

## 三、综合评分
- 加权总分: {计算过程} = {最终分数}
- 等级: A/B/C/D
- 判定: ✅ 通过 / ❌ 打回修复 / ❌ 打回重做

## 四、待修复问题清单

### P0 - 必须修复（严重问题）
| # | 问题描述 | 所在位置 | 建议修复方案 | ✅ 修复验证（重审时填写） |
|---|---------|---------|-------------|------------------------|
| 1 | {问题描述} | {产物中的具体章节或行号} | {修复指引} | 是否已修复: ✅/❌ 证据: {引用} |

### P1 - 建议完善
| # | 问题描述 | 所在位置 | 建议修复方案 | ✅ 修复验证（重审时填写） |
|---|---------|---------|-------------|------------------------|
| 1 | {问题描述} | {产物中的具体章节或行号} | {修复指引} | 是否已修复: ✅/❌ 证据: {引用} |

## 五、评分分布监控（由主Agent检查）
- 本次评分: {分数}
- 历史评分分布: {分数1}, {分数2}, {分数3}
- 是否触发告警: 是/否（连续3次≥90）
- 告警原因: {如果有}

---

*报告版本: 1.0 | 由 Quality Auditor Agent 自动生成*

6.2 文件命名规则

轮次	文件名	说明
第1次审核	_quality_audit_{phase}.md	首次审核（phase=analysis/design/implement/verify/judge）
第1次修复后重审	_quality_audit_{phase}_v2.md	重试第1次
第2次修复后重审	_quality_audit_{phase}_v3.md	重试第2次（之后FAILED）

各阶段（analysis/design/implement/verify/judge）的命名规则同理。

6.3 产物完成后的强制操作（Quality Auditor Agent 必须执行）

## 完成后检查清单

- [ ] 1. 本产物已保存到 {项目路径}/.agent/harness/_quality_audit_{phase}.md
- [ ] 2. 审核报告包含"阻断检查结果"章节
- [ ] 3. 审核报告包含"各维度评分"章节（L1模式可省略）
- [ ] 4. 审核报告包含"综合评分"章节（L1模式可省略）
- [ ] 5. 审核报告包含"待修复问题清单"章节（通过时可省略）
- [ ] 6. 包含"评分分布监控"章节
- [ ] 7. 每个扣分项有明确的引用来源

**阻断规则**：以上任一未勾选 → 审核报告无效