requirements

Requirements 技能

运行一个结构化的 5 阶段需求工作流，将功能请求转化为可直接用于实现的规格说明。

将 SKILL.md 作为工作流的唯一事实来源。从 references/templates.md 加载详细模板和预设输出文本。

目的

• 在实现前明确产品和技术预期。
• 明确记录假设。
• 编写一份在可行时引用真实代码库模式的需求规格说明。

使用时机

在以下情况下使用此技能：

• 用户要求明确新功能的范围。
• 用户要求编写或完善需求文档／规格说明。
• 正在运行需求命令工作流（requirements-start、requirements-status、requirements-current、requirements-list、requirements-remind、requirements-end）。

核心规则

1. 每条消息只问一个问题。
2. 每个问题都必须是封闭式问题：
   • 是／否，或
   • 有界多选题（2–5 个选项），并提供默认选项。
3. 先生成当前阶段的所有问题，再按顺序提问。
4. 优先使用产品语言；仅在有助于提高决策质量时补充技术说明。
5. 收集需求期间，不要实现代码。
6. 发现真实仓库路径后，使用这些路径。仅在可复用模板／示例中使用占位符。
7. 控制每个阶段的问题数量（目标为 5 个；有充分理由时可为 4–7 个）。

5 阶段工作流

阶段 1 — 初始化会话

1. 创建需求文件夹：requirements/[timestamp]-[slug]/。
2. 创建初始文档：
   • 00-initial-request.md
   • metadata.json
3. 使用活动文件夹更新 requirements/.current-requirement。
4. 扫描代码库，找出相关模块、数据模型、路由和 API。

如果仓库结构不同，请相应调整路径和命名。

阶段 2 — 探索问题（产品范围）

1. 起草探索问题，重点关注用户成果、范围边界、权限、数据影响和外部集成。
2. 在提问前，将本阶段的所有问题写入 01-discovery-questions.md。
3. 按顺序逐个提问，并为每个问题提供建议的默认选项。
4. 接受简洁回答：
   • 是／否
   • 有界选项中的一个选项
   • 未知／默认
5. 阶段进行期间，将回答保存在临时工作笔记中。
6. 所有问题提完后，将最终回答写入 02-discovery-answers.md，并更新 metadata.json。

阶段 3 — 收集上下文（自主进行）

1. 搜索代码，查找类似功能和可复用模式。
2. 检查相关的后端／前端／数据文件和集成点。
3. 在 03-context-findings.md 中记录调查结果：
   • 类似功能
   • 候选修改文件
   • 约束和风险
   • 建议采用的模式
4. 自主完成此阶段，除非存在阻碍进展的关键歧义，否则不要向用户提问。

使用当前 Agent 运行环境中可用的搜索／读取／导航工具。

阶段 4 — 细节问题（行为与设计决策）

1. 根据阶段 3 的调查结果推导后续问题。
2. 在提问前，将本阶段的所有问题写入 04-detail-questions.md。
3. 每次提一个问题，并提供默认选项。
4. 优先使用 PM 易于理解的措辞；需要时再补充可选的技术定位信息。
   • 示例：“用户应从现有的 Project Settings 页面编辑此项吗？”
   • 可选定位信息：“（可能位于 apps/web/src/routes/project-settings.tsx）”
5. 阶段进行期间，将回答保存在临时笔记中。
6. 所有问题提完后，将最终回答写入 05-detail-answers.md，并更新 metadata.json。

阶段 5 — 生成需求规范

1. 创建 06-requirements-spec.md。
2. 包含：
   • 概述
   • 功能需求和验收标准
   • 技术需求
   • 受影响的文件/系统
   • 假设和待解决问题
3. 将未解决的事项标记为 ASSUMED:，并说明理由。
4. 将元数据状态更新为已完成（如果明确暂停，则更新为未完成）。
5. 会话结束时清空 .current-requirement。

使用 references/templates.md 中的规范模板。

命令行为

requirements-start

• 初始化文件夹和元数据。
• 执行阶段 1，然后开始阶段 2。

requirements-status

• 显示当前阶段、进度、近期回答和下一个问题。
• 从下一个尚未回答的问题继续。

requirements-current

• 显示当前需求的完整只读快照（所有产物）。
• 除非用户明确要求，否则不要继续提问。

requirements-list

• 列出所有需求文件夹及其状态，按以下顺序排序：
  1. 活跃项
  2. 已完成/未完成
  3. 最新优先

requirements-remind

• 根据当前阶段显示简洁的规则提醒。
• 纠正流程偏离（例如，开放式问题、偏离实施、缺少默认值）。

requirements-end

• 如果存在活跃需求，提供以下选项：
  1. 立即生成规范
  2. 标记为未完成
  3. 取消
• 删除产物前确认破坏性操作。

可移植性规则

1. 将特定于项目的路径视为示例，而非固定值。
2. 将配套技能视为可选的加速工具，而非依赖项。
3. 除非仓库上下文明确确认了特定框架/工具，否则优先使用通用措辞。
4. 在不同 Agent 运行环境中保持产物和流程一致。

质量检查清单

• 开始提问前，确保问题集完整。
• 每个已提出的问题都有默认值和理由。
• 将临时笔记整合到阶段答案文件中。
• 规范明确区分已确认的决策和假设。
• 输出聚焦于需求（不涉及实施）。

参考文件

• references/templates.md — 以下内容的规范模板：
  • 问题文件
  • 答案文件
  • 上下文调查结果
  • 元数据
  • 需求规范
  • 状态/列表/提醒输出片段