311 lines
7.6 KiB
Markdown
311 lines
7.6 KiB
Markdown
|
---
|
|||
|
|
name: 0004-define-requirements
|
|||
|
|
description: 需求定义与入库，创建需求文档并更新索引
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 技能：需求定义与入库 (Define Requirements)
|
|||
|
|
|
|||
|
|
## 元数据 (Metadata)
|
|||
|
|
|
|||
|
|
- **name**: define-requirements
|
|||
|
|
- **description**: 需求定义与入库，创建需求文档并更新索引
|
|||
|
|
- **version**: 1.0.0
|
|||
|
|
- **author**: SSOT Architect
|
|||
|
|
- **lastUpdated**: 2026-01-15
|
|||
|
|
|
|||
|
|
## 触发与定位 (Triggers & Scope)
|
|||
|
|
|
|||
|
|
### 触发条件 (Triggers)
|
|||
|
|
当以下情况发生时，AI 应当"觉醒"本技能：
|
|||
|
|
|
|||
|
|
1. **新功能需求**: 用户提出新的功能需求
|
|||
|
|
2. **Bug 修复需求**: 用户报告 Bug 并要求修复
|
|||
|
|
3. **性能优化需求**: 用户要求优化系统性能
|
|||
|
|
4. **技术债务清理**: 用户要求清理技术债务
|
|||
|
|
5. **工作流阶段 1**: 用户进入工作流的"需求定义与入库"阶段
|
|||
|
|
|
|||
|
|
### 定位范围 (Scope)
|
|||
|
|
- **适用模块**: 所有 Datai 项目模块
|
|||
|
|
- **影响文件**: `docs/requirements/REQ-XXX.md`, `docs/index.md`
|
|||
|
|
- **相关技能**: skill-architecture-decision, skill-prompt-engineering
|
|||
|
|
|
|||
|
|
## 核心指令集 (Instructions)
|
|||
|
|
|
|||
|
|
### 架构约束 (Architecture Constraints)
|
|||
|
|
|
|||
|
|
1. **需求文档命名规范**:
|
|||
|
|
- 格式: `REQ-XXX.md`
|
|||
|
|
- XXX: 三位数字，从 001 开始递增
|
|||
|
|
- 示例: `REQ-001.md`, `REQ-002.md`
|
|||
|
|
|
|||
|
|
2. **需求文档必须包含**:
|
|||
|
|
- 需求编号和标题
|
|||
|
|
- 需求类型（功能/非功能）
|
|||
|
|
- 优先级（高/中/低）
|
|||
|
|
- 用户故事
|
|||
|
|
- 验收标准（AC）
|
|||
|
|
- 相关文档链接
|
|||
|
|
- 状态（Draft/In Progress/Completed）
|
|||
|
|
|
|||
|
|
3. **必须同步更新 docs/index.md**:
|
|||
|
|
- 将新需求添加到"需求文档"表格
|
|||
|
|
- 标记需求状态
|
|||
|
|
- 包含需求描述和更新日期
|
|||
|
|
|
|||
|
|
### 业务逻辑 SOP (Business Logic SOP)
|
|||
|
|
|
|||
|
|
#### 步骤 1: 解析用户原始需求
|
|||
|
|
```markdown
|
|||
|
|
## 需求解析
|
|||
|
|
|
|||
|
|
### 原始需求
|
|||
|
|
[用户提供的原始需求描述]
|
|||
|
|
|
|||
|
|
### 需求类型
|
|||
|
|
- [ ] 功能需求
|
|||
|
|
- [ ] 非功能需求（性能/安全/可用性等）
|
|||
|
|
|
|||
|
|
### 优先级
|
|||
|
|
- [ ] 高
|
|||
|
|
- [ ] 中
|
|||
|
|
- [ ] 低
|
|||
|
|
|
|||
|
|
### 影响范围
|
|||
|
|
- [ ] 前端
|
|||
|
|
- [ ] 后端
|
|||
|
|
- [ ] 数据库
|
|||
|
|
- [ ] API
|
|||
|
|
- [ ] 文档
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 步骤 2: 编写用户故事
|
|||
|
|
```markdown
|
|||
|
|
## 用户故事
|
|||
|
|
|
|||
|
|
### 用户角色
|
|||
|
|
[目标用户角色]
|
|||
|
|
|
|||
|
|
### 用户目标
|
|||
|
|
[用户想要达成的目标]
|
|||
|
|
|
|||
|
|
### 用户价值
|
|||
|
|
[用户为什么需要这个功能]
|
|||
|
|
|
|||
|
|
### 用户故事格式
|
|||
|
|
作为一个 [用户角色]，
|
|||
|
|
我想要 [用户目标]，
|
|||
|
|
以便于 [用户价值]。
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 步骤 3: 定义验收标准（AC）
|
|||
|
|
```markdown
|
|||
|
|
## 验收标准 (Acceptance Criteria)
|
|||
|
|
|
|||
|
|
### 功能验收标准
|
|||
|
|
- [ ] AC1: [具体的验收标准]
|
|||
|
|
- [ ] AC2: [具体的验收标准]
|
|||
|
|
- [ ] AC3: [具体的验收标准]
|
|||
|
|
|
|||
|
|
### 非功能验收标准
|
|||
|
|
- [ ] 性能要求: [具体的性能指标]
|
|||
|
|
- [ ] 安全要求: [具体的安全要求]
|
|||
|
|
- [ ] 可用性要求: [具体的可用性要求]
|
|||
|
|
|
|||
|
|
### 测试用例
|
|||
|
|
| 用例编号 | 用例描述 | 预期结果 |
|
|||
|
|
|----------|----------|----------|
|
|||
|
|
| TC-001 | [测试用例描述] | [预期结果] |
|
|||
|
|
| TC-002 | [测试用例描述] | [预期结果] |
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 步骤 4: 创建需求文档
|
|||
|
|
```markdown
|
|||
|
|
---
|
|||
|
|
name: REQ-001
|
|||
|
|
description: [需求描述]
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 需求: [需求标题]
|
|||
|
|
|
|||
|
|
## 元数据 (Metadata)
|
|||
|
|
|
|||
|
|
- **需求编号**: REQ-001
|
|||
|
|
- **需求标题**: [需求标题]
|
|||
|
|
- **需求类型**: [功能需求/非功能需求]
|
|||
|
|
- **优先级**: [高/中/低]
|
|||
|
|
- **状态**: [Draft/In Progress/Completed]
|
|||
|
|
- **创建日期**: YYYY-MM-DD
|
|||
|
|
- **最后更新**: YYYY-MM-DD
|
|||
|
|
- **创建人**: [创建人姓名]
|
|||
|
|
- **负责人**: [负责人姓名]
|
|||
|
|
|
|||
|
|
## 需求描述 (Description)
|
|||
|
|
|
|||
|
|
### 背景
|
|||
|
|
[需求背景和上下文]
|
|||
|
|
|
|||
|
|
### 问题陈述
|
|||
|
|
[当前存在的问题]
|
|||
|
|
|
|||
|
|
### 目标
|
|||
|
|
[需求要达成的目标]
|
|||
|
|
|
|||
|
|
## 用户故事 (User Story)
|
|||
|
|
|
|||
|
|
作为一个 [用户角色]，
|
|||
|
|
我想要 [用户目标]，
|
|||
|
|
以便于 [用户价值]。
|
|||
|
|
|
|||
|
|
## 验收标准 (Acceptance Criteria)
|
|||
|
|
|
|||
|
|
### 功能验收标准
|
|||
|
|
- [ ] AC1: [具体的验收标准]
|
|||
|
|
- [ ] AC2: [具体的验收标准]
|
|||
|
|
- [ ] AC3: [具体的验收标准]
|
|||
|
|
|
|||
|
|
### 非功能验收标准
|
|||
|
|
- [ ] 性能要求: [具体的性能指标]
|
|||
|
|
- [ ] 安全要求: [具体的安全要求]
|
|||
|
|
- [ ] 可用性要求: [具体的可用性要求]
|
|||
|
|
|
|||
|
|
## 技术要求 (Technical Requirements)
|
|||
|
|
|
|||
|
|
### 技术栈
|
|||
|
|
- [ ] Java 17/21
|
|||
|
|
- [ ] Spring Boot 3.x
|
|||
|
|
- [ ] MyBatis Plus
|
|||
|
|
- [ ] Salesforce API
|
|||
|
|
|
|||
|
|
### 接口要求
|
|||
|
|
- [ ] REST API
|
|||
|
|
- [ ] SOAP API
|
|||
|
|
- [ ] GraphQL API
|
|||
|
|
|
|||
|
|
### 数据库要求
|
|||
|
|
- [ ] MySQL
|
|||
|
|
- [ ] PostgreSQL
|
|||
|
|
- [ ] Oracle
|
|||
|
|
|
|||
|
|
## 依赖关系 (Dependencies)
|
|||
|
|
|
|||
|
|
### 前置需求
|
|||
|
|
- [REQ-XXX](./REQ-XXX.md) - [前置需求描述]
|
|||
|
|
|
|||
|
|
### 后续需求
|
|||
|
|
- [REQ-XXX](./REQ-XXX.md) - [后续需求描述]
|
|||
|
|
|
|||
|
|
### 外部依赖
|
|||
|
|
- [外部系统/服务] - [依赖描述]
|
|||
|
|
|
|||
|
|
## 相关文档 (Related Documents)
|
|||
|
|
|
|||
|
|
- [设计文档](../design/DES-XXX.md)
|
|||
|
|
- [ADR 文档](../decisions/adr/ADR-XXX.md)
|
|||
|
|
- [提示词文档](../prompts/PROMPT-XXX.md)
|
|||
|
|
|
|||
|
|
## 变更历史 (Change History)
|
|||
|
|
|
|||
|
|
| 日期 | 版本 | 变更内容 | 变更人 |
|
|||
|
|
|------|------|----------|--------|
|
|||
|
|
| YYYY-MM-DD | 1.0.0 | 初始版本 | [姓名] |
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 步骤 5: 更新 docs/index.md
|
|||
|
|
```markdown
|
|||
|
|
### 📝 需求文档 (Requirements)
|
|||
|
|
| 文档 | 状态 | 描述 | 更新日期 |
|
|||
|
|
|------|------|------|----------|
|
|||
|
|
| [REQ-001](requirements/REQ-001.md) | 🔄 In Progress | [需求描述] | 2026-01-15 |
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 工具调用 (Tool Usage)
|
|||
|
|
|
|||
|
|
1. **需求编号生成工具**:
|
|||
|
|
- 使用 `Grep` 工具搜索 `docs/requirements/` 目录
|
|||
|
|
- 查找最大的 REQ 编号
|
|||
|
|
- 生成新的 REQ 编号
|
|||
|
|
|
|||
|
|
2. **文件创建工具**:
|
|||
|
|
- 使用 `Write` 工具创建需求文档
|
|||
|
|
- 确保文件路径正确
|
|||
|
|
|
|||
|
|
3. **索引更新工具**:
|
|||
|
|
- 使用 `Read` 工具读取 `docs/index.md`
|
|||
|
|
- 使用 `SearchReplace` 工具更新索引
|
|||
|
|
|
|||
|
|
## 错误陷阱与验证 (Anti-Patterns & Checklist)
|
|||
|
|
|
|||
|
|
### 常见错误 (Anti-Patterns)
|
|||
|
|
|
|||
|
|
1. **错误**: 需求描述过于模糊
|
|||
|
|
- **后果**: 无法准确理解需求，导致开发偏差
|
|||
|
|
- **修正**: 使用具体的、可量化的描述
|
|||
|
|
|
|||
|
|
2. **错误**: 验收标准不完整
|
|||
|
|
- **后果**: 无法验证需求是否满足
|
|||
|
|
- **修正**: 确保每个功能点都有对应的验收标准
|
|||
|
|
|
|||
|
|
3. **错误**: 忘记更新 docs/index.md
|
|||
|
|
- **后果**: 产生孤儿文件，违反 SSOT 原则
|
|||
|
|
- **修正**: 创建需求文档后必须更新索引
|
|||
|
|
|
|||
|
|
4. **错误**: 用户故事格式不规范
|
|||
|
|
- **后果**: 难以理解用户需求
|
|||
|
|
- **修正**: 使用标准格式：作为一个...我想要...以便于...
|
|||
|
|
|
|||
|
|
5. **错误**: 缺少非功能需求
|
|||
|
|
- **后果**: 系统性能、安全性等无法保证
|
|||
|
|
- **修正**: 必须包含性能、安全、可用性等非功能需求
|
|||
|
|
|
|||
|
|
### 验收清单 (Acceptance Checklist)
|
|||
|
|
|
|||
|
|
- [ ] 需求文档已创建
|
|||
|
|
- [ ] 需求编号符合规范
|
|||
|
|
- [ ] 需求类型已明确
|
|||
|
|
- [ ] 优先级已设定
|
|||
|
|
- [ ] 用户故事已编写
|
|||
|
|
- [ ] 验收标准已定义
|
|||
|
|
- [ ] 技术要求已明确
|
|||
|
|
- [ ] 依赖关系已列出
|
|||
|
|
- [ ] docs/index.md 已更新
|
|||
|
|
- [ ] 相关文档已链接
|
|||
|
|
|
|||
|
|
### Correct vs Incorrect 对比
|
|||
|
|
|
|||
|
|
#### Correct 示例
|
|||
|
|
```markdown
|
|||
|
|
## 用户故事
|
|||
|
|
|
|||
|
|
作为一个系统管理员，
|
|||
|
|
我想要批量导入用户数据，
|
|||
|
|
以便于快速初始化系统用户。
|
|||
|
|
|
|||
|
|
## 验收标准
|
|||
|
|
|
|||
|
|
- [ ] AC1: 支持 CSV 格式的批量导入
|
|||
|
|
- [ ] AC2: 单次导入最多支持 1000 条记录
|
|||
|
|
- [ ] AC3: 导入失败时提供详细的错误信息
|
|||
|
|
- [ ] AC4: 导入耗时不超过 30 秒（1000 条记录）
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### Incorrect 示例
|
|||
|
|
```markdown
|
|||
|
|
## 用户故事
|
|||
|
|
|
|||
|
|
用户想要批量导入数据。
|
|||
|
|
|
|||
|
|
## 验收标准
|
|||
|
|
|
|||
|
|
- [ ] 支持批量导入
|
|||
|
|
- [ ] 导入速度快
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**问题**: 用户故事格式不规范，验收标准不具体、不可量化。
|
|||
|
|
|
|||
|
|
## 相关文档 (Related Documents)
|
|||
|
|
|
|||
|
|
- [工作流提示词](../prompts/03-创建工作流提示词.md#阶段-1-需求定义与入库-requirements)
|
|||
|
|
- [架构决策技能](./0005-architecture-decision.md)
|
|||
|
|
- [提示词资产化技能](./0006-prompt-engineering.md)
|
|||
|
|
- [需求模板](../prompts/03-创建工作流提示词.md#阶段-1-需求定义与入库-requirements)
|