SuperAPI AI 工具集

implementation-plan-review

编程与开发

查看项目

更新于 10-19 05:26

技能介绍

用途

Implementation Plan Review (Expert) 是一个用于评审实现计划的技能。它对照 GitHub issue 或增强需求描述(以本地文件或 GitHub issue URL 提供)以及当前代码库,检查实现计划的覆盖度、正确性和契合度。该技能明确不执行实现,只做评审。

主要能力

  • 读取实现计划(本地文件路径)和需求(本地文件路径或 GitHub issue 编号)。
  • 若用户提供 GitHub issue 编号,优先使用附带脚本抓取到本地文件:bash scripts/fetch_github_issue.sh <issue-number> --out /tmp/issue.md。
  • 应用版本中立策略:除非仓库规则、用户指令、发布计划或 issue 文本明确要求,否则不要求缺失的版本号变更;也不因 issue 未提及版本管理而建议删除版本号变更步骤。
  • 应用评审噪声策略:不因实现计划省略开发者执行机制(如检查 /.dockerenv、选择主机与 devcontainer 命令前缀等)而提出发现;不教授命令调用机制;从语义上评审验证范围。
  • 验证代码库实际情况:先用 rg 查找引用的模块、配置、环境变量和测试,再打开最小文件集确认模式与命名,必要时扩大范围。
  • 若计划涉及 MCP 工具、REST API、文档或测试,交叉检查相关 .cursor/rules/*.mdc 指南。
  • 对候选发现进行独立裁决:每个候选创建独立目录,包含 input.md、full-report.md、brief.md,启动独立子代理运行裁决协议。
  • 最终输出固定格式的评审,包含六个部分。

使用方式

  1. 准备干净的评审运行:在技能目录下运行 bash scripts/new_scratchpads_dir.sh <plan-file>,使用脚本打印的绝对路径作为本次评审运行目录,不要自行猜测或通配 scratchpads/ 下的路径。每次运行创建新的时间戳目录,不删除任何内容。
  2. 完整读取两份输入:计划文件和 issue 描述文件(或抓取的 /tmp/issue.md)。
  3. 应用版本中立与评审噪声策略。
  4. 验证代码库实际情况,建议命令包括:
    • rg -n "name_in_plan|function_in_plan|ENV_VAR_IN_PLAN" -S .
    • rg -n "ToolResponse\\[|@mcp\\.tool\\(|log_tool_invocation" blockscout_mcp_server -S
    • rg -n "ServerConfig\\(|BaseSettings\\(|BLOCKSCOUT_" blockscout_mcp_server/config.py -S
    • rg -n "pytest\\.mark\\.integration|tests/integration|tests/tools" tests -S
  5. 独立裁决候选发现:先完整阅读 references/finding-adjudication-protocol.md 和 assets/finding-adjudication-report.md,为每个候选创建目录并写入 input.md,然后为每个候选启动一个独立子代理,使用 fork_turns="none",优先使用强推理模型。子代理必须写入 full-report.md,运行 scripts/finalize_adjudication.py,修复所有验证错误,并只返回协议的简短完成记录。
  6. 所有裁决完成后,运行验证:python3 scripts/verify_adjudication_run.py --run <absolute-run-directory> --expected-count <candidate-count>。若验证失败,将确切错误发回负责的裁决者要求修正并重新定稿。
  7. 先读取所有有效的 brief.md,仅在需要渐进披露时打开完整报告或提取标记部分。提取命令:python3 scripts/finalize_adjudication.py --report <candidate-directory>/full-report.md --extract <section-slug>。
  8. 主代理负责跨发现工作:去重、解决冲突、应用统一严重性等级、评估累积范围。只有 Confirmed、可操作的 Downgraded 和未解决的 Question 候选可进入最终第 4 节,省略 Closed 候选。最终评论的 Scratchpad 字段指向候选生成的 brief.md,绝不直接指向 full-report.md。

输出格式

评审必须包含以下部分:

  1. Understanding:issue 摘要、验收标准(项目符号列表)。
  2. Plan ↔ Requirements coverage:覆盖良好的部分、缺失或模糊的部分。
  3. Codebase alignment:检查的关键文件/模块(含路径)、计划中与代码库匹配的假设、不匹配的假设(解释并建议修正)。
  4. Review comments (actionable):每条评论包含 Severity(Blocker | Major | Minor | Question | Nit)、Location、Problem、Recommendation、Rationale、Scratchpad(可操作且非纯 Question 时指向候选生成的 brief.md)。测试缺口规则:每个具体缺失或错误的测试都作为可操作评论列入第 4 节;第 6 节提供合并清单引用这些条目而不重复完整解释。
  5. Junior-dev readiness check:缺失的任务特定前置条件、步骤顺序和验证覆盖;不标记省略的环境特定命令调用细节;计划需要更明确细节的地方。
  6. Test & rollout strategy:合并测试清单(Unit / Integration / E2E / Negative & security / Performance & regression),引用第 4 节测试评论;迁移/回滚计划(如适用);功能标志/安全发布建议(如适用)。

评审重点清单

  • 覆盖:每个验收标准映射到计划步骤。
  • 代码库对齐:路径、模块结构、命名、现有辅助函数和模式。
  • 边界情况与兼容性:分页、超时、空结果、截断限制、向后兼容。
  • 安全:输入验证、SSRF/DNS 重绑定边界、密钥处理、日志脱敏、认证假设。
  • 性能/规模:API 调用次数、缓存、分页策略、长时间运行任务/进度更新。
  • 运维/可观测性:错误处理、日志、指标/遥测/分析影响、发布/回滚。
  • 版本管理:仅在 issue 描述明确要求时评论;否则假设省略是有意为之。

适用场景

适用于需要对照需求和现有代码库评审实现计划的开发流程,尤其是涉及 MCP 工具、REST API、文档或测试的项目。

限制

该技能不执行实现。抓取 GitHub issue 是网络操作;在沙箱化命令执行时,需为确切抓取命令请求网络升级(require_escalated),而不是授予可复用的宽泛 bash 权限。脚本失败时区分网络不可用(退出码 6)、进程无凭据(退出码 3)、其他 GitHub 抓取失败(退出码 4)和本地输出失败(退出码 5)。