SuperAPI AI 工具集

workflows-plan

编程与开发

查看项目

更新于 10-16 11:30

技能介绍

用途

workflows-plan 用于为新的功能或缺陷修复创建计划。它把功能描述、缺陷报告或改进想法转化为结构化、可执行的规划产物,主要输出两份文件:

  • spec.md:人类可读的计划,包含理由、上下文与设计决策。
  • prd.json:机器可执行的故事(story)拆解,用于系统性实现。

工作流程

0. 想法澄清(Idea Refinement)

在提问之前,先检查是否已存在与本功能匹配的计划文件夹或头脑风暴:

  • 匹配标准是文件夹名或头脑风暴内容在语义上与功能描述相符;用户选定的产物优先,不论时间新旧。
  • 找到相关头脑风暴时,会读取该文档并说明其日期与主题,作为规划上下文。
  • 若检测到 shaping 格式(前含 shaping: true,含 R 表、shapes、fit check),会提取 R 表作为验收标准的主要来源、提取所选 shape 与 parts 表作为技术方案结构、提取标记的未知项作为待解决的问题。
  • 若是标准头脑风暴格式,则提取关键决策、选定方案与开放问题,作为调研阶段的输入。
  • 若有多个可能匹配,会通过结构化提问让用户选择使用哪一个,或是否不使用。

若没有找到相关头脑风暴,则进入想法澄清:只提能够消除实质性不确定性的问题,先利用已有对话与仓库证据;一次一个问题,有自然选项时优先多选;聚焦目的、约束与成功标准,直到想法清晰或用户表示继续。

1. 本地上下文与调研决策

复用本任务中已读取的相关上下文,仅检查为支撑计划所必需的缺口。查找既有模式、项目指令文件(AGENTS.md、CLAUDE.md、README.md、OPENCODE.md)、技术熟悉度与模式一致性。

随后决定是否做外部调研:

  • 高风险主题(安全、支付、外部 API、数据隐私)始终调研。
  • 本地上下文充分时跳过外部调研。
  • 不确定或不熟悉领域则调研。

调研完成后汇总发现,记录相关文件路径、外部文档 URL、相关 PR 与项目约定。

1.7 选择详细程度

  • MINIMAL:快速规格,问题 + 方案 + 验收标准,适合简单缺陷、小改进、清晰功能。
  • STANDARD:多数功能适用,增加背景、技术考量、成功指标、依赖与风险。
  • COMPREHENSIVE:大型功能或架构变更,在概览中补充适用的架构、后端、契约、UI 与前端文档。

默认推荐 STANDARD,除非功能极小(MINIMAL)或涉及大型架构、多层系统、复杂集成(COMPREHENSIVE)。

2. 规划与结构

工单与分支:如功能描述包含工单 URL,则提取工单号;否则使用 null(工单可选)。分支命名格式为 feat/[ticket-number]-[description-kebab-case],无工单时用 type/description-kebab-case。规划阶段只记录拟用分支名,不创建或切换分支。

文件夹与标题:使用约定式格式拟定清晰、可搜索的标题,确定类型(feat、fix、refactor),创建形如 YYYY-MM-DD-<type>-<descriptive-kebab-name> 的文件夹名,保持 3-5 个词的描述性。

还包括干系人分析与内容规划。

3. SpecFlow 分析

验证流程与缺口,核对边界情况,依据发现更新验收标准。

3.5 面包板(Breadboard)

触发条件:存在 shaping 格式头脑风暴时。以所选 shape 的 parts 表为输入,产出 places、UI affordances、code affordances、data stores 等 affordance 表,可选生成 Mermaid 可视化。之后切片为垂直增量(最多 V1-V9),每个切片有名称、机制引用、affordance 列表与演示陈述。面包板表与切片摘要作为 spec.md 的一个章节。

3.6 面包板反思

对每个关键用户故事沿接线追踪,对每个 affordance 应用命名测试,标记不一致接线、缺失路径、捆绑 affordance、命名阻力等气味,并修复发现的问题。

4-5. 生成与格式化规格

仅读取所选模板(MINIMAL、STANDARD、COMPREHENSIVE),只使用所需章节。内容要求问题/动机清晰、技术方案带理由、代码引用使用 file:line 格式。Markdown 使用清晰的标题层级、语法高亮、任务列表作为验收标准、可折叠 details 放冗长内容。

6. 生成 PRD

写完 spec.md 后必须生成 prd.json 的可执行故事拆解。若存在面包板切片,每个切片 V1-V9 对应一个故事(切片较大时可为故事组);切片演示陈述作为验收标准;切片机制引用作为故事标题上下文;切片顺序作为优先级与依赖。故事提取规则:每个故事交付一个连贯、可验证的结果,含完整所需的错误路径,不以措辞或技术层拆分;验收标准用 Given/When/Then;依赖关系显式;提示相关的斜杠命令。

每个故事必须恰好属于一个类别:functional、ui、integration、edge-case、performance。需阅读 prd-schema.md 获取模式、字段含义、示例与校验清单,校验 ID 唯一、依赖有效、无环、覆盖每条验收标准。

6.5 必要时绘制图表

当图表能消除具体歧义或便于验证关系时(组件边界、多步数据流、重要状态转换、复杂分支、依赖顺序)才包含;简单缺陷或线性流程用文字或验收标准即可。有用时在 spec 中用 Mermaid,包含错误路径与无效转换。

7. 最终审查

写前检查:文件夹名描述性且可查找;spec.md 章节对所选详细程度完整;prd.json 故事覆盖全部验收标准;依赖映射正确;代码引用用 file:line;在澄清关键关系或状态转换处包含图表。

输出结构

文件夹:docs/plans/YYYY-MM-DD-<type>-<descriptive-name>/

MINIMAL / STANDARD 内容:brainstorm.md(可选)、spec.md、prd.json。

COMPREHENSIVE 内容(仅在适用时包含支持文档):brainstorm.md(可选)、spec.md(整合概览,供下游工具入口)、adr.md、backend.md、dtos.md、ui-design.md、frontend.md、prd.json。

生成后可选项

报告计划位置并给出后续动作选项:查看规格、查看 PRD、运行 /workflows-deepen-plan、运行 /workflows-plan-review、本地开始 /workflows-work、在配置的远程代理运行时后台开始 /workflows-work、简化(降低详细程度或故事数)。

适用场景

适用于将功能描述、缺陷报告或改进想法转化为结构化规格与可执行 PRD 的规划场景,尤其适合需要人类可读计划与机器可执行故事拆解结合的工作流。

限制

资料未提供收费、价格、平台支持与效果方面的信息。该技能依赖正在运行的运行时环境及其运行时等价工具(RUNTIME_TOOLS.md)、共享与项目指令文件;ETHOS.md 仅为人类参考,非强制运行时来源。规划日期取自当前环境日期。规划阶段不创建或切换分支,工作区准备由实现阶段负责。外部调研与子代理研究按条件触发,非每次必做。