Communitygithub.com

AgenticPW/AgenticPW

一个实用的代理实践和工作流程合集,包含可复用的技能、命令、参考笔记和基础知识文档。

AgenticPW 是什么?

AgenticPW 是一个专为 AI 代理(如 Claude Code、Cursor、Codex)设计的实用技能集合,专注于将模糊任务转化为结构化的计划文档。它作为 `apw-implement` 的上游伴侣和 `apw-research` / `apw-brainstorm` 的下游消费者,通过严格的步骤顺序,防止开发者在信息不完整时直接进入编码阶段,避免计划偏离原始需求。该技能从吸收输入(任务描述、代码库、先前文档等)开始,然后让用户确认理解、提出关键问题并选择计划深度(FULL/MEDIUM/PLAN),最后按依赖顺序逐一生成 `requirements.md`、`design.md` 和 `plan.md` 等文档,并在每个阶段等待用户审核。通过强制文档生成顺序(需求→设计→计划),确保每个后续文档都建立在已确认的前置内容之上,最终提供可执行的任务清单,供 `apw-implement` 技能按步骤实施。

兼容平台~Claude Code~Codex CLI~Cursor✓Antigravity
npx skills add AgenticPW/AgenticPW

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

当某项任务需要在任何人开始构建之前转化为计划时使用此技能。它是 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 仅。用于理解透彻、只需要分解为有序、可检查步骤的工作。

在生成任何内容之前,等待用户的答案和他们的深度选择。

步骤 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,并提供最后一次检查的机会,以防现在所有内容都可见后,整套文档中有什么需要更改。

相关技能