# harness-driven-requirement

**Repository Path**: c2harness/harness-driven-requirement

## Basic Information

- **Project Name**: harness-driven-requirement
- **Description**: 基于Harness的软件需求开发与管理
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-27
- **Last Updated**: 2026-06-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# harness-driven-requirement

## 1. 项目简介

基于 Harness 的需求管理框架，实现从需求池管理、需求分析、需求设计、需求变更到 PRD 生成的产品需求协作流程。本项目提供技能系统（Skills）和工作流（Workflows），支持需求澄清、阶段化设计、变更处理和原型生成。

### 1.1 核心特性

- **技能系统（Skills）**: 提供模块化的需求处理技能，包括需求澄清、模块需求生成、原型生成等
- **工作流系统（Workflows）**: 定义标准化的需求流程，覆盖需求分析、初步设计、详细设计、需求变更和总装配
- **需求池管理**: 通过需求池清单管理需求入口、状态和分流
- **PRD 章节产出**: 保留 11 个章节子工作流作为章节级或模块级局部重跑能力
- **原型生成**: 支持界面原型自动生成与描述规范
- **执行计划**: 功能状态追踪（feature_list.json）和进度管理

---

## 2. PM 如何使用

### 2.1 主流程概览

如果把这个空间当成 PM 的日常工作台，可以按下面这条主线理解：

```
需求池管理 → 需求分析 → 需求初步设计 → 需求详细设计 → PRD装配交付
    ↓           ↓             ↓               ↓              ↓
  条目登记     澄清定义      骨架设计         详细需求        完整PRD
```

对应关系如下：

| 阶段 | 入口 | 说明 |
|------|------|------|
| 需求池管理 | `docs/requirement-pool-files/需求池清单.md` + `requirement-prd-all.md` | 先登记需求条目，再在总入口中判断当前条目属于新增需求、需求变更还是直接进入设计 |
| 需求分析 | `requirement-analysis.md` | 对新增需求做澄清与定义，生成需求定义文档 |
| 需求初步设计 | `requirement-initial-design.md` | 优先生成第 2 章到第 5 章，完成目标、边界、功能清单和顶层设计 |
| 需求详细设计 | `requirement-detailed-design.md` | 生成第 6 章到第 11 章，必要时再进入章节或模块工作流 |
| PRD装配交付 | `requirement-prd-all.md` | 合并章节、检查一致性并输出完整 PRD |

`需求变更` 不属于这条主干串行终点。它是针对已有需求、已有章节或已有 PRD 的并行更新入口，通常在已有产物基础上进入 `requirement-change.md`，完成定向更新后再回到 PRD 装配交付。

#### 2.1.1 需求变更流程

**核心流程**：
```
变更请求 → requirement-change.md → 变更确认 → 影响与差异分析 → 更新受影响产物 → 按需更新原型 → requirement-prd-all.md → PRD 装配交付
```

---

**两条入口路径**：

| 路径类型 | 流程描述 | 适用场景 |
|---------|---------|----------|
| **客户/业务方路径** | 变更请求 → 登记到需求池 → requirement-change.md → ... | 外部需求，需走审批流程 |
| **内部优化路径** | 变更请求 → 直接进入 requirement-change.md → ... | 内部缺陷修复、优化 |

---

**关键决策点**：

1. **变更类型选择**
   - 新增需求变更：读取需求定义 + 核心业务场景
   - 设计变更：读取已完成的 PRD 章节
   - 原型变更：读取已有原型 + 相关 PRD

2. **影响范围判断**
   - 单模块：只更新该模块的 PRD
   - 多模块：批量更新相关模块
   - 顶层设计：先更新 `5-顶层设计.md`，再更新其他受影响章节

---

**关键产出物**：
- 变更描述 → 变更确认记录 → `影响与差异分析.md` → 更新的 `{模块名称}.md`/`.html` → 更新后的 `PRD.md`

### 2.2 PM 常用使用场景

PM 实际使用时，不需要先理解 11 个章节，也不需要先理解底层 Skill。可以直接按当前任务进入：

PM要做什么 → 需要用哪些工具 → 具体怎么操作 → 能得到什么产出。
---

#### 场景1：新项目启动

**业务场景描述**：
PM: "我有一个新项目，这是解决方案文档，需要快速搭出 PRD 骨架。"

**空间运行及产出**：
```
🛠️ 技能（Skills）：
  - requirement-clarifier（需求澄清）

📋 工作流（Workflows）：
  - requirement-analysis.md（需求分析）
  - requirement-initial-design.md（初步设计）

🚀 执行路径：
  1. 读取解决方案文档
  2. 调用 requirement-clarifier 技能澄清关键问题 → 生成需求定义文档（草稿）
  3. PM确认后，执行 requirement-initial-design.md 工作流一键生成 PRD 骨架：
     - 1-引言（自动填充）
     - 2-系统目标（从需求定义提取）
     - 3-机构用户权限定义（从需求定义提取）
     - 4-功能清单（草稿）
     - 5-顶层设计（从需求定义提取实体）
  4. PM确认骨架 → 保存

⏱ 目标：30分钟内出 PRD 骨架
🎯 产出：5个章节的草稿文件
```

---

#### 场景2：写用户管理模块的PRD需求

**业务场景描述**：
PM: "我只需要写用户管理这个模块的详细需求，其他模块已经写好了。"

**空间运行及产出**：
```
🛠️ 技能（Skills）：
  - functional-module-prd-generator（模块需求生成）
  - prototype-generator（原型生成，可选）

📋 工作流（Workflows）：
  - requirement-detailed-design.md（详细设计-单模块模式）

🚀 执行路径：
  1. 读取功能清单和顶层设计
  2. 调用 functional-module-prd-generator 技能，选择目标模块：用户管理
  3. 生成用户管理模块详细需求：
     - 模块概述 → 流程及说明 → UML 图 → 子功能详细描述
  4. PM审阅 → 修改 → 确认
  5. （可选）调用 prototype-generator 技能生成 HTML 原型

⏱ 目标：10分钟内出单模块详细需求
🎯 产出：6-功能性需求-章节拆分/用户管理.md
```

---

#### 场景3：新增用户管理模块的功能点：批量导入、导出

**业务场景描述**：
PM: "用户管理模块需要新增批量导入和导出功能，其他内容不用动。"

**空间运行及产出**：
```
🛠️ 技能（Skills）：
  - functional-module-prd-generator（模块需求更新）

📋 工作流（Workflows）：
  - requirement-change.md（增量补充模式）

🚀 执行路径：
  1. 读取 6-功能性需求-章节拆分/用户管理.md
  2. 执行 requirement-change.md 工作流（增量补充模式）
  3. 调用 functional-module-prd-generator 技能新增子功能：
     - 6.x.x 批量导入用户
     - 6.x.x 批量导出用户
  4. 更新相关内容：流程及说明 → 数据要素 → 业务规则 → 异常情况说明
  5. 检查影响范围 → 输出变更摘要
  6. PM确认 → 保存

⏱ 目标：15分钟内完成功能点新增
🎯 产出：更新后的 用户管理.md + 变更摘要
```

---

#### 场景4：用户管理，新增了一个实体字段，修改删除逻辑

**业务场景描述**：
PM: "User 实体新增了一个字段，同时删除逻辑需要调整，需要看这个变更会传播到哪些章节。"

**空间运行及产出**：
```
🛠️ 技能（Skills）：
  - functional-module-prd-generator（模块需求更新）

📋 工作流（Workflows）：
  - requirement-change.md（影响传播分析模式）

🚀 执行路径：
  1. 读取 5-顶层设计.md 的 User 实体定义
  2. 执行 requirement-change.md 工作流（影响传播分析模式）
  3. 自动推导传播路径：
     - User 实体字段 → 用户管理.md → 数据字典 → 角色权限 → 数据权限
     - 删除逻辑 → 用户管理.md（业务规则）
  4. 输出影响范围报告 → PM确认
  5. 调用 functional-module-prd-generator 技能批量更新受影响章节
  6. 输出变更摘要

⏱ 目标：10分钟内完成变更传播分析和更新
🎯 产出：变更影响范围报告 + 更新后的相关章节 + 变更摘要
```

---

#### 场景5：需求PRD评审会后改需求

**业务场景描述**：
PM: "评审会后，维度管理的删除规则需要修改，其他内容不用动。"

**空间运行及产出**：
```
🛠️ 技能（Skills）：
  - functional-module-prd-generator（模块需求更新）

📋 工作流（Workflows）：
  - requirement-change.md（定点修改模式）

🚀 执行路径：
  1. 执行 requirement-change.md 工作流（定点修改模式）
  2. 定位到 维度管理.md 中"删除维度"的"业务规则"段落
  3. 调用 functional-module-prd-generator 技能修改 R-DIM-xxx 规则描述
  4. 同步修改"异常情况说明"表格
  5. 检查影响范围 → 输出变更摘要
  6. PM确认 → 保存

⏱ 目标：5分钟内完成定点修改
🎯 产出：修改后的 维度管理.md + 变更摘要
```

---

#### 场景6：明天要演示，PM需要快速出原型，PRD后补

**业务场景描述**：
PM: "明天要演示用户管理功能，需要快速出原型，PRD 后面再补。"

**空间运行及产出**：
```
🛠️ 技能（Skills）：
  - prototype-generator（原型生成）

📋 工作流（Workflows）：
  - requirement-prototype.md（原型生成工作流）

🚀 执行路径：
  1. 检查 用户管理.md 是否存在
     - 存在 → 直接调用 prototype-generator 技能
     - 不存在 → 从功能清单+顶层设计快速生成简版PRD → 再生成原型
  2. 生成 用户管理.html（高保真 HTML 原型）
  3. PM确认原型 → 后续再补完整 PRD

⏱ 目标：5分钟内出可演示原型
🎯 产出：用户管理.html
```

---

#### 场景7：上线后客户反馈问题，新增需求点

**业务场景描述**：
PM: "上线后客户反馈了一个问题，需要新增一个需求点。"

**空间运行及产出**：
```
🛠️ 技能（Skills）：
  - functional-module-prd-generator（模块需求更新）

📋 工作流（Workflows）：
  - requirement-prd-all.md（总入口判断）
  - requirement-change.md（变更处理）

🚀 执行路径：
  1. 读取客户反馈内容
  2. 执行 requirement-prd-all.md 工作流（总入口）判断需求类型：
     - 缺陷修复 → requirement-change.md（修复模式）
     - 新增功能 → requirement-change.md（增量补充模式）
     - 需求优化 → requirement-change.md（优化模式）
  3. PM确认分流建议 → 执行 requirement-change.md 工作流：
     - 影响分析 → 调用 functional-module-prd-generator 技能更新受影响产物 → 变更摘要
  4. 返回 requirement-prd-all.md 重新装配 PRD

⏱ 目标：15分钟内完成需求点新增
🎯 产出：分流建议 + 更新后的相关章节 + 变更摘要
```

### 2.3 流程图说明

#### 2.3.1 主流程图怎么理解

`需求池管理 → 需求分析 → 需求初步设计 → 需求详细设计 → PRD装配交付` 表示的是 PM 在空间中的主使用顺序：

- 先在需求池中登记条目，并在总入口里完成前置判断
- 如果是新增需求，先做需求分析，澄清问题、目标和场景
- 分析稳定后先进入需求初步设计，再进入需求详细设计
- 最后把章节产物合并为完整 PRD

它表达的是“按阶段推进”的主线，不表示每次都必须从头走到尾。若是已有需求的局部修改，通常直接进入 `requirement-change.md`，完成定向更新后再回到 PRD 装配交付。

#### 2.3.2 材料到需求设计链路图怎么理解

这张链路图表达的是“从材料到需求设计”的关系：

- `需求池清单` 负责登记和分流
- `关联需求源文件` 负责提供最小原始材料
- `requirement-analysis` 负责把材料转成结构化需求定义
- `需求初步设计 / 需求详细设计` 负责继续生成 PRD 章节

重点不是“读取整个 source-files 目录”，而是“只读取当前需求条目关联的源文件”。

#### 2.3.3 BLP 分层并行流程图怎么理解

这张图表达的是 PRD 章节之间的依赖关系，不是 PM 的日常入口顺序：

- `Phase 1 / Phase 2`：先搭业务上下文和架构基线
- `Phase 3`：第 6 章到第 9 章之间有联动，需要迭代闭环
- `Phase 4`：在核心需求稳定后，再补接口和非功能
- `Phase 5 / Phase 6`：做一致性检查并输出最终 PRD

所以这张图更适合用来理解“章节依赖”，不是用来替代前面的 PM 场景入口说明。

---

## 3. 项目结构

```
harness-driven-requirement/
├── .trae/
│   ├── rules/              # 规则定义
│   ├── skills/             # 技能实现
│   │   ├── requirement-clarifier/  # 需求澄清技能
│   │   ├── functional-module-prd-generator/ # 模块需求生成技能
│   │   └── prototype-generator/     # 原型生成技能
│   ├── workflows/          # 工作流定义
│   │   ├── requirement-analysis.md   # 需求分析工作流
│   │   ├── requirement-change.md     # 需求变更工作流
│   │   ├── requirement-initial-design.md  # 需求初步设计工作流
│   │   ├── requirement-detailed-design.md # 需求详细设计工作流
│   │   ├── requirement-prd-all.md    # 产品需求总入口工作流
│   │   ├── requirement-prototype.md  # 原型工作流
│   │   └── requirement-prd-subworkflows/  # PRD 子工作流
│   ├── prompts/            # 提示词模板
│   └── context-packs/      # 上下文包（场景装配）
├── docs/
│   ├── templates/          # 文档模板
│   │   └── ppt/            # PPT模板
│   ├── requirement-prd-files/       # PRD 产出物
│   │   └── 章节产出物/      # 各章节产出物
│   ├── requirement-analysis-files/  # 需求分析文件
│   │   ├── 产出文件/        # 需求分析产出
│   │   ├── 过程文件/        # 过程记录
│   │   ├── 需求评审/        # 评审相关文件
│   │   └── 需求变更/        # 需求变更相关文件
│   ├── requirement-pool-files/      # 需求池清单
│   ├── requirement-prototype-files/  # 原型文件
│   │   ├── demo/            # 原型演示页面
│   │   └── ui/              # UI规范
│   ├── requirement-source-files/    # 需求源文件
│   ├── reference/          # 参考文档
│   ├── exec-plan/          # 执行计划
│   │   ├── feature_list.json  # 功能状态追踪（SSOT）
│   │   ├── progress.md        # 进度记录
│   │   └── session-handoff.md # 会话交接
│   ├── metrics/            # 运行留痕
│   │   ├── run-log.jsonl     # 运行日志
│   │   └── scenario-evaluation.md # 场景评估
│   └── README.md
├── scripts/                # 脚本工具
├── AGENTS.md               # 执行协议
└── README.md               # 项目说明
```

---

## 4. 技能系统（Skills）

### 4.1 可用技能

| 技能名称 | 用途 |
|---------|------|
| `requirement-clarifier` | 需求澄清，通过结构化提问将模糊需求转化为精确规格 |
| `functional-module-prd-generator` | 模块需求生成，围绕单模块生成或重写功能性需求文档 |
| `prototype-generator` | 原型生成，将功能描述转换为可视化 HTML 原型页面 |

### 4.2 技能优先级

```
requirement-clarifier            > 新增需求分析
functional-module-prd-generator > 单模块详细需求
prototype-generator             > 原型相关任务
```

---

## 5. 工作流系统（Workflows）

### 5.1 主工作流

#### 5.1.1 需求分析工作流 (requirement-analysis)

**目标**：拒绝伪需求，把一句话需求转化为严谨的需求定义文档。

**适用场景**：新增需求的澄清与定义阶段。

**执行步骤**：
1. **Phase 1**: 需求澄清 - 通过结构化提问将模糊需求转化为精确规格
2. **Phase 2**: 场景分析 - 分析业务背景、使用场景和用户角色
3. **Phase 3**: 需求定义生成 - 输出结构化的需求定义文档

**输入**：
- 原始需求资料（解决方案文档、用户故事等）
- 需求池清单条目

**输出**：
| 输出物 | 路径 |
|--------|------|
| 需求定义文档 | `docs/requirement-analysis-files/产出文件/成果物-需求定义文档.md` |
| 需求澄清问题清单 | `docs/requirement-analysis-files/产出文件/过程文件-需求澄清问题清单.md` |

---

#### 5.1.2 需求变更工作流 (requirement-change)

**目标**：已有需求的补充、修改和收紧，先做差异分析，再定向更新受影响章节、模块和页面。

**适用场景**：
- 已有需求补充功能点
- 评审意见导致的需求修订
- 版本规划下的已有需求增量调整
- 顶层设计变更后的影响传播

**不适用场景**：
- 全新需求从 0 到 1 定义
- 原需求边界被彻底推翻

**执行步骤**：
1. **登记需求变更** - 更新需求变更单，明确变更标题、类型、原因和影响范围
2. **识别差异并评估影响** - 拆出差异类型（新增/修改/删除），判断影响对象
3. **确定处理方式** - 局部修订 / 增量补充 / 跨章节重构 / 全量重生
4. **定向更新文档** - 只更新受影响章节和模块
5. **定向更新原型** - 页面级微调，不整站重刷
6. **留痕与闭环** - 记录变更状态和风险复核

**输入**：
- 本次变更说明、评审意见或版本规划内容
- 已有需求对应的分析文档或 PRD 章节
- 受影响页面的原型文件（按需）

**输出**：
| 输出物 | 路径 |
|--------|------|
| 需求变更单 | `docs/requirement-analysis-files/需求变更/需求变更单.md` |
| 影响与差异分析 | `docs/requirement-analysis-files/需求变更/影响与差异分析.md` |
| 更新后的 PRD 章节 | `docs/requirement-prd-files/章节产出物/` |
| 更新后的原型页面 | `docs/requirement-prototype-files/demo/pages/` |

**变更粒度判断**：
| 变更粒度 | 典型场景 | 默认处理方式 |
|----------|----------|--------------|
| 章节级变更 | 顶层设计整体调整、权限模型口径调整 | 只更新受影响章节 |
| 模块级变更 | 某个模块补充 2 个功能点 | 只更新目标模块及其联动章节 |
| 规则/字段级变更 | 删除规则、审批规则、字段新增、校验调整 | 只更新受影响段落、表格、页面 |

---

#### 5.1.3 需求初步设计工作流 (requirement-initial-design)

**目标**：完成"目标、边界、模块、顶层架构"四类产物，生成 PRD 骨架。

**适用场景**：新项目启动，需要快速搭出 PRD 骨架。

**执行模式**：
- **标准模式**：系统目标 → 机构用户权限定义 → 功能清单 → 顶层设计
- **骨架优先模式**：功能清单 → 顶层设计 → 系统目标 → 机构用户权限定义

**输入**：
- `requirement-analysis.md` 的产出文件（需求定义文档）
- 原始需求资料

**输出**：
| 输出物 | 路径 |
|--------|------|
| 2-系统目标 | `docs/requirement-prd-files/章节产出物/2-系统目标.md` |
| 3-机构用户权限定义 | `docs/requirement-prd-files/章节产出物/3-机构用户权限定义.md` |
| 4-功能清单 | `docs/requirement-prd-files/章节产出物/4-功能清单.md` |
| 5-顶层设计 | `docs/requirement-prd-files/章节产出物/5-顶层设计.md` |

**阶段通过标准**：
- 至少已形成稳定的模块树
- 顶层设计中的核心实体、模块关系和主流程可支撑后续详细设计

---

#### 5.1.4 需求详细设计工作流 (requirement-detailed-design)

**目标**：完成"模块级需求、字典、权限、接口、非功能"产物。

**适用场景**：
- 初次完整产出详细设计
- 只编写或修改某个模块的详细需求
- 评审后只重跑受影响模块

**执行模式**：
- **全章模式**：生成第 6 章到第 11 章全部内容
- **单模块模式**：只生成或重跑目标模块

**执行步骤**：
1. **功能性需求** - 按模块生成详细需求（第 6 章）
2. **数据字典配置表** - 定义系统数据字典（第 7 章）
3. **角色权限功能说明** - 定义角色权限模型（第 8 章）
4. **数据权限说明** - 定义数据范围权限（第 9 章）
5. **外部接口说明** - 定义系统外部接口（第 10 章）
6. **非功能性需求** - 定义性能、安全等非功能要求（第 11 章）

**输入**：
- 初步设计产出（第 2~5 章）
- 功能清单（按需）
- 目标模块的 PRD（单模块模式）

**输出**：
| 输出物 | 路径 |
|--------|------|
| 6-功能性需求 | `docs/requirement-prd-files/章节产出物/6-功能性需求-章节拆分/` |
| 7-数据字典配置表 | `docs/requirement-prd-files/章节产出物/7-数据字典配置表.md` |
| 8-角色权限功能说明 | `docs/requirement-prd-files/章节产出物/8-角色权限功能说明.md` |
| 9-数据权限说明 | `docs/requirement-prd-files/章节产出物/9-数据权限说明.md` |
| 10-外部接口说明 | `docs/requirement-prd-files/章节产出物/10-外部接口说明.md` |
| 11-非功能性需求 | `docs/requirement-prd-files/章节产出物/11-非功能性需求.md` |

**局部重跑原则**：
- 第 6 章默认支持单模块生成和单模块重跑
- 第 7~11 章仅在该模块变更会影响对应章节时才更新
- 不因单模块修改而默认重跑全章

---

#### 5.1.5 产品需求工作流 (requirement-prd-all)

**目标**：作为总入口导航，负责按场景分流并在最后完成 PRD 装配与交付。

**适用场景**：
- 新项目启动的完整流程
- 最终交付完整 PRD
- 需求变更后的重新装配

**执行阶段**：
```
Phase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4
  ↓          ↓          ↓          ↓         ↓
需求池判断  需求分析   两阶段设计   PRD装配   验证与迭代
```

| 阶段 | 工作流 | 描述 |
|------|--------|------|
| Phase 0 | requirement-prd-all.md（入口判断） | 在总入口中先判断当前条目属于新增需求、需求变更还是直接进入设计 |
| Phase 1 | 需求分析 | 对新增需求做澄清与定义，生成需求定义文档 |
| Phase 2 | 两阶段设计 | 优先按初步设计和详细设计主流程推进，必要时再进入章节或模块工作流 |
| Phase 3 | PRD装配交付 | 合并章节、检查一致性并输出完整 PRD |
| Phase 4 | 验证与迭代 | 交付前自检与优化循环 |

**输入**：
- 11 个章节产出物
- 需求变更相关文件（变更场景）

**输出**：
| 输出物 | 路径 |
|--------|------|
| PRD.md | `docs/requirement-prd-files/PRD.md` |
| AC-Checklist.md | `docs/requirement-prd-files/AC-Checklist.md` |
| 章节产出物 | `docs/requirement-prd-files/章节产出物/` |

**验证检查项**：
- **逻辑完整性检查**：状态流转图完整、核心业务规则已编号、异常场景处理策略明确
- **数据规范性检查**：数据类型正确、字段必填属性明确、枚举值清单完整
- **权限与安全检查**：权限说明完整覆盖四级授权机制、敏感数据已脱敏、权限边界检查机制存在

---

#### 5.1.6 原型工作流 (requirement-prototype)

**目标**：把 PRD 模块文档转成可运行的单文件 HTML 原型。

**适用场景**：
- 新增需求的模块原型生成
- 已有需求变更后的受影响页面微调
- 快速生成可演示原型

**不适用场景**：
- 纯需求分析
- 全量 PRD 生成
- 脱离 PRD 直接凭口头描述拼页面

**执行模式**：
- **模式 A（新增需求）**：直接生成新的 `{模块名称}.html`
- **模式 B（需求变更）**：只更新受影响页面，不重刷无关模块

**执行步骤**：
1. **确认范围** - 判断是新增需求还是需求变更，确认模块名和输出路径
2. **调用 prototype-generator 技能** - 执行四层流水线：
   - Layer 1（需求解析）：解析模块元信息、提取子功能和数据要素
   - Layer 2（布局映射）：推断页面类型、推荐布局
   - Layer 3（组件选型）：建立数据类型到组件的映射
   - Layer 4（代码生成）：生成 Mock 数据、输出单文件 HTML
3. **执行页面级约束** - 确保技术栈和代码规范符合要求
4. **需求变更场景下的局部处理** - 只更新受影响页面和功能

**输入**：
| 输入类型 | 路径 | 说明 |
|----------|------|------|
| 模块 PRD | `docs/requirement-prd-files/章节产出物/6-功能性需求-章节拆分/{模块名称}.md` | 必需输入，原型生成的直接依据 |
| 功能清单 | `docs/requirement-prd-files/章节产出物/4-功能清单.md` | 用于菜单、模块边界校验 |
| 已有原型 | `docs/requirement-prototype-files/demo/pages/{模块名称}.html` | 需求变更时用于局部微调 |
| 变更分析 | `docs/requirement-analysis-files/需求变更/影响与差异分析.md` | 需求变更场景下读取 |

**输出**：
| 输出物 | 路径 |
|--------|------|
| 单模块原型 | `docs/requirement-prototype-files/demo/pages/{模块名称}.html` |

**技术栈**：
| 技术栈项 | 默认值 |
|----------|--------|
| 框架 | Vue 3 (CDN) |
| UI组件库 | Element Plus (CDN) |
| CSS方案 | Tailwind CSS (CDN, preflight: false) |
| 构建方式 | 零构建，单文件 HTML |

**页面级约束**：
- CDN 顺序正确：Vue 3 → Element Plus CSS → Element Plus JS → Icons → Tailwind
- `ElementPlusIconsVue` 必须在 `app.use(ElementPlus)` 之前全局注册
- 组件标签使用全闭合写法
- `el-switch` 不输出 `active-text` 和 `inactive-text`
- 操作反馈使用 `ElMessage`，禁止使用 `alert`
- 弹窗类操作使用 `el-dialog`

### 5.2 执行链路详解

#### 5.2.1 Phase 0 → Phase 1 → Phase 2 链路

```
[需求池清单]
    ↓
识别当前需求条目
    ↓
[关联需求源文件]
    ↓
需求分析 (requirement-analysis)
    ↓
requirement-analysis-files/产出文件/需求定义文档.md
    ↓
需求初步设计 / 需求详细设计
```

#### 5.2.2 Phase 2 → Phase 3 链路

```
阶段主流程和章节/模块工作流产出章节文件
    ↓
合并到 章节产出物/ 目录
    ↓
Phase 3: 按 PRD 模板合并 → 一致性检查
    ↓
最终交付物: PRD.md
```

### 5.3 PRD 章节依赖关系

```
┌─────────────────────────────────────────────────────────────────────┐
│                     BLP 分层并行流程                                 │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  Phase 1: 业务上下文构建（并行）                                   │
│  ┌─────────┐ ┌─────────┐                                           │
│  │ 1-引言  │ │ 2-系统目标│                                          │
│  └─────────┘ └─────────┘                                            │
│                     ↓                                                │
│  Phase 2: 架构基线定义（并行）                                      │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐                                │
│  │3-机构权限│ │4-功能清单│ │5-顶层设计│                               │
│  └─────────┘ └─────────┘ └─────────┘                                │
│                     ↓                                                │
│  Phase 3: 核心需求迭代（反馈闭环）                                  │
│  ┌─────────────────────────────────────┐                           │
│  │ 6-功能性需求 ←→ 7-数据字典配置表 ←→ │                           │
│  │ 8-角色权限功能说明 ←→ 9-数据权限说明│ │                           │
│  │          （迭代 2~3 轮）             │                           │
│  └─────────────────────────────────────┘                           │
│                     ↓                                                │
│  Phase 4: 技术细节完善（并行）                                      │
│  ┌─────────┐ ┌─────────┐                                           │
│  │10-外部接口│ │11-非功能需求│                                      │
│  └─────────┘ └─────────┘                                            │
│                     ↓                                                │
│  Phase 5: 质量校验网关                                              │
│  规则ID校验 | 接口一致性 | 权限完整性                                │
│                     ↓                                                │
│  Phase 6: 输出 PRD 文档                                             │
│  PRD.md                                                             │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

**分层说明**：

| Phase | 章节 | 说明 |
|-------|------|------|
| Phase 1 | 1, 2 | 业务上下文构建，并行执行 |
| Phase 2 | 3, 4, 5 | 架构基线定义，并行执行 |
| Phase 3 | 6, 7, 8, 9 | 核心需求迭代，闭环反馈（2~3 轮） |
| Phase 4 | 10, 11 | 技术细节完善，并行执行 |
| Phase 5 | - | 质量校验网关 |
| Phase 6 | - | 输出最终文档 |

**迭代闭环（Phase 3）**：

> **核心需求迭代（反馈闭环）**: 功能性需求 ↔ 数据字典 ↔ 权限设计

| 迭代路径 | 说明 |
|----------|------|
| 功能性需求 ↔ 数据字典配置表 | 数据要素中的字段类型、枚举值同步；枚举值变化反写校验规则 |
| 功能性需求 ↔ 权限设计 | 功能模块的操作权限同步；权限模型变化影响数据范围 |
| 数据字典 ↔ 权限设计 | 枚举值作为权限条件时的联动 |

**迭代触发条件**：
- 数据要素中新增/修改了枚举字段
- 业务规则中新增了权限校验要求
- 数据范围定义发生变化

**迭代终止条件**：
- 连续两轮迭代无内容变化
- 用户确认闭环检查通过

**依赖说明**：
- Phase 1 → Phase 2：前置输入
- Phase 2 → Phase 3：架构基线完成后进入核心需求迭代
- Phase 3 → Phase 4：核心需求闭环后进入技术细节
- Phase 4 → Phase 5 → Phase 6：串行收尾

### 5.4 PRD 子工作流

| 子工作流 | 对应章节 |
|---------|----------|
| `requirement-prd-subworkflow-1-引言` | 1-引言 |
| `requirement-prd-subworkflow-2-系统目标` | 2-系统目标 |
| `requirement-prd-subworkflow-3-机构用户权限定义` | 3-机构用户权限定义 |
| `requirement-prd-subworkflow-4-功能清单` | 4-功能清单 |
| `requirement-prd-subworkflow-5-顶层设计` | 5-顶层设计 |
| `requirement-prd-subworkflow-6-功能性需求` | 6-功能性需求 |
| `requirement-prd-subworkflow-7-数据字典配置表` | 7-数据字典配置表 |
| `requirement-prd-subworkflow-8-角色权限功能说明` | 8-角色权限功能说明 |
| `requirement-prd-subworkflow-9-数据权限说明` | 9-数据权限说明 |
| `requirement-prd-subworkflow-10-外部接口说明` | 10-外部接口说明 |
| `requirement-prd-subworkflow-11-非功能性需求` | 11-非功能性需求 |

### 5.5 功能性需求子工作流详解 (requirement-prd-subworkflow-6)

> **目标**: 生成 PRD 第 6 章功能性需求部分

**产出目录结构**:
```
[输出目录]/requirement-prd-files/章节产出物/
├── 6-功能性需求.md              # 最终合并文件
└── 6-功能性需求-章节拆分/       # 拆分章节产出物
    └── {模块名称}.md           # 功能模块详细描述
```

**执行步骤**:

| 步骤 | 名称 | 说明 |
|------|------|------|
| 步骤 1 | 选择功能模块 | 读取功能清单，选择要生成的模块及生成策略 |
| 步骤 2 | 解析前置输入 | 读取需求定义、用户故事、验收标准等 |
| 步骤 3 | 生成功能模块 | 逐个生成模块详细描述（模块概述→流程→UML→子功能） |
| 步骤 4 | 合并最终文件 | 将拆分文件合并为完整的 6-功能性需求.md |

**生成策略**:

| 策略 | 说明 | 适用场景 |
|:----:|------|----------|
| 策略A | 先生成 1 个模板模块，确认质量后再批量生成 | 首次生成，验证模板质量 |
| 策略B | 按优先级批量生成 P0 模块 | 追求效率，快速完成核心功能 |
| 策略C | 每次只生成 1 个模块，逐个确认 | 追求质量，严格控制每个模块 |

**模块详细描述结构** (每个 `{模块名称}.md`):

```
## {模块序号} {模块名称}功能模块
### {模块序号}.1 流程及说明 (泳道图/流程图)
### {模块序号}.2 UML图 (用例图/时序图/状态机)
### {模块序号}.3 {子功能1}
    - 功能概述（表格）
    - 功能详细逻辑说明
    - 界面原型
    - 数据要素（16列表格）
    - 业务规则
    - 异常情况说明
### {模块序号}.4 {子功能2}
...
```

### 5.6 原型工作流 (requirement-prototype)

基于功能描述文档，生成高保真 HTML 原型页面。

**前置输入**：
- 功能模块清单（4-功能清单.md）
- 功能性需求-章节拆分/{模块名称}.md（业务需求文档）
- 界面原型描述规范（UI规范）

**技术栈**：
| 技术栈项 | 默认值 |
|----------|--------|
| 框架 | Vue 3 (CDN) |
| UI组件库 | Element Plus (CDN) |
| CSS方案 | Tailwind CSS (CDN) |
| 构建方式 | 零构建，单文件 HTML |

**四层流水线架构**：

| Layer | 名称 | 输入 | 输出 |
|-------|------|------|------|
| Layer 1 | 需求解析层 | 业务需求.md | 结构化需求JSON |
| Layer 2 | 布局映射层 | 结构化需求JSON + UI规范 | 页面结构定义 |
| Layer 3 | 组件选型层 | 页面结构 + 数据要素 + 业务规则 | 组件映射表 |
| Layer 4 | 代码生成层 | 所有上层输出 + 参考模板 | 单文件HTML原型 |

**组件映射规则**：

| 数据类型 | Element Plus 组件 |
|----------|------------------|
| UUID | `<span>` / `el-select` / `el-tree-select` |
| String (≤50) | `el-input` + `maxlength` |
| String (长文本) | `el-input type="textarea"` |
| Enum (≤5) | `el-radio-group` |
| Enum (>5) | `el-select` |
| Integer | `el-input-number` |
| Boolean | `el-switch` |
| DateTime | `el-date-picker` |

**Checkpoint 检查清单**：
- [ ] 所有子功能均已提取
- [ ] 每个子功能的页面类型已推断
- [ ] 数据要素表格已解析为结构化字段
- [ ] 业务规则已转化为组件约束
- [ ] UI规范P0检查表全部通过
- [ ] 浏览器直接打开可正常运行

---

## 6. 文档模板

### 6.1 模板类型

| 模板 | 路径 | 用途 |
|------|------|------|
| PRD 章节模板 | `docs/templates/prd-chapter-template.md` | PRD 章节编写模板 |
| PRD 完整模板 | `docs/templates/prd-template.md` | PRD 完整文档模板 |
| PRD 模型模板 | `docs/templates/prd-model-template.md` | 数据模型模板 |
| 业务过程模板 | `docs/templates/business-process-template.md` | 业务流程模板 |
| 字段列表模板 | `docs/templates/field-list-template.md` | 字段定义模板 |
| 需求确认单 | `docs/requirement-analysis-files/需求评审/需求确认单.md` | 评审确认模板 |

### 6.2 使用方式

```bash
# 基于模板创建章节
cp docs/templates/prd-chapter-template.md docs/requirement-prd-files/章节产出物/6-功能性需求.md
```

---

## 7. 执行计划

### 7.1 功能状态追踪

`docs/exec-plan/feature_list.json` 是功能状态的 **SSOT（单一数据源）**。

| 字段 | 说明 |
|------|------|
| `id` | 功能唯一标识 |
| `name` | 功能名称 |
| `status` | 开发状态 |
| `priority` | 优先级 |

### 7.2 进度记录

`docs/exec-plan/progress.md` 记录当前会话进度。

### 7.3 会话交接

`docs/exec-plan/session-handoff.md` 用于多代理场景下的上下文交接。

---

## 8. 治理体系

空间治理的目标不是增加流程负担，而是保证三件事：

- 需求入口清楚，不把原始材料直接当成正式需求
- 上下文输入可控，不因为全量读取导致 Token 成本失控
- 产物更新可追溯，不因为局部修改造成章节之间互相打架

### 8.1 治理对象

当前空间治理聚焦 5 类对象：

1. 需求入口  
通过 `docs/requirement-pool-files/需求池清单.md` 管理需求条目、状态和下一步入口。

2. 原始材料  
通过 `docs/requirement-source-files/` 管理解决方案、原始需求、补充资料等输入来源。

3. 工作流与规则  
通过 `.trae/workflows/`、`.trae/rules/` 管理场景入口、执行边界和上下文装配规则。

4. 需求产物  
通过 `docs/requirement-analysis-files/`、`docs/requirement-prd-files/`、`docs/requirement-prototype-files/` 管理分析、PRD 和原型产物。

5. 运行留痕  
通过 `docs/metrics/`、`docs/exec-plan/` 管理 Token 留痕、场景评估、进度和交接记录。

### 8.2 治理原则

当前空间建议固定遵循以下原则：

1. 入口治理优先  
所有新输入先进入需求池，不直接冲进分析、设计或变更流程。

2. 最小上下文优先  
只读取当前任务必需文件，不读取整个目录，不默认读取全量 PRD 和全量原型。

3. 产物边界清晰  
需求分析、需求变更、PRD 章节、原型页面各自负责自己的产物，不跨边界混写。

4. 变更先分析后更新  
已有需求调整时，先补 `影响与差异分析.md`，再定向更新受影响产物。

5. 留痕先于优化  
没有运行记录，就没有后续优化依据。高成本任务必须留下输入规模、轮次和结果说明。

### 8.3 如何治理空间

#### 8.3.1 入口治理

- 使用 `docs/requirement-pool-files/需求池清单.md` 统一登记需求
- 使用 `docs/templates/intake-template.md` 补齐结构化输入
- 使用 `requirement-prd-all.md` 作为总入口，判断当前条目是新增需求、需求变更还是直接进入设计

#### 8.3.2 上下文治理

- 依照 `.trae/rules/context-assembly-rule.md` 装配上下文
- 新增需求默认读取：需求池条目 + 关联源文件 + 必要模板
- 需求变更默认读取：变更单 + 影响与差异分析 + 受影响章节
- 不允许把 `docs/requirement-source-files/`、`docs/requirement-prd-files/`、`docs/requirement-prototype-files/` 整目录当默认输入

#### 8.3.3 产物治理

- 需求分析产物统一进入 `docs/requirement-analysis-files/`
- PRD 章节产物统一进入 `docs/requirement-prd-files/章节产出物/`
- 原型产物统一进入 `docs/requirement-prototype-files/`
- 需求变更产物统一进入 `docs/requirement-analysis-files/需求变更/`
- 同一类产物的命名、目录和引用路径尽量固定，不临时发散

#### 8.3.4 质量治理

每次局部修改后，至少检查以下一致性：

- 功能清单是否与模块详细需求一致
- 顶层设计字段变化是否传播到受影响模块
- 角色权限、数据权限、接口说明是否需要联动更新
- README、workflow、rule 中的说明口径是否一致

#### 8.3.5 运营治理

- `docs/metrics/run-log.jsonl`：记录任务时间、场景、输入输出、轮次、Token 等运行留痕
- `docs/metrics/scenario-evaluation.md`：按新增需求、需求变更等场景做效果评估
- `docs/exec-plan/feature_list.json`：记录空间能力建设项
- `docs/exec-plan/progress.md`：记录当前推进进度
- `docs/exec-plan/session-handoff.md`：记录上下文交接信息

### 8.4 最小治理动作清单

如果只做极简治理，建议每次任务至少执行下面 5 个动作：

1. 先确认需求是否已登记到需求池
2. 先确认当前任务属于新增需求还是需求变更
3. 先确认本次只读取了必要文件，而不是整个目录
4. 先确认修改后需要联动更新哪些章节、模块或原型
5. 先记录一次运行留痕，再讨论优化

---

## 9. 使用说明

### 9.1 基本流程

```
需求池判断 → 需求分析 → 两阶段设计 → 合并生成
    ↓           ↓           ↓          ↓
需求池清单   requirement   initial /   PRD模板
             -analysis     detailed       ↓
                                      完整PRD文档
```

### 9.2 技能调用示例

```text
# 需求澄清调用 requirement-clarifier
模糊需求 → requirement-clarifier → 精确规格

# 原型生成调用 prototype-generator
功能描述 → prototype-generator → HTML原型
```

### 9.3 阶段控制规则

1. **未完成需求池判断** → 禁止直接进入正式分析或设计
2. **未完成需求分析** → 禁止新增需求直接进入详细设计
3. **PRD 章节未通过验证** → 禁止合并
4. **文档未通过一致性检查** → 禁止进入下一阶段

### 9.4 全量需求生成 vs 增量需求生成

#### 9.4.1 全量需求生成

适用于**新系统或从零开始**的场景，完整执行所有 Phase。

| 阶段 | 说明 |
|------|------|
| Phase 1 | 需求分析（需求澄清、需求定义） |
| Phase 2 | 优先按需求初步设计和需求详细设计主流程推进，必要时再进入章节子工作流 |
| Phase 3 | 核心需求迭代（2~3 轮闭环） |
| Phase 4 | 技术细节完善 |
| Phase 5 | 质量校验 |
| Phase 6 | 合并生成 PRD.md |

**建议**：首次生成使用**策略A**（先生成1个模板模块确认质量）

#### 9.4.2 增量需求生成

适用于**需求变更、功能迭代**场景，只更新受影响的部分。

**增量类型与影响范围**：

| 增量类型 | 影响章节 | 处理方式 |
|----------|----------|----------|
| 新增功能模块 | 4-功能清单、6-功能性需求 | 新增模块走独立模块子工作流 |
| 功能变更 | 对应模块的 6-N.md | 重新生成该模块 → 触发 Phase 3 迭代 |
| 数据字典变更 | 7-数据字典配置表 | 评估影响范围 → 联动更新相关模块数据要素 |
| 权限模型变更 | 3、8、9 | 权限变更需联动检查 6、7 |
| 非功能需求变更 | 11-非功能性需求 | 独立更新，无需联动 |

**增量检测规则**：

| 触发条件 | 联动影响 |
|----------|----------|
| 4-功能清单.md 有新增/删除模块 | 触发 6-功能性需求相应模块的 新增/移除 |
| 6-功能性需求-章节拆分/{模块}.md 变更 | 触发 Phase 3 迭代闭环，检查 7、8、9 是否联动 |
| 7-数据字典配置表.md 变更 | 反查引用该字典的模块，同步更新数据要素 |
| 3-机构用户权限定义.md 变更 | 联动 8、9，评估对 6 的影响 |
| 章节 10、11 变更 | 独立变更，无需联动其他章节 |

**迭代终止条件**：
- 连续两轮迭代无内容变化
- 用户确认闭环检查通过

### 9.5 执行协议

详见 [AGENTS.md](AGENTS.md)，包含完整的执行规则和约束。

---

## 10. 参与贡献

1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 提交代码（遵循项目编码规范）
4. 新建 Pull Request
5. 通过代码审查

---

## 11. 许可证

本项目采用 MIT 许可证，详见 LICENSE 文件。