review-merge-readiness

请求代码审查（结构化审查：需求对齐 + 生产就绪性）

目标：让代码审查成为可重复的流程，而不是随意发表评论。

核心原则：尽早审查，经常审查。

必须进行审查的时机

强制要求：

• 完成重要功能后
• workflow-execute-plans 的每个批次结束后（默认每批 3 个任务）
• 合并到主分支之前

可选但很有价值：

• 遇到阻碍时（获取新的视角）
• 大规模重构之前（先建立基线）
• 修复复杂 Bug 后（验证没有引入新的回归问题）

如何发起（最少信息集）

1）确定审查范围（git SHA）

优先使用“计划／任务开始前的基线”作为 BASE_SHA：

# Common approach: use main as baseline
BASE_SHA=$(git merge-base HEAD main 2>/dev/null || git merge-base HEAD master)
HEAD_SHA=$(git rev-parse HEAD)

如果只想审查小型任务中最近的一次提交：

BASE_SHA=$(git rev-parse HEAD~1)
HEAD_SHA=$(git rev-parse HEAD)

2）准备审查依据（计划／需求）

审查必须提供：

• WHAT_WAS_IMPLEMENTED：刚刚完成的内容（1-3 个要点）
• PLAN_OR_REQUIREMENTS：对应的计划摘录或需求文档路径（例如 run_dir/03-plans/features/<feature_slug>-plan.md）

3）获取差异（证据）

git diff --stat "$BASE_SHA..$HEAD_SHA"
git diff "$BASE_SHA..$HEAD_SHA"

审查执行方式（任选其一）

方式 A：子 Agent 审查（如果系统支持）

使用模板：review-merge-readiness/code-reviewer.md，填写占位符并执行。

方式 B：自我审查（无需子 Agent）

按照模板检查清单逐项检查，并输出相同的结构化结果（优势 + 按严重程度分类的问题 + 结论）。

审查输出格式（必须采用结构化格式）

输出必须包含：

• 优势：具体的优点（至少 1 项）
• 问题：按严重程度分类：
  • 严重（必须修复）：安全／数据丢失／功能缺陷／可能导致生产事故的问题
  • 重要（应该修复）：明显糟糕的架构／缺少错误处理／测试缺口／需求不符
  • 轻微（有则更好）：风格／小幅优化／文档润色
• 评估：是否已准备好合并（是／否／修复后可以）+ 1-2 句技术理由

每个问题必须包含：

• 位置：file:line
• 问题所在
• 影响原因
• 修复方法（提供最小改动建议）

与其他审查技能的关系

• review-clean-code：更侧重于“可维护性／整洁度”，适合深入调查代码异味
• review-react-best-practices：更侧重于 React/Next.js 性能模式（瀑布流／包体积／重复渲染）。当差异涉及 React UI、数据获取或性能敏感区域时使用。
• 本技能：更侧重于“需求对齐／生产就绪性／合并结论”，以得出结论为导向

如果你只想知道“能否合并”，请使用本技能。 如果你想进行深入的健康检查，请另外调用 review-clean-code。