260 lines
9.0 KiB
Markdown
260 lines
9.0 KiB
Markdown
# requirement-generator-v1 - 开发文档
|
||
|
||
## 核心设计理念
|
||
|
||
设计原则:
|
||
|
||
1. **动态适应用户能力**: 业务语言优先，通过观察用户回答动态评估其技术深度，切换语言风格
|
||
2. **允许用户中途介入**：允许用户中途完全介入，及时修正
|
||
3. **多专家独立评审**：4位专家从不同视角独立评审，确保需求覆盖全面
|
||
4. **用户需求基准原则**：以用户原始需求为最高准则，专家建议不可违背用户核心需求
|
||
5. **最终校验确保质量**：确保最终的需求文档以客观、陈述性输出，前后逻辑闭环，无明显矛盾
|
||
|
||
## 执行流程概览
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph Phase1_4["阶段 1-4: 需求生成"]
|
||
A[用户描述] --> B[项目类型判断]
|
||
B --> C[智能访谈]
|
||
C --> D[生成 requirement.md]
|
||
end
|
||
|
||
subgraph Phase5["阶段 5: 用户交互"]
|
||
D --> E{用户选择}
|
||
E -->|修改| F[修改文档]
|
||
F --> E
|
||
E -->|结束| G[流程结束]
|
||
end
|
||
|
||
subgraph Phase6["阶段 6: 多角色评审"]
|
||
E -->|进入评审| H[领域识别]
|
||
|
||
subgraph Review["独立评审"]
|
||
H --> I1[开发专家]
|
||
H --> I2[产品经理]
|
||
H --> I3[AI专家]
|
||
H --> I4[领域专家]
|
||
end
|
||
|
||
I1 & I2 & I3 & I4 --> L{决策模式}
|
||
L -->|用户确认| M1[req_consolidator]
|
||
L -->|自动应用| M2[req_auto_consolidator]
|
||
M1 & M2 --> N[requirement_final.md]
|
||
N --> O[质量审查]
|
||
O --> P[输出最终总结]
|
||
end
|
||
```
|
||
|
||
## 阶段详细说明
|
||
|
||
### 阶段 1-4: 需求生成
|
||
|
||
```
|
||
用户描述 → 项目类型判断 → 智能访谈 → 生成需求文档(requirement.md)
|
||
```
|
||
|
||
### 阶段 5: 用户交互
|
||
|
||
系统展示文档概览，询问用户选择下一步操作：
|
||
- **修改**: 用户编辑或提出修改建议，完成后再次询问
|
||
- **进入多角色评审**: 进入阶段6
|
||
- **结束**: 直接使用当前版本
|
||
|
||
### 阶段 6: 多角色评审
|
||
|
||
#### 6.1 领域识别与角色生成
|
||
|
||
读取 requirement.md，分析项目领域特征，生成领域专家角色定义，保存到 `temp/domain_role.md`。
|
||
|
||
#### 6.2 独立评审（并行）
|
||
|
||
4位专家并行评审 requirement.md：
|
||
|
||
| 专家 | 输出文件 | 评审重点 |
|
||
|------|----------|----------|
|
||
| 开发专家 | `temp/review_dev.json` | 技术可行性、架构、性能、风险 |
|
||
| 产品经理 | `temp/review_pm.json` | 业务目标、用户价值、场景完整性 |
|
||
| AI专家 | `temp/review_ai.json` | 智能化需求合理性、AI能力边界 |
|
||
| 领域专家 | `temp/review_domain.json` | 领域合规性、行业规范、特殊要求 |
|
||
|
||
#### 6.3 决策模式选择
|
||
|
||
询问用户选择处理方式：
|
||
- **用户确认模式**: 调用 `req_consolidator`，逐项与用户确认
|
||
- **自动应用模式**: 调用 `req_auto_consolidator`，自动评估并应用
|
||
|
||
#### 6.4 汇总整合
|
||
|
||
汇总Agent读取文件：
|
||
|
||
| 类别 | 文件 | 数量 |
|
||
|------|------|------|
|
||
| 用户需求基准 | `temp/interview_result.json` | 1 |
|
||
| 原始需求文档 | `requirement.md` | 1 |
|
||
| 评审结果 | `temp/review_*.json` | 4 |
|
||
|
||
**合并决策规则**：
|
||
1. **可以采纳**: 优化补充用户需求、细化实现细节的建议
|
||
2. **谨慎采纳**: 与用户需求有出入但专家一致认同的建议
|
||
3. **禁止采纳**: 完全背离用户原始需求的建议（即使专家全员同意）
|
||
|
||
#### 6.5 质量审查
|
||
|
||
调用 `review_report` 检查最终文档：
|
||
- 文档结构是否符合模板（不能有多余章节）
|
||
- 客观性（无评审标注、讨论性词汇）
|
||
- 逻辑严谨性（前后无矛盾）
|
||
- 闭环性（功能描述完整）
|
||
- 业务完整性（无"待确认"的业务问题）
|
||
|
||
## Agent 协作架构
|
||
|
||
### 需求生成 Agents (阶段1-4)
|
||
|
||
| Agent | 职责 | 关键能力 |
|
||
|-------|------|---------|
|
||
| **project_type_matcher** | 项目类型识别 | 语义匹配，置信度分级 |
|
||
| **req_interviewer** | 智能访谈 | 动态评估技术深度，业务到技术转化 |
|
||
| **req_writer** | 文档生成 | 模板驱动，决策标注 |
|
||
|
||
### 评审 Agents (阶段6)
|
||
|
||
| Agent | 视角 | 重点 |
|
||
|-------|------|------|
|
||
| **dev_expert_reviewer** | 技术 | 可行性、架构、性能、风险 |
|
||
| **pm_reviewer** | 业务 | 目标、价值、场景、验收标准 |
|
||
| **ai_expert_reviewer** | 智能化 | AI能力边界、智能化合理性 |
|
||
| **domain_expert_reviewer** | 领域 | 合规性、行业规范、特殊要求 |
|
||
| **req_consolidator** | 整合 | 用户确认模式，多轮交互 |
|
||
| **req_auto_consolidator** | 整合 | 自动评估模式，无用户交互 |
|
||
| **review_report** | 质量 | 客观性、逻辑严谨性、业务完整性 |
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
requirement-generator-v1/
|
||
├── SKILL.md # 主流程（简化版）
|
||
├── 开发文档.md # 本文档
|
||
├── references/ # 详细指南（渐进式披露）
|
||
│ ├── phase3_interview_guide.md
|
||
│ └── phase6_review_guide.md
|
||
├── assets/ # 项目类型配置
|
||
│ ├── agent_dev.md
|
||
│ ├── feature_update.md
|
||
│ └── testing.md
|
||
└── templates/ # 需求文档模板
|
||
├── agent_dev_template.md
|
||
├── feature_update_template.md
|
||
└── testing_template.md
|
||
|
||
项目 agents/ (D:\AA_Work\AIEC-团队开发规范Skills\.claude\agents\)
|
||
├── project_type_matcher.md
|
||
├── req_interviewer.md
|
||
├── req_writer.md
|
||
├── dev_expert_reviewer.md
|
||
├── pm_reviewer.md
|
||
├── ai_expert_reviewer.md
|
||
├── domain_expert_reviewer.md
|
||
├── req_consolidator.md
|
||
├── req_auto_consolidator.md
|
||
└── review_report.md
|
||
|
||
temp/ (运行时生成)
|
||
├── interview_result.json # 访谈结果
|
||
├── domain_role.md # 领域专家角色定义
|
||
├── review_dev.json # 开发专家评审
|
||
├── review_pm.json # 产品经理评审
|
||
├── review_ai.json # AI专家评审
|
||
├── review_domain.json # 领域专家评审
|
||
└── consolidation_report.json # 汇总应用记录（自动模式）
|
||
```
|
||
|
||
## 数据传递策略
|
||
|
||
本 Skill 采用以下数据传递模式：
|
||
|
||
| 传递方向 | 策略 | 说明 |
|
||
|----------|------|------|
|
||
| 主窗口 → Agent | 简洁指令 | 仅传递任务描述 |
|
||
| Agent → temp/ | JSON文件 | 结构化数据存储，便于其他Agent读取 |
|
||
| Agent → 主窗口 | 概要文字 | 简洁提示，详细数据在文件中 |
|
||
| Agent → Agent | 文件路径 | 通过 `temp/*.json` 传递，主窗口不加载 |
|
||
|
||
## 关键设计决策
|
||
|
||
### 1. 多专家独立评审
|
||
|
||
采用4位专家（开发专家、产品经理、AI专家、领域专家）从不同视角独立评审需求文档。
|
||
|
||
**设计理由**: 不同角色关注点不同，多视角评审可发现单一视角的盲点，确保需求覆盖全面。
|
||
|
||
### 2. 评审结果持久化
|
||
|
||
各专家评审结果保存到 `review_*.json`，便于后续汇总和追溯。
|
||
|
||
**设计理由**: 结构化存储便于自动化处理，同时保留评审历史供审计。
|
||
|
||
### 3. 用户需求基准原则
|
||
|
||
汇总时以 `interview_result.json` 中的用户原始需求为最高准则，专家建议不可违背。
|
||
|
||
**设计理由**: 专家是辅助角色，最终产品要满足用户需求。
|
||
|
||
### 4. Agent 自治性
|
||
|
||
所有 Agent 采用自治设计模式：
|
||
- 执行规则、工具使用规范固化在 Agent 定义中
|
||
- Agent 自行读取配置文件（路径在 Agent 定义中硬编码）
|
||
- 主窗口仅传递模式标识，不传递执行逻辑
|
||
|
||
### 5. 文档版本管理
|
||
|
||
采用双文档策略保留完整历史：
|
||
- `requirement.md`: 初版文档，生成后不再修改
|
||
- `requirement_final.md`: 评审优化版，仅在阶段6生成
|
||
|
||
## 扩展指南
|
||
|
||
### 添加新项目类型
|
||
|
||
1. 参考现有配置文件（如 `assets/agent_dev.md`）创建新配置
|
||
2. 编辑 frontmatter 字段：type, keywords, priority
|
||
3. 定义核心问题（业务版本 + 技术版本）
|
||
4. 设计业务到技术的映射规则
|
||
5. 创建对应的文档模板 `templates/{type}_template.md`
|
||
6. 测试访谈流程和文档生成完整性
|
||
|
||
### 添加新评审专家
|
||
|
||
1. 在 `agents/` 目录创建新专家定义文件
|
||
2. 定义专家视角和评审重点
|
||
3. 更新 SKILL.md 和 phase6_review_guide.md 中的调用列表
|
||
4. 更新汇总 Agent 的文件读取列表
|
||
|
||
## 常见场景处理
|
||
|
||
### 用户描述过于简短
|
||
|
||
当 project_type_matcher 返回低置信度时：
|
||
1. 系统列出所有可用项目类型供用户选择
|
||
2. req_interviewer 通过多轮访谈补充缺失信息
|
||
|
||
### 用户选择"未知类型"
|
||
|
||
系统采用开放式访谈模式：
|
||
1. req_interviewer 通过开放式问题理解项目本质
|
||
2. Agent 自主决定文档结构
|
||
3. req_writer 根据 custom_sections 构建文档（不使用预定义模板）
|
||
|
||
### 专家意见存在冲突
|
||
|
||
当多位专家意见不一致时：
|
||
- **用户确认模式**: 向用户展示不同观点，由用户决定
|
||
- **自动应用模式**: 按裁决规则处理（合规性优先 > 技术可行性优先 > 用户价值优先），在 `consolidation_report.json` 中记录裁决过程
|
||
|
||
---
|
||
|
||
**最后更新**: 2025-12-01
|
||
**Skill 版本**: v1
|