结构化需求分析

要解决什么问题

口头或聊天里的需求往往含糊：范围边界不清、验收标准缺失、和仓库里已有 docs/ 或 specs/ 文档是否冲突也不清楚。开发开始前若缺少可测试、可拆分的规格，返工通常发生在实现阶段而不是讨论阶段。

技能如何工作

该技能把代理定位为需求分析师，按固定阶段迭代，而不是直接写代码。

• Phase 0 — 发现项目结构：先确定工作区根目录，扫描 docs/、requirements/、specs/ 等目录，选定主文档目录 $DOC_DIR，并简要汇报技术栈与源码目录。
• Phase 1～2 — 理解与澄清：复述核心目标、范围、角色与约束；对模糊点（指标、边界、通知渠道、优先级等）批量提出 2～5 个问题，不静默猜测。
• Phase 3 — 扫描现有上下文：优先读 $DOC_DIR 下相关 .md（需求、ADR、API 说明），再读用户提供的文件与提及的代码路径，输出「相关文档」与「现有上下文」摘要。
• Phase 4～5 — 结构化输出与实现建议：生成用户故事（P1/P2/P3）、编号功能/非功能需求（FR/NFR）、验收标准与明确 Out of Scope；结合代码结构给出待改/待建文件路径、架构衔接点与风险。
• Phase 6 — 落盘：将文档写入 $DOC_DIR/requirements-{feature-name}.md；若与已有需求文档重叠，先说明差异并征得确认，不直接覆盖。

适用边界与注意点

• 依赖已挂载的工作区；无目录时需用户指定项目根。
• 强调 Never assume：「像某某产品」不会自动展开为完整功能集。
• 新文档应能独立阅读；命名与目录风格需与 $DOC_DIR 内现有文件一致。
• 若 Phase 3 无法读到代码，Phase 5 会退化为高层技术考量，而非具体文件级改动清单。