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