用途
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,启动独立子代理运行裁决协议。 - 最终输出固定格式的评审,包含六个部分。
使用方式
- 准备干净的评审运行:在技能目录下运行
bash scripts/new_scratchpads_dir.sh <plan-file>,使用脚本打印的绝对路径作为本次评审运行目录,不要自行猜测或通配scratchpads/下的路径。每次运行创建新的时间戳目录,不删除任何内容。 - 完整读取两份输入:计划文件和 issue 描述文件(或抓取的
/tmp/issue.md)。 - 应用版本中立与评审噪声策略。
- 验证代码库实际情况,建议命令包括:
rg -n "name_in_plan|function_in_plan|ENV_VAR_IN_PLAN" -S .rg -n "ToolResponse\\[|@mcp\\.tool\\(|log_tool_invocation" blockscout_mcp_server -Srg -n "ServerConfig\\(|BaseSettings\\(|BLOCKSCOUT_" blockscout_mcp_server/config.py -Srg -n "pytest\\.mark\\.integration|tests/integration|tests/tools" tests -S
- 独立裁决候选发现:先完整阅读
references/finding-adjudication-protocol.md和assets/finding-adjudication-report.md,为每个候选创建目录并写入input.md,然后为每个候选启动一个独立子代理,使用fork_turns="none",优先使用强推理模型。子代理必须写入full-report.md,运行scripts/finalize_adjudication.py,修复所有验证错误,并只返回协议的简短完成记录。 - 所有裁决完成后,运行验证:
python3 scripts/verify_adjudication_run.py --run <absolute-run-directory> --expected-count <candidate-count>。若验证失败,将确切错误发回负责的裁决者要求修正并重新定稿。 - 先读取所有有效的
brief.md,仅在需要渐进披露时打开完整报告或提取标记部分。提取命令:python3 scripts/finalize_adjudication.py --report <candidate-directory>/full-report.md --extract <section-slug>。 - 主代理负责跨发现工作:去重、解决冲突、应用统一严重性等级、评估累积范围。只有 Confirmed、可操作的 Downgraded 和未解决的 Question 候选可进入最终第 4 节,省略 Closed 候选。最终评论的 Scratchpad 字段指向候选生成的
brief.md,绝不直接指向full-report.md。
输出格式
评审必须包含以下部分:
- Understanding:issue 摘要、验收标准(项目符号列表)。
- Plan ↔ Requirements coverage:覆盖良好的部分、缺失或模糊的部分。
- Codebase alignment:检查的关键文件/模块(含路径)、计划中与代码库匹配的假设、不匹配的假设(解释并建议修正)。
- Review comments (actionable):每条评论包含 Severity(Blocker | Major | Minor | Question | Nit)、Location、Problem、Recommendation、Rationale、Scratchpad(可操作且非纯 Question 时指向候选生成的
brief.md)。测试缺口规则:每个具体缺失或错误的测试都作为可操作评论列入第 4 节;第 6 节提供合并清单引用这些条目而不重复完整解释。 - Junior-dev readiness check:缺失的任务特定前置条件、步骤顺序和验证覆盖;不标记省略的环境特定命令调用细节;计划需要更明确细节的地方。
- 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)。