SuperAPI AI 工具集

plan-eng-review

编程与开发

查看项目

更新于 10-16 23:14

技能介绍

用途

plan-eng-review 是一个以工程经理模式(Eng manager-mode)执行的计划评审 Skill。它的核心目标是在进入实现之前,对一份计划做工程维度的审视,包括:范围挑战(Scope challenge)、架构审查、代码质量审查、详细的测试覆盖图(test coverage diagram)以及性能审查。评审结果会产出一份测试计划产物,供下游 QA 环节使用。此外还提供可选的跨模型外部意见(Optional cross-model outside voice)。

来源与许可

该 Skill 引用上游文档:garrytan/gstack 仓库中的 plan-eng-review/SKILL.md,修订版本 f4bbfaa5bdfd2d6ce59541c2145432febde57fed,署名 Garry Tan,许可为 MIT。文件注明为从 SKILL.md.tmpl 自动生成,不应直接编辑,重新生成命令为 bun run gen:skill-docs。

运行前导步骤(Preamble)

Skill 开始时执行一段 Bash 前导脚本,内容包括:

  • 运行 gstack 更新检查(gstack-update-check),可能输出升级提示。
  • 创建并清理会话目录 ~/.gstack/sessions(保留 120 分钟内的文件,删除更早的)。
  • 读取配置项 gstack_contributor、proactive。
  • 输出当前 git 分支、PROACTIVE 状态、REPO_MODE(通过 gstack-repo-mode)、Completeness 介绍是否已看过、遥测状态与是否已询问遥测。
  • 记录一次技能使用日志到 ~/.gstack/analytics/skill-usage.jsonl。
  • 处理遗留的 pending 遥测项。

根据结果有不同的后续行为:若 PROACTIVE 为 false,则不再主动建议 gstack 技能;若提示升级则按内联升级流程处理;若刚升级则提示用户;若从未看过完整性介绍,则介绍 Boil the Lake 原则并可提供打开文章链接;若尚未询问遥测则通过 AskUserQuestion 询问是否参与遥测(社区模式/匿名模式/关闭)。

交互与原则

AskUserQuestion 有固定格式要求:重新定位(项目、当前分支、当前计划)、用通俗英文简化说明问题、给出带完整度评分(Completeness: X/10)的推荐、列出 A/B/C 选项并在涉及工作量时同时给出人工与 CC 两套时间。

完整性原则(Boil the Lake):AI 辅助编码让“完整”的边际成本接近零,因此在选项之间应优先推荐完整实现而非捷径;区分“湖”(可燃尽的完整范围,如 100% 测试覆盖、完整功能、全部边界情况)与“海洋”(超出范围,如重写整个系统、给不受控依赖加功能、多季度平台迁移)。估算时同时给出人工团队与 CC+gstack 两套时间,并给出了按任务类型的压缩比参考表(如样板/脚手架约 100x、测试编写约 50x、功能实现约 30x 等)。文中列出若干反模式,例如不要只给出人工时间、不要以省时为由跳过边界情况处理、不要把测试覆盖推迟到后续 PR。

仓库所有权模式(Repo Ownership Mode)根据 REPO_MODE 决定处理方式:solo 模式下对分支外发现的问题默认主动调查并提议修复;collaborative 模式下通过 AskUserQuestion 标记问题并默认询问而非直接修;unknown 按 collaborative 处理。配合“See Something, Say Something”,在任何工作流步骤中发现异常都应简要标记。

Search Before Building 强调先搜索,提出三层知识(成熟可用、新且流行、第一性原理),鼓励记录 EUREKA 时刻到 ~/.gstack/analytics/eureka.jsonl;若 WebSearch 不可用则跳过搜索并说明仅用分布内知识。

贡献者模式(Contributor Mode):当配置为贡献者时,在每个主要工作流步骤后反思并评分,对明显可操作的 bug 或有价值的改进提交现场报告(写入 ~/.gstack/contributor-logs/{slug}.md),规定了报告模板、slug 命名规则(小写、连字符、最长 60 字符)、每会话最多 3 份报告等。

状态与收尾

完成状态协议:DONE、DONE_WITH_CONCERNS、BLOCKED、NEEDS_CONTEXT。允许在困难或不确定时升级停止,并给出升级格式(STATUS/REASON/ATTEMPTED/RECOMMENDATION);例如同一任务尝试三次未成功应停止升级。

遥测(Telemetry,最后运行):工作流完成后记录遥测事件到 ~/.gstack/analytics/,包含技能名、时长、结果(success/error/abort/unknown)、是否使用 browse、会话 ID。计划模式例外——该命令始终运行。

计划状态页脚:在计划模式准备调用 ExitPlanMode 时,若计划文件已有 ## GSTACK REVIEW REPORT 则跳过;否则运行 gstack-review-read 并写入评审报告表格,包含 CEO Review、Codex Review、Eng Review、Design Review 等行(截断处为止)。

适用场景与限制

该 Skill 面向 gstack 技能生态(Claude 类环境)中计划阶段的工程评审,适合在实现前需要架构、代码质量、测试覆盖与性能审视的开发计划。它依赖 gstack 的 bin 工具链(更新检查、配置、遥测日志、repo-mode、review-read 等)以及 ~/.gstack 目录与 git 仓库环境。资料未提供具体的安装步骤、价格或平台支持范围,暂未提供。

引用文档

以下为作者声明的引用来源,保留指定版本、署名和许可。

作者的来源声明