需求澄清

何时使用

• 用户给出一段模糊的功能描述,如"帮我做一个博客系统""我想加个搜索功能";
• 实现前发现需求缺少边界条件、用户场景或验收标准;
• 用户说"需求不太清楚""你先帮我理理";
• 任何可能因理解偏差导致返工的开发任务开始前。

使用步骤

第 1 步:识别需求来源

先确认三件事:

1. 需求提出者是谁(产品、老板、客户、自己);
2. 这个需求要解决什么问题(而不是"要做什么功能");
3. 截止时间或优先级要求。

第 2 步:逐项提问澄清

按以下清单提问,一次只问一组,用户回答后再进入下一组:

第 3 步:复述确认

分维度提问清单、最短提问组合和常见坑见 references/QUESTION_TEMPLATES.md。

用一段话复述你对需求的理解,请用户确认或纠正:

我的理解是:你要为【用户】实现【功能】,目标是【结果】,
核心场景是【场景】,验收标准是【标准】,约束是【约束】。
对吗?

第 4 步:输出需求规格文档

按 references/SPEC_TEMPLATE.md 的结构整理(直接输出在对话中,或应要求写入文件)。写完用 spec_checker.py 自查,补上标出的缺口(见下面的辅助脚本)。

输入与输出

• 输入:一段需求描述(文字、语音转写、口头说明均可);
• 输出:需求规格文档 + 待确认问题清单。

示例

用户输入: "帮我做一个待办事项 App。"

澄清提问(节选):

1. "待办事项 App 要解决什么问题?是个人使用还是团队使用?"
2. "需要哪些功能?比如添加、编辑、删除、提醒、分类?"
3. "数据存在哪里?本地还是云端?要不要多设备同步?"
4. "验收标准是什么?比如:能添加任务、能在今天/明天/逾期之间切换?"

需求规格节选:

## 功能范围
- 必须做:任务的增删改查、完成状态切换、按日期分组
- 不做:提醒推送、多端同步、团队协作
## 验收标准
- 用户能添加任务,输入标题和日期
- 用户能勾选完成,任务进入"已完成"列表
- 任务按日期分组展示(今天/明天/更晚)

辅助脚本

scripts/spec_checker.py 检查需求规格文档的完整性:必需章节是否齐全、章节是否为空、验收标准是否含糊、有无未填占位符:

python skills/requirement-clarifier/scripts/spec_checker.py <需求规格.md>

模板见 references/SPEC_TEMPLATE.md。脚本只做标记,结论需要人确认。

注意事项

• 不要跳步:不要听完需求就直接写代码,先澄清再实现;
• 不要替用户决定:涉及取舍(如"要不要提醒功能")时,列出选项让用户选;
• 区分"要什么"和"怎么要":用户常直接说方案("加个数据库"),要追问目标("解决什么问题");
• 用户不耐烦时,最少问 3 个最关键的问题(目标、范围、验收),然后输出带"待确认问题"的初稿。

不适用场景

• 需求已经清晰且有明确验收标准;
• 用户只需要简单问答,不需要文档化;
• 纯技术咨询(如"这个 API 怎么用"),不属于需求澄清。

验证方式

1. 触发:用"帮我把这个需求理清楚"或一段模糊需求描述触发;
2. 检查:输出包含背景、范围、验收标准、边界、待确认问题;
3. 跑脚本:python skills/requirement-clarifier/scripts/spec_checker.py <输出文档>,无"必须"级问题;
4. 确认:用户对复述内容无异议,或只做了少量修正。