zcode-review-deep

name: zcode-review-deep description: "多智能体深度代码审查技能。对单次 Commit/PR/模块执行 4+ 维度并行专项审查，合并去重后生成结构化修复任务与最终报告。" argument-hint: "[--mode commit|pr|module|frz] [--ref REF] [--base BASE] [--head HEAD] [--path PATH] [--frz-ref FRZ_REF] [--output-dir .cr-deep]" allowed-tools: - Read - Write - Edit - Bash - Agent - AskUserQuestion

zcode-review-deep

多智能体深度代码审查技能。对单次 Commit/PR/模块执行多维度并行专项审查，合并去重后生成结构化修复任务与最终报告。

1. 目标与非目标

1.1 目标

• 对单次 Commit/PR/模块执行 4+ 维度并行专项审查，捕获深层缺陷与架构风险
• 多 Agent 独立审查后合并去重，生成结构化问题清单与修复任务
• 提供带证据链的审查结论，支撑人工决策而非替代人工决策
• 产出可机器消费的 JSON 产物与可人工阅读的 Markdown 报告，支持 CI 集成

1.2 非目标

• 不替代 bmad-code-review（互补；bmad 用于快速扫描，deep 用于关键 PR）
• 不自动修改源代码（仅生成修复任务，人工决定是否执行）
• 不做合并/发布 Gate 决策（仅提供证据，决策权保留给人类）
• 不覆盖全量回归测试（聚焦变更范围，不保证无漏测）

2. 输入/输出

2.1 输入

2.2 输出

2.3 退出码

3. 执行步骤

1. Initialize — 解析参数，生成 batch_id，创建输出目录，捕获输入快照
2. Role Selection — 根据变更内容选择 2-4 个专业 Agent + 1 个 Moderator，写入 role-panel.json
3. Parallel Review — 并行 Spawn 各 Agent 执行审查，每个 Agent 写入 {agent_id}-review.json
4. Merge & Conflict Detection — Moderator 合并去重，检测严重级别冲突，写入 consolidated-review.json + review-conflicts.json
5. Consensus Build — 相邻级别冲突自动取高级别，写入 review-consensus.json
6. Fix Task Generation — 为 P0/P1 问题生成修复任务，写入 fix-tasks.json
7. Report Synthesis — 生成 final-report.md

详细执行逻辑见下方 ## Execution Protocol 章节。

Execution Model

本技能采用协作式执行架构：

注意：本技能是纯 SKILL.md 实现，所有流程逻辑由外层 AI Agent 执行。 validate.py 仅用于验证输出产物是否符合 JSON Schema 契约。

Output Schema

所有输出产物必须符合以下 JSON Schema：

Issue Schema（每条问题）

{
  "issue_id": "{batch_id}-{agent_id}-{severity}-{seq:03d}",
  "severity": "P0 | P1 | P2 | P3",
  "dimension": "如 C01-Consistency, C03-Logic",
  "file": "相对文件路径",
  "line_range": [10] 或 [10, 20],
  "evidence": "精确代码片段（带行号）",
  "description": "问题描述",
  "found_by": ["agent_id1", "agent_id2"]
}

Severity 级别

Execution Protocol

1. Initialize

   • 解析参数，生成 batch_id
   • 创建输出目录结构
   • 捕获输入快照（git diff, PR description）

2. Role Selection

   • 根据变更内容选择 2-4 个专业 Agent + 1 个 Moderator
   • 写入 role-panel.json

3. Parallel Review

   • 并行 Spawn 各 Agent 执行审查
   • 每个 Agent 写入 {agent_id}-review.json

4. Merge & Conflict Detection

   • Moderator 合并去重
   • 检测严重级别冲突（≥2 级或 P0 vs "none"）
   • 写入 consolidated-review.json + review-conflicts.json

5. Consensus Build

   • 相邻级别冲突自动取高级别
   • 写入 review-consensus.json

6. Fix Task Generation

   • 为 P0/P1 问题生成修复任务
   • 写入 fix-tasks.json

7. Report Synthesis

   • 生成 final-report.md

Artifact Directory Structure

{output_dir}/{batch_id}/
├── batch-state.json
├── role-panel.json
├── reviews/
│   ├── {agent1}-review.json
│   └── {agent2}-review.json
├── consolidated-review.json
├── review-conflicts.json
├── review-consensus.json
├── fix-tasks.json
└── final-report.md

Validation

使用 validate.py 验证输出产物是否符合 Schema 契约：

# 验证整个批次
python validate.py .cr-deep/CR-20260527-001

# 安装依赖
pip install jsonschema

Non-Negotiable Rules

• 审查阶段不修改源文件
• 不捏造问题 — 每个发现必须有精确代码证据
• 纯风格问题不得标记为 P0/P1
• 所有产物立即写入磁盘，不保留内存状态

Pitfalls / 常见坑与规避

Usage

在 Claude Code 中调用：

/zcode-review-deep --mode commit --ref HEAD~1
/zcode-review-deep --mode pr --base main --head feature/x
/zcode-review-deep --mode module --path src/services/order/

预期输出路径：