当某项任务需要在任何人开始构建之前转化为计划时使用此技能。它是 apw-implement 的上游伴侣和 apw-research / apw-brainstorm 的下游消费者:它接收一个模糊的简报(加上任何文档或先前产物),并生成实现可执行的持久计划文档。它存在的目的是对抗两种失败:带着仅存于易失性上下文的完整计划直接跳入代码,导致步骤被跳过且工作偏离原始要求;以及生成一个丢失了它本应满足的需求线索的计划。严格按以下步骤顺序执行。
输出风格
当此技能要求提供计划、报告、摘要、状态更新或其他面向聊天的输出时,首选项目符号或编号列表,而不是纯段落。保持每个项目简洁且富有信息量。省略那些仅用于平滑语气、重复上下文或在不改变含义的情况下添加“语言糖”的语言。
步骤 1 — 吸收输入
在制定任何计划之前,阅读所有定义任务的内容:
- 简报 — 提供的任务描述、工单或请求。
- 提供的材料 — 随附的任何文档、规格、设计或参考资料。
- 先前产物 — 如果工作项的
research.md或brainstorm.md产物存在(参见apw-work-with-work-item-artifacts了解其位置),计划需在其基础上构建,而不是重做它们的工作。 - 代码库 — 工作将涉及的文件、模块和约定,以便计划符合实际架构而非想象中的架构。
即使任务看起来很小,也不要跳过此步骤。计划的好坏取决于其背后的信息。
步骤 2 — 陈述你的理解、提问并选择深度
首先,写一个简洁的陈述,说明你理解需要做什么——目标、你阅读到的范围以及主要工作部分。这为用户提供了在写入任何文档之前可以纠正的具体内容。
然后,在同一轮中:
- 提出最多 5 个主要问题 —— 仅针对会改变计划的真正歧义点。跳过任何你可以从步骤 1 中回答的问题。不要为了提问而提问。
- 询问要生成哪种文档深度(使用 AskUserQuestion 工具):
- FULL —
requirements.md+design.md+plan.md。适用于更大或更关键的工作,其中是什么 和怎么做 都值得在编写任何代码之前确定下来。 - MEDIUM —
design.md+plan.md。当需求已经明确(或已在上游捕获)但技术/UI 方法仍需要决定时。 - PLAN —
plan.md仅。用于理解透彻、只需要分解为有序、可检查步骤的工作。
- FULL —
在生成任何内容之前,等待用户的答案和他们的深度选择。
步骤 3 — 逐个生成并确认产物
将文档(requirements.md、design.md、plan.md)写入工作项的人工产物文件夹——参见 apw-work-with-work-item-artifacts 了解工作项产物的位置。
按依赖顺序逐个生成文档——切勿一次性全部生成。 写入每个产物后,停止:告诉用户它已就绪(包括其路径)以及一两行关于其内容的摘要,然后等待他们的审核。用户要么:
- 批准 → 继续下一个产物,或
- 要求修改 → 修订该产物并重新提交,重复此过程直到他们批准。
仅在已确认的前一个产物基础上构建下一个产物——设计必须在需求批准后写入,计划必须在设计(和需求)批准后写入。这种顺序是关键:后面的文档引用前面文档中的 ID,因此每个关卡都能防止下一个文档构建在用户即将更改的内容之上。
顺序取决于步骤 2 中选择的深度:
- FULL →
requirements.md→ 审核 →design.md→ 审核 →plan.md→ 审核 - MEDIUM →
design.md→ 审核 →plan.md→ 审核 - PLAN →
plan.md→ 审核
每个文档都使用此技能文件夹中的模板:
requirements.md(仅 FULL) —REQUIREMENTS_TEMPLATE.md。为每个需求赋予一个稳定 ID(R1, R2, …),以便设计和计划可以引用它。ID 一旦分配就不得更改。design.md(FULL 和 MEDIUM) —DESIGN_TEMPLATE.md。涵盖技术设计(主要技术决策、各部分如何配合、被拒绝的方案)以及——仅当任务具有面向用户的界面时——作为 ASCII 线框图 的 UI 设计。为每个设计决策赋予一个稳定 ID(D1, D2, …),并将其与其服务的需求关联。如果没有 UI,则删除 UI 部分。plan.md(所有深度) —PLAN_TEMPLATE.md。有序的子任务列表。规则:- 每个子任务都是一个复选框:
- [ ],保持未选中状态。该框供实施代理在完成该任务时勾选(- [x])——这是向apw-implement传递的机制。 - 在 FULL/MEDIUM 中,每个任务命名其实现内容——
(implements: R2, D1)。一个不能追溯至其来源需求/设计的计划正是此技能旨在防止的那种漂移。在 PLAN 深度中没有上游文档,因此删除引用,保持每个任务自包含。 - 每个任务都是具体的且可独立检查的,并带有“完成条件”验收说明。
- 对任务进行排序,使依赖项在前;如果工作量大,则分组为阶段。
- 每个子任务都是一个复选框:
步骤 4 — 揭示冲突
如果在计划过程中发现输入相互矛盾、某个需求按现有表述无法实现、或范围明显大于简报所暗示的——停下来并告知用户。与他们重新构建框架,而不是为错误的问题编写一个自信、结构良好的计划。
步骤 5 — 简洁摘要
每个产物已在步骤 3 中逐个审核并批准,因此这是一个简短的最终总结,而不是第一次提出反对的机会。保持聊天简短——详细信息存在于产物中。仅报告:
- 选择的 深度 和生成的所有文档的路径。
- 用一两行说明计划概要——阶段数量、任务数量、方法的主线。
然后确认它已准备好移交给 apw-implement,并提供最后一次检查的机会,以防现在所有内容都可见后,整套文档中有什么需要更改。