subagent-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Subagent Review Skill

子Agent评审技能

1. Review Workflow

1. 评审工作流

1.1. Setup (Fully Automatic)

1.1. 配置（全自动化）

No arguments required. Everything is auto-detected:

Item	Detection
review_type	`git diff main...HEAD` has output -> code, else design
scope	Always `git diff main...HEAD`
context	Directory name pattern (see 1.3.2)

Default: 10 parallel (cx x 5 + cc x 5)

无需参数，所有内容均自动检测：

项目	检测规则
review_type	`git diff main...HEAD` 有输出 -> 代码评审，否则为设计评审
scope	始终为 `git diff main...HEAD`
context	目录名称规则（见1.3.2）

默认配置：10路并行（cx x 5 + cc x 5）

1.2. Priority (Code Review)

1.2. 优先级（代码评审）

Priority	Role	Focus
1	security	OWASP, vulnerabilities
2	architecture	Patterns, structure
3	historian	History, context
4	code	Quality, readability
5	qa	Edge cases, acceptance

For design review: replace

code

with

data

(Data model, schema). Assign: cx first (1-5), then cc (1-5). cx manages token usage of cc.

优先级	角色	关注点
1	安全	OWASP、漏洞
2	架构	模式、结构
3	历史追溯	历史、上下文
4	代码	质量、可读性
5	qa	边界用例、可接受性

设计评审场景：将

code

替换为

data

（数据模型、schema）。分配规则：先运行cx（1-5），再运行cc（1-5）。cx负责管控cc的token使用。

1.3. Scope and Context

1.3. 范围与上下文

1.3.1. Scope (Review Target) - Always Local

1.3.1. 范围（评审目标）- 始终为本地内容

Scope	Command	When
diff	`git diff main...HEAD`	Default. Branch changes
file	Read the file at {path}	User specifies a file path

范围	命令	触发条件
diff	`git diff main...HEAD`	默认，分支变更场景
文件	读取{path}指定的文件	用户指定文件路径时

1.3.2. Context (Metadata) - Auto-detected from Directory Name

1.3.2. 上下文（元数据）- 从目录名称自动检测

Detect PR/Issue number from current directory name pattern:

```
*-pr-{N}
```
-> PR worktree -> fetch PR #{N} metadata
```
*-issue-{N}
```
-> Issue worktree -> fetch Issue #{N} metadata
Otherwise -> no metadata (diff only)

Detection command:

bash

basename "$(git rev-parse --show-toplevel)" | grep -oP '(pr|issue)-\K[0-9]+'

从当前目录名称规则中检测PR/Issue编号：

```
*-pr-{N}
```
-> PR工作树 -> 拉取PR #{N}元数据
```
*-issue-{N}
```
-> Issue工作树 -> 拉取Issue #{N}元数据
其他情况 -> 无元数据（仅diff内容）

检测命令：

bash

basename "$(git rev-parse --show-toplevel)" | grep -oP '(pr|issue)-\K[0-9]+'

1.3.3. Context Fetch Procedure

1.3.3. 上下文拉取流程

Detect type and number from directory name

Fetch primary metadata:

PR:
```
gh pr view {N} --json body,comments
```
Issue:
```
gh issue view {N} --json body,comments
```

For PR: parse body for referenced Issues/PRs (
```
#123
```
,
```
Closes #456
```
, etc.) and fetch each with
```
gh issue view
```
or
```
gh pr view
```
Save all context to CONTEXT_FILE (created with mkoutput)

IMPORTANT: For PR reviews, always chase references in the PR body. Related Issues/PRs provide critical intent and acceptance criteria.

Agent file: @~/.agents/subagents/reviewer-{ROLE}.md

拉取核心元数据：

PR:
```
gh pr view {N} --json body,comments
```
Issue:
```
gh issue view {N} --json body,comments
```

PR场景：解析内容中引用的Issue/PR（
```
#123
```
、
```
Closes #456
```
等）并通过
```
gh issue view
```
或
```
gh pr view
```
拉取每个引用的内容
将所有上下文保存到CONTEXT_FILE（通过mkoutput创建）

重要提示：PR评审时必须追踪PR正文中的引用内容，关联的Issue/PR会提供关键的需求意图和验收标准。

Agent文件： @~/.agents/subagents/reviewer-{ROLE}.md

1.4. Review Execution

1.4. 评审执行

1.4.1. IMPORTANT: Always execute 10-parallel reviews as standard practice

1.4.1. 重要规则：标准流程始终执行10路并行评审

Always execute the following for design/code reviews:

cc x 5: Launch reviewer-* agents in parallel via Task tool
cx x 5: Execute codex exec sequentially via worker-codex

2-parallel execution (worker-claude + worker-codex only) is prohibited.

Task content template:

text

[SUBAGENT capability=READONLY]
<!-- REVIEW_SESSION
timestamp: {TS}, source: {SOURCE}, role: {ROLE}
review_type: {REVIEW_TYPE}
-->
Review the diff in {DIFF_FILE} from {ROLE} perspective.
Context (PR/Issue metadata): {CONTEXT_FILE}
Return your review directly. Do NOT create files.

设计/代码评审始终按照以下规则执行：

cc x 5：通过Task工具并行启动reviewer-* Agent
cx x 5：通过worker-codex顺序执行codex exec

禁止仅执行2路并行（仅worker-claude + worker-codex）。

任务内容模板：

text

[SUBAGENT capability=READONLY]
<!-- REVIEW_SESSION
timestamp: {TS}, source: {SOURCE}, role: {ROLE}
review_type: {REVIEW_TYPE}
-->
从{ROLE}视角评审{DIFF_FILE}中的diff内容。
上下文（PR/Issue元数据）：{CONTEXT_FILE}
直接返回评审结果，不要创建文件。

1.4.2. Method A: Task Tool (Recommended for Claude Code)

1.4.2. 方法A：Task工具（推荐Claude Code使用）

Use Task tool with reviewer agents. Launch multiple Task tools in a single message for parallel execution with clean output isolation.

text

Task tool calls (parallel):
- subagent_type: reviewer-security
- subagent_type: reviewer-architecture
- subagent_type: reviewer-historian
- subagent_type: reviewer-code
- subagent_type: reviewer-qa

Each reviewer agent reads the agent file automatically.

配合评审Agent使用Task工具，在单条消息中启动多个Task工具实现并行执行，输出隔离清晰。

text

Task工具调用（并行）：
- subagent_type: reviewer-security
- subagent_type: reviewer-architecture
- subagent_type: reviewer-historian
- subagent_type: reviewer-code
- subagent_type: reviewer-qa

每个评审Agent会自动读取对应的Agent文件。

1.4.3. Method B: Codex CLI Sequential (Recommended for Codex)

1.4.3. 方法B：Codex CLI顺序执行（推荐Codex使用）

NEVER use background processes (

) with codex exec - causes output interleaving.

bash

for ROLE in security architecture historian code qa; do
  FILE=$(mkoutput --dir reviews --label "${ROLE}-cx")
  codex exec --sandbox workspace-write -o "$FILE" "{task}"
done

codex exec禁止使用后台进程（

），会导致输出交错。

bash

for ROLE in security architecture historian code qa; do
  FILE=$(mkoutput --dir reviews --label "${ROLE}-cx")
  codex exec --sandbox workspace-write -o "$FILE" "{task}"
done

1.4.4. Method C: Codex CLI Parallel (Advanced)

1.4.4. 方法C：Codex CLI并行执行（高级）

For true parallelism without output mixing, use separate terminal sessions or accept that outputs will be written to files (not displayed cleanly).

WARNING: Background execution (

) with

wait

causes stderr/stdout mixing.

要实现无输出混合的真正并行，可以使用独立终端会话，或接受输出写入文件（不会清晰展示）。

警告：搭配

wait

使用后台执行（

）会导致stderr/stdout混合。

1.5. Parallel Execution for 10-Review (cc x 5 + cx x 5)

1.5. 10路评审并行执行（cc x 5 + cx x 5）

IMPORTANT: Start cc and cx reviews simultaneously for true parallelism.

重要提示：同时启动cc和cx评审实现真正并行。

1.5.1. Step 1: Auto-detect and Prepare

1.5.1. 步骤1：自动检测与准备

Run these steps automatically (no user input needed):

bash

undefined

自动执行以下步骤（无需用户输入）：

bash

undefined

1. Save diff

1. 保存diff

DIFF_FILE=$(mkoutput --dir reviews --label review-diff) git diff main...HEAD > "$DIFF_FILE"

2. Detect review_type

2. 检测review_type

if [ -s "$DIFF_FILE" ]; then REVIEW_TYPE="code" else REVIEW_TYPE="design" fi

3. Detect context from directory name

3. 从目录名称检测上下文

DIR_NAME=$(basename "$(git rev-parse --show-toplevel)") PR_NUM=$(echo "$DIR_NAME" | grep -oP 'pr-\K[0-9]+' || true) ISSUE_NUM=$(echo "$DIR_NAME" | grep -oP 'issue-\K[0-9]+' || true)

4. Fetch context metadata

4. 拉取上下文元数据

CONTEXT_FILE=$(mkoutput --dir reviews --label review-context) echo "# Review Context" > "$CONTEXT_FILE"

if [ -n "$PR_NUM" ]; then echo "## PR #${PR_NUM}" >> "$CONTEXT_FILE" gh pr view "$PR_NUM" --json title,body,comments >> "$CONTEXT_FILE"

Chase references: extract #NNN from PR body, fetch each

gh pr view "$PR_NUM" --json body --jq '.body'
| grep -oP '#\K[0-9]+' | sort -u | while read -r REF; do echo "## Referenced #${REF}" >> "$CONTEXT_FILE" gh issue view "$REF" --json title,body,comments >> "$CONTEXT_FILE" 2>/dev/null
|| gh pr view "$REF" --json title,body,comments >> "$CONTEXT_FILE" 2>/dev/null
|| echo "(not found)" >> "$CONTEXT_FILE" done elif [ -n "$ISSUE_NUM" ]; then echo "## Issue #${ISSUE_NUM}" >> "$CONTEXT_FILE" gh issue view "$ISSUE_NUM" --json title,body,comments >> "$CONTEXT_FILE" fi

undefined

CONTEXT_FILE=$(mkoutput --dir reviews --label review-context) echo "# Review Context" > "$CONTEXT_FILE"

if [ -n "$PR_NUM" ]; then echo "## PR #${PR_NUM}" >> "$CONTEXT_FILE" gh pr view "$PR_NUM" --json title,body,comments >> "$CONTEXT_FILE"

追踪引用：从PR正文中提取#NNN，拉取每个引用的内容

undefined

1.5.2. Step 2: Launch cc x 5 (Single Message)

1.5.2. 步骤2：启动cc x 5（单条消息）

In one message, call Task tool 5 times in parallel:

text

Task tool calls (parallel, single message):
- subagent_type: reviewer-security
- subagent_type: reviewer-architecture
- subagent_type: reviewer-historian
- subagent_type: reviewer-code (or reviewer-data for design review)
- subagent_type: reviewer-qa

Each prompt should include:

text

[SUBAGENT capability=READONLY]
Review from {ROLE} perspective.
Diff: {DIFF_FILE}
Context: {CONTEXT_FILE}

在单条消息中并行调用5次Task工具：

text

Task工具调用（并行，单条消息）：
- subagent_type: reviewer-security
- subagent_type: reviewer-architecture
- subagent_type: reviewer-historian
- subagent_type: reviewer-code（设计评审场景为reviewer-data）
- subagent_type: reviewer-qa

每个提示词需要包含：

text

[SUBAGENT capability=READONLY]
从{ROLE}视角进行评审。
Diff：{DIFF_FILE}
上下文：{CONTEXT_FILE}

1.5.3. Step 3: Launch cx x 5 (Background Processes)

1.5.3. 步骤3：启动cx x 5（后台进程）

Use file output to avoid interleaving:

bash

for ROLE in security architecture historian data qa; do
  FILE=$(mkoutput --dir reviews --label "review-${ROLE}-cx")
  codex exec --sandbox workspace-write -o "$FILE" \
    "[SUBAGENT capability=READONLY] Review from ${ROLE} perspective. Diff: ${DIFF_FILE} Context: ${CONTEXT_FILE}" &
done
wait

使用文件输出避免内容交错：

bash

for ROLE in security architecture historian data qa; do
  FILE=$(mkoutput --dir reviews --label "review-${ROLE}-cx")
  codex exec --sandbox workspace-write -o "$FILE" \
    "[SUBAGENT capability=READONLY] Review from ${ROLE} perspective. Diff: ${DIFF_FILE} Context: ${CONTEXT_FILE}" &
done
wait

1.5.4. Step 4: Collect Results

1.5.4. 步骤4：收集结果

bash

undefined

bash

undefined

cx review files are referenced by $FILE variables from Step 3

cx评审文件通过步骤3的$FILE变量引用

cc review results are returned directly by the Task tool

cc评审结果直接由Task工具返回

undefined

undefined

1.5.5. Timing Optimization

1.5.5. 时序优化

Action	Timing
Auto-detect/prep	Before starting reviews
Launch cc x 5	Immediately (Task tool)
Launch cx x 5	Immediately (background)
Collect results	After wait completes

操作	时序
自动检测/准备	启动评审前执行
启动cc x 5	立即执行（Task工具）
启动cx x 5	立即执行（后台进程）
收集结果	wait执行完成后执行

1.6. Reviewer Deliberation (Optional)

1.6. 评审研讨（可选）

IMPORTANT: This is an optional phase. Execute only when:

Running as orchestrator (role name is "orchestrator")
User explicitly requests comprehensive review with deliberation

For standalone execution, Phase 1 (Section 1.5) alone is sufficient.

After Phase 1 review completion, discuss with critic and guardian to collect additional findings.

重要提示：此为可选阶段，仅在以下情况执行：

以编排器（角色名称为"orchestrator"）身份运行
用户明确要求带研讨环节的全面评审

独立执行时仅需阶段1（1.5节）即可。

阶段1评审完成后，与评审员和监护员讨论收集额外发现。

1.6.1. Purpose

1.6.1. 目的

Collect additional findings from other perspectives
Prevent cross-functional oversights
Ensure comprehensive multi-angle coverage

从其他视角收集额外发现
避免跨职能疏漏
确保全面的多视角覆盖

1.6.2. Deliberation Prompt

1.6.2. 研讨提示词

Share all Phase 1 review results with critic and guardian and request additional findings.

text

[SUBAGENT capability=READONLY]
<!-- DELIBERATION_SESSION
timestamp: {TS}, role: {ROLE}
review_type: {REVIEW_TYPE}
-->

将所有阶段1评审结果共享给评审员和监护员，请求额外发现。

text

[SUBAGENT capability=READONLY]
<!-- DELIBERATION_SESSION
timestamp: {TS}, role: {ROLE}
review_type: {REVIEW_TYPE}
-->

Phase 1 Review Results Summary

阶段1评审结果汇总

{List all Phase 1 findings sorted by severity}

{按严重程度排序列出所有阶段1发现}

Questions

问题

Based on other reviewers' findings, from your expert perspective ({ROLE}):

Are there any additional points to raise?
Are there any supplementary points related to other findings?
Are there any overlooked perspectives?

Output in the same format as Phase 1 only if there are additional findings. If no additional findings, explicitly state "No additional findings."

undefined

基于其他评审员的发现，从你的专业视角（{ROLE}）回答：

是否有其他需要提出的问题？
是否有与其他发现相关的补充内容？
是否有被忽略的视角？

仅当有额外发现时，使用与阶段1相同的格式输出。如果没有额外发现，请明确说明"无额外发现。"

undefined

1.6.3. Deliberation Execution

1.6.3. 研讨执行

Execute 10-parallel (cc x 5 + cx x 5) same as Phase 1.

text

Task tool calls (parallel, single message):
- subagent_type: reviewer-security (with Phase 1 results)
- subagent_type: reviewer-architecture (with Phase 1 results)
- subagent_type: reviewer-historian (with Phase 1 results)
- subagent_type: reviewer-code or reviewer-data (with Phase 1 results)
- subagent_type: reviewer-qa (with Phase 1 results)

与阶段1相同，执行10路并行（cc x 5 + cx x 5）。

text

Task工具调用（并行，单条消息）：
- subagent_type: reviewer-security（携带阶段1结果）
- subagent_type: reviewer-architecture（携带阶段1结果）
- subagent_type: reviewer-historian（携带阶段1结果）
- subagent_type: reviewer-code或reviewer-data（携带阶段1结果）
- subagent_type: reviewer-qa（携带阶段1结果）

1.6.4. Result Files

1.6.4. 结果文件

Save deliberation results:

cc: Use Task tool results directly

cx:

FILE=$(mkoutput --dir reviews --label "deliberation-{ROLE}-cx")

保存研讨结果：

cc：直接使用Task工具结果

cx：

FILE=$(mkoutput --dir reviews --label "deliberation-{ROLE}-cx")

1.7. Summary Output

1.7. 汇总输出

Create file:

bash

SUMMARY_FILE=$(mkoutput --dir reviews --label summary)

markdown

undefined

创建文件：

bash

SUMMARY_FILE=$(mkoutput --dir reviews --label summary)

markdown

undefined

Review Summary

评审汇总

Target

目标

Type: {review_type}, Directory: {dir_name}

类型：{review_type}, 目录：{dir_name}

Findings by Phase

各阶段发现

Phase 1: Initial Review

阶段1：初始评审

#	Issue	Reporter	Severity	File
1	{issue description}	{role}-{src}	High	`path/to/file:123`

#	问题	提交者	严重程度	文件
1	{问题描述}	{role}-{src}	高	`path/to/file:123`

Phase 2: Deliberation

阶段2：研讨

#	Issue	Reporter	Triggered By	Severity	File
1	{additional finding}	{role}-{src}	{role}	Medium	`path/to/file:456`

#	额外发现	提交者	触发来源	严重程度	文件
1	{额外发现内容}	{role}-{src}	{role}	中	`path/to/file:456`

Coverage Analysis

覆盖度分析

Perspective	Phase 1	Phase 2	Total
Security	N	M	N+M
Architecture	N	M	N+M
Historian	N	M	N+M
Code/Data	N	M	N+M
QA	N	M	N+M
Total	X	Y	Z

undefined

视角	阶段1	阶段2	总计
安全	N	M	N+M
架构	N	M	N+M
历史追溯	N	M	N+M
代码/数据	N	M	N+M
QA	N	M	N+M
总计	X	Y	Z

undefined

2. Standalone Usage (Lightweight Mode)

2. 独立使用（轻量模式）

For quick reviews without Reviewer Deliberation:

Execute Phase 1 only (Section 1.5)
Collect results (Section 1.5.4)
Create summary (Section 1.7) with Phase 1 only

Skip Phase 2 (Section 1.6) to reduce execution time and token usage.

无需评审研讨的快速评审场景：

仅执行阶段1（1.5节）
收集结果（1.5.4节）
仅使用阶段1结果创建汇总（1.7节）

跳过阶段2（1.6节）以减少执行时间和token消耗。