SuperAPI AI 工具集

augment-plan

编程与开发

查看项目

更新于 10-16 06:58

技能介绍

用途

Augment Plan 用于增强一份已有的执行计划(ExecPlan)。它读取现有计划,并为其补充两层互补的指导内容:面向智能体的命令行界面(CLI)设计需求,以及项目脚手架(仓库结构与指导文件)建议。

该技能存在的意义在于:由 PRD 生成的 ExecPlan 通常只描述代码层面要构建什么——里程碑、文件编辑、验证步骤,但有两件事经常被遗漏:

  • CLI 设计:当项目包含 CLI 时,计划往往只在功能层面描述命令(如“添加一个 deploy 命令”),而没有规定结构化信封、错误分类、退出码、guide 命令、dry-run 支持或安全标志,导致 CLI 对人类可用但会破坏智能体自动化。
  • 项目脚手架:计划直接跳到功能代码,而没有建立仓库基础——README、ARCHITECTURE.md、AGENTS.md、测试策略、CI 工作流等指导文件,使项目对人类和未来的编码智能体都难以导航。

该技能通过读取现有计划并插入位置恰当的里程碑、步骤和上下文来弥补这两处缺口,同时不破坏计划原有的结构或叙述流。

主要能力

  • 定位并通读现有 ExecPlan,识别项目类型、已有里程碑、技术栈以及计划的语气与详细程度。
  • 在可用时读取生成该计划的 PRD,以获取项目是否为 CLI、目标用户群、非目标等上下文。
  • 判断需要增强的内容:项目是否包含 CLI、计划是否已有脚手架步骤,并在修改文件前告知用户计划添加的内容。
  • 根据 CLI 类型确定适用的 CLI 清单部分(只读查询工具、修改状态工具、计划-审查-应用工作流工具、多智能体/共享资源工具)。
  • 以三种策略之一写入 CLI 增强:插入新里程碑、增强现有里程碑,或添加 Context 章节附录。
  • 写入脚手架增强:添加一个位于所有功能工作之前的脚手架里程碑,包含基础文档、智能体指导文件和质量基础设施。
  • 更新计划的“活动章节”:Progress、Decision Log、Context and Orientation。
  • 进行自审:自包含、比例适当、技术栈特定、非破坏性、顺序正确、具体明确。
  • 将增强后的计划保存回同一文件(或用户偏好的新文件),并告知用户添加了什么。

使用方式

该技能按以下步骤运行:

  1. 定位并读取现有计划:若未提供 ExecPlan 文件路径则向用户询问。通读并关注项目类型、已有里程碑、技术栈、计划的语气与详细程度。
  2. 读取 PRD(如可用):若生成该计划的 PRD 存在于仓库中,一并读取,以了解项目是否为 CLI、目标用户群、可能影响脚手架范围的非目标。若无 PRD,则仅依据计划工作,并请用户确认推断。
  3. 决定增强内容:判断项目是否包含 CLI(是则应用 CLI 增强,否则完全跳过);判断计划是否已有脚手架步骤(完全没有则添加完整脚手架里程碑,有缺口则填补,已全面则跳过或轻度补充)。在修改文件前告知用户计划添加的内容。
  4. 确定适用的 CLI 部分:CLI 清单有五部分,并非所有 CLI 都适用。依据 CLI 类型选择:只读查询/检查工具适用 I(基础)+ II(读取与发现);修改文件/状态的工具适用 I + II + III(安全变更);计划-审查-应用工作流工具适用 I + II + III + IV(事务性工作流);多智能体/共享资源工具适用 I + II + III + IV + V(多智能体协调)。Part I(基础)适用于每个 CLI,涵盖结构化 JSON 信封、机器可读错误码、按错误类别区分的退出码、内置 guide 命令、一致的命令组与动词命名、--help 中的示例、TOON(stdout 仅用于数据)、LLM=true 环境变量支持、每个响应中的可观测性指标、模式版本控制。
  5. 写入 CLI 增强:以尊重现有结构的方式添加 CLI 需求,有三种策略——策略 A:插入新里程碑(当计划完全没有 CLI 设计时);策略 B:增强现有里程碑(当计划已描述 CLI 命令但缺少契约细节时);策略 C:添加 Context 章节附录(当 CLI 设计基本完整但缺少某些原则时)。所有情况下都要具体:不要只说“添加结构化输出”,而要给出项目语言的确切信封类型定义;不要只说“添加错误码”,而要列出 CLI 将需要的具体错误码。
  6. 写入脚手架增强:添加一个脚手架里程碑,应作为第一个里程碑(在任何功能工作之前),标题类似“Scaffold Repository Structure and Guidance Files”。该里程碑应包含创建以下内容的具体步骤:基础文档(README.md、PROJECT.md、ARCHITECTURE.md、TESTING.md、CONTRIBUTING.md、CHANGELOG.md、DECISIONS/ADR-0001-initial-architecture.md,仅创建项目尚没有的);智能体指导文件(AGENTS.md、路径特定的 .instructions.md 文件);质量基础设施(格式化配置、linter 配置、.editorconfig、.gitignore、CI 工作流)。对于 PRD 未指定的内容,使用占位符模式(TODO、Why it matters、How to fill this in、Example)。脚手架里程碑的验证步骤应验证所有指导文件存在且非空、README 包含可用的快速开始章节、CI 工作流语法有效、linter 运行无配置错误。
  7. 更新活动章节:添加里程碑和步骤后,更新计划的 Progress(为新步骤添加未勾选项)、Decision Log(记录应用了哪些 CLI 清单部分及原因、包含/排除了哪些脚手架文件及原因、对项目类型所做的假设)、Context and Orientation(定义新概念,使计划保持自包含)。
  8. 自审:验证计划自包含、增强比例适当、技术栈特定、非破坏性、顺序正确、具体明确。
  9. 写入增强后的计划:保存回同一文件(或用户偏好的新文件),并告知用户添加了什么、应用了哪些 CLI 清单部分、引入了多少新里程碑/步骤、需要验证的假设。

适用场景

  • 项目包含 CLI,且希望该 CLI 能被智能体自动化使用。
  • 计划缺少结构化输出、错误码、退出码、guide 命令、dry-run 支持或安全标志等 CLI 契约细节。
  • 计划直接跳到功能代码,缺少 README、ARCHITECTURE.md、AGENTS.md、测试策略、CI 工作流等仓库基础。
  • 需要为项目建立可供人类和未来编码智能体导航的指导文件。
  • 需要在不破坏原计划结构与叙述的前提下补充里程碑和步骤。

限制

  • 并非每个计划都需要两层增强;若项目不包含 CLI,则完全跳过 CLI 增强。
  • CLI 清单的五部分并非都适用于每个 CLI,需依据 CLI 类型选择。
  • 若没有 PRD,只能依据计划工作,并需用户确认推断。
  • 增强应与计划范围成比例,小型简单 CLI 的计划不应获得 200 行的 CLI 契约章节。
  • 实现提示必须匹配计划的技术栈,不应在 Go 项目中给出 Python 示例。
  • 增强必须是非破坏性的,保留现有里程碑、步骤和验证标准。
  • 顺序必须正确:脚手架在前,然后是 CLI 基础,然后是功能里程碑。
  • 每个新步骤都必须具体,指明具体文件、类型、函数或命令,而非模糊指令。

参考文件

  • references/cli-manifest.md — 完整的 CLI-MANIFEST 规范。在编写 CLI 增强前阅读。包含完整契约、Python/TypeScript/Go 的实现提示,以及每条原则的正反示例。
  • references/scaffold-from-prd.md — 完整的项目脚手架指南。在编写脚手架增强前阅读。包含完整交付物列表、每个文件的内容指导,以及占位符模式。