multi-agent-pr

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Multi-Agent PR & Code Review Workflow

多Agent PR与代码审查工作流

Handle pull requests and code reviews in projects with multiple AI review assistants.

Requirements: GitHub repository with GitHub CLI (

gh

) installed and authenticated.

Key insight: Review bots (Gemini, Codex) don't read skills and post inline comments. This skill teaches implementers how to check ALL feedback sources and respond systematically.

在使用多AI审查助手的项目中处理拉取请求和代码审查。

要求： 已安装并认证GitHub CLI（

gh

）的GitHub仓库。

核心要点： 审查机器人（Gemini、Codex）不会读取技能文档，只会发布行内评论。本技能指导使用者如何检查所有反馈来源并系统地做出响应。

Quick Commands

快速命令

Note: Run scripts from repository root, not from

.claude/skills/

directory.

注意： 请从仓库根目录运行脚本，不要在

.claude/skills/

目录下运行。

Check All Feedback (CRITICAL - Use First)

检查所有反馈（至关重要 - 优先使用）

bash

.claude/skills/multi-agent-pr/scripts/check-pr-feedback.sh [PR_NUMBER]

Checks all three sources: conversation comments, inline comments, reviews.

If no PR number provided, detects current PR from branch.

bash

.claude/skills/multi-agent-pr/scripts/check-pr-feedback.sh [PR_NUMBER]

检查以下三类来源：会话评论、行内评论、审查意见。

若未提供PR编号，将自动从当前分支检测对应的PR。

Reply to Inline Comment

回复行内评论

bash

.claude/skills/multi-agent-pr/scripts/reply-to-inline.sh <COMMENT_ID> "Your message"

Replies in-thread to inline bot comments. Uses

-F

flag (not

--raw-field

) which properly handles numeric ID conversion in

gh

CLI.

Must be run from repository root with an active PR branch.

Important: Always sign inline replies with your agent identity (e.g.,

—Claude Sonnet 4.5

—GPT-4

—Custom Agent

) to distinguish agent responses from human responses in the GitHub UI.

bash

.claude/skills/multi-agent-pr/scripts/reply-to-inline.sh <COMMENT_ID> "Your message"

在对应线程中回复机器人的行内评论。使用

-F

标志（而非

--raw-field

），该标志可在

gh

CLI中正确处理数字ID转换。

必须从仓库根目录运行，且当前分支需关联一个已打开的PR。

重要提示： 行内回复必须标注你的Agent身份（例如：

—Claude Sonnet 4.5

、

—GPT-4

、

—Custom Agent

），以便在GitHub界面中区分Agent回复与人工回复。

Commit Workflows

提交工作流

Quick Commit (No Approval)

快速提交（无需审批）

Allowed when:

Not on
```
main
```
/
```
master
```
No
```
--force
```
needed
Changes clearly scoped

bash

git add -A
git commit -m "<type>: <outcome>"
git push  # if requested

Types:

feat

fix

refactor

docs

chore

test

满足以下条件时可使用：

不在
```
main
```
/
```
master
```
分支
无需使用
```
--force
```
参数
变更范围清晰明确

bash

git add -A
git commit -m "<type>: <outcome>"
git push  # 若需要

类型可选：

feat

fix

refactor

docs

chore

test

Safe Commit (With Inspection)

安全提交（含检查）

Required for

main

master

or ambiguous changes:

Inspect:

git status --porcelain && git diff --stat

Wait for approval if ambiguous
Stage selectively:
```
git add -A
```
or
```
git add -p <files>
```
Commit:
```
git commit -m "<type>: <outcome>"
```
Push (never
```
--force
```
)
Report: branch, commit hash, pushed (yes/no)

在

main

master

分支或变更内容模糊时必须使用：

检查状态：

git status --porcelain && git diff --stat

若内容模糊，等待审批
选择性暂存：
```
git add -A
```
或
```
git add -p <files>
```
提交：
```
git commit -m "<type>: <outcome>"
```
推送（禁止使用
```
--force
```
）
报告：分支名称、提交哈希、是否已推送（是/否）

Self-Check Before Commit

提交前自检

Before committing, verify:

Test changes - If modifying working code based on suggestions, test first
Check latest feedback - Run feedback check script to catch new comments
User confirmation - If user is active in session, ask before committing
Verify claims - If Fix Report says "verified:", actually verify

Example check:

bash

undefined

提交前请验证：

测试变更 - 若根据建议修改了可运行代码，请先测试
检查最新反馈 - 运行反馈检查脚本以捕获新评论
用户确认 - 若用户在会话中处于活跃状态，提交前请询问
验证声明 - 若修复报告中包含"verified:"，请实际进行验证

示例检查流程：

bash

undefined

1. Test changes (run project-specific tests)

1. 测试变更（运行项目特定的测试命令）

npm test # or: pytest, go test, etc.

npm test # 或：pytest, go test 等

2. Check for new feedback since last check

2. 检查自上次检查以来的新反馈

.claude/skills/multi-agent-pr/scripts/check-pr-feedback.sh

(prevents "ready to merge" when new comments exist)

（避免在存在新评论时标记PR为"可合并"）

3. If user active: "Ready to commit these changes?"

3. 若用户活跃："是否准备提交这些变更？"

undefined

undefined

PR Creation

PR创建

Set Up Template (Once)

设置模板（仅需一次）

Create

.github/pull_request_template.md

markdown

undefined

创建

.github/pull_request_template.md

文件：

markdown

undefined

Summary

摘要

How to test

测试方法

Notes

说明

Agent review loop: PR Conversation comments only (for agent-reviewers). External bots may use inline comments. See workflow docs.


Or copy from `assets/pr_template.md`.

Agent审查循环：仅在PR会话区评论（面向审查Agent）。外部机器人可能使用行内评论。请查看工作流文档。


或从 `assets/pr_template.md` 复制模板。

Create PR

创建PR

Fill Summary, How to test, and Notes sections.

填写摘要、测试方法和说明部分。

Code Review Coordination

代码审查协调

Agent Roles

Agent角色

Agent Type	Posts Where	Format
Agent-reviewers (Claude, GPT-4, custom)	Conversation	Top-level comments
External review bots (Gemini, Codex)	Inline	File/line threads
Human reviewers	Mixed	Conversation or inline

Agent类型	发布位置	格式
审查Agent（Claude、GPT-4、自定义Agent）	会话区	顶层评论
外部审查机器人（Gemini、Codex）	行内	文件/代码行线程
人工审查者	混合	会话区或行内

Critical Rule: Check ALL Three Sources

关键规则：检查所有三类来源

bash

.claude/skills/multi-agent-pr/scripts/check-pr-feedback.sh

Why: External bots post inline comments even though agent-reviewers use conversation. Missing any source = missing feedback.

Three sources:

Conversation comments - Agent-reviewers post here
Inline comments - Gemini, Codex, security bots post here
Reviews - State + optional body

bash

.claude/skills/multi-agent-pr/scripts/check-pr-feedback.sh

原因： 即使审查Agent使用会话区，外部机器人仍会发布行内评论。遗漏任何一类来源都会导致错过反馈。

三类来源：

会话评论 - 审查Agent在此发布
行内评论 - Gemini、Codex、安全机器人在此发布
审查意见 - 状态 + 可选正文

Responding to Inline Bot Comments

回复机器人的行内评论

Address the feedback in code
Reply inline to each comment (sign with agent identity):

bash

.claude/skills/multi-agent-pr/scripts/reply-to-inline.sh <COMMENT_ID> "Fixed @ abc123. [details] —[Your Agent Name]"

Include in Fix Report (conversation comment) — the Fix Report summarizes all changes, but inline replies ensure each bot comment gets a direct acknowledgment

在代码中处理反馈
逐行回复每个评论（标注Agent身份）：

bash

.claude/skills/multi-agent-pr/scripts/reply-to-inline.sh <COMMENT_ID> "Fixed @ abc123. [详情] —[你的Agent名称]"

纳入修复报告（会话区评论）——修复报告汇总所有变更，但行内回复可确保每个机器人评论都得到直接确认

Fix Reporting

修复报告

After addressing feedback, post ONE conversation comment:

markdown

undefined

处理完反馈后，在会话区发布一条评论：

markdown

undefined

Fix Report

修复报告

[file.ext:L10 Symbol]: FIXED @ abc123 — verified:
```
npm test
```
passes
[file.ext:L42 fn]: WONTFIX — reason: intentional per AGENTS.md
[file.ext:L100 class]: DEFERRED — tracking: #123
[file.ext:L200 method]: QUESTION — Should this handle X?

@reviewer-username please re-review.

undefined

[file.ext:L10 Symbol]: FIXED @ abc123 — 已验证：
```
npm test
```
执行通过
[file.ext:L42 fn]: WONTFIX — 原因：根据AGENTS.md为有意设计
[file.ext:L100 class]: DEFERRED — 跟踪链接：#123
[file.ext:L200 method]: QUESTION — 此处是否应处理X场景？

@reviewer-username 请重新审查。

undefined

Fix Statuses

修复状态

Status	Required Info
FIXED	Commit hash + verification command/result
WONTFIX	Reason (cite docs if applicable)
DEFERRED	Issue/ticket link
QUESTION	Specific question to unblock

See
references/fix-report-examples.md
for real-world examples.

Use

assets/fix-report-template.md

as starting point.

状态	必填信息
FIXED	提交哈希 + 验证命令/结果
WONTFIX	原因（适用时引用文档）
DEFERRED	问题/工单链接
QUESTION	用于解除阻塞的具体问题

请查看
references/fix-report-examples.md
获取真实示例。

可使用

assets/fix-report-template.md

作为起始模板。

Review Format (For Agent-Reviewers)

审查格式（面向审查Agent）

Agent-reviewers MUST post ONE top-level conversation comment:

markdown

undefined

审查Agent必须在会话区发布一条顶层评论：

markdown

undefined

Review - Actionable Findings

审查 - 可执行发现

Blocking

path/file.ext:L10-L15 (Symbol): Issue → Fix → Verify:
```
command
```

Optional

path/file.ext:L100 (class): Improvement → Fix


Rules:

- Blocking MUST include verification (runnable command or objective check)
- Use `file:line` + symbol anchor
- Actionable, not prose
- Group by severity

**Do NOT:**

- Create inline file/line comments
- Submit GitHub review submissions
- Post multiple separate comments

**Why:** Inline comments harder to retrieve. Conversation comments deterministic.

阻塞项

path/file.ext:L10-L15 (Symbol): 问题 → 修复方案 → 验证命令：
```
command
```

可选优化

path/file.ext:L100 (class): 优化建议 → 修复方案


规则：

- 阻塞项必须包含验证方式（可运行的命令或客观检查标准）
- 使用 `file:line` + 符号锚点
- 内容需可执行，而非纯描述性文字
- 按严重程度分组

**禁止：**

- 创建行内文件/代码行评论
- 提交GitHub审查意见
- 发布多条独立评论

**原因：** 行内评论难以检索，会话区评论具有确定性。

Re-Review Loop

重新审查循环

After Fix Report:

Request re-review:

@reviewer please re-review. See Fix Report.

Tag ALL reviewers who provided feedback
If QUESTION items: Wait for clarification
If blocking feedback was only provided inline: Mention it was addressed, optionally ask to mirror to conversation for future determinism

发布修复报告后：

请求重新审查：

@reviewer 请重新审查。详情请查看修复报告。

标注所有提供过反馈的审查者
若存在QUESTION项：等待澄清
若阻塞反馈仅在行内发布：提及已处理该反馈，可选择要求将来镜像至会话区以确保确定性

Multi-Agent Patterns

多Agent模式

Duplicate Feedback

重复反馈

If multiple agents flag same issue:

markdown

- [file.php:L42 (ALL flagged)]: FIXED @ abc123 — verified: `npm test` passes
  - Gemini: "use const"
  - Codex: "prefer immutable"
  - Claude: "const prevents reassignment"

若多个Agent标记了同一问题：

markdown

- [file.php:L42 (所有Agent均标记)]: FIXED @ abc123 — 已验证：`npm test` 执行通过
  - Gemini: "使用const"
  - Codex: "优先使用不可变变量"
  - Claude: "const可防止重新赋值"

Conflicting Suggestions

冲突建议

markdown

- [file.php:L100]: QUESTION — Gemini suggests pattern A, Codex suggests pattern B. Which aligns with project conventions? See AGENTS.md.

markdown

- [file.php:L100]: QUESTION — Gemini建议使用模式A，Codex建议使用模式B。哪一种符合项目规范？请查看AGENTS.md。

Finding Specific Bot Comments

查找特定机器人评论

bash

undefined

bash

undefined

Set REPO and PR for your context

为你的环境设置REPO和PR

REPO="owner/repo" # or: gh repo view --json nameWithOwner -q .nameWithOwner PR=42 # or: gh pr view --json number -q .number

REPO="owner/repo" # 或：gh repo view --json nameWithOwner -q .nameWithOwner PR=42 # 或：gh pr view --json number -q .number

Find Gemini comment about "JavaScript"

查找Gemini关于"JavaScript"的评论

gh api repos/$REPO/pulls/$PR/comments
--jq '.[] | select(.user.login == "gemini-code-assist[bot]" and (.body | contains("JavaScript"))) | {id, line, path}'

undefined

gh api repos/$REPO/pulls/$PR/comments
--jq '.[] | select(.user.login == "gemini-code-assist[bot]" and (.body | contains("JavaScript"))) | {id, line, path}'

undefined

Troubleshooting

故障排除

"Can't find review comments" → Check all three sources. Use

.claude/skills/multi-agent-pr/scripts/check-pr-feedback.sh

, not just

gh pr view

"Bot posted inline, should I reply inline?" → Address in code, include in Fix Report, optionally reply inline with brief ack.

"Multiple agents flagged same issue" → Fix once, report once (note all sources), tag all reviewers.

"Conflicting suggestions" → Mark QUESTION, check project docs, cite specific suggestions.

"Script can't detect PR" → Run from repository root (not

.claude/skills/

). Must be on branch with open PR.

"Reply script fails with HTTP 422" → Use

-F in_reply_to=ID

not

--raw-field

. The

-F

flag works correctly with

gh

CLI for numeric IDs.

"Bot suggestion broke working code" → Always test suggestions before committing. Some bot suggestions may be incorrect or context-dependent.

"Committed before checking latest feedback" → Run feedback check script immediately before declaring PR "ready" or "complete."

"无法找到审查评论" → 检查所有三类来源。使用

.claude/skills/multi-agent-pr/scripts/check-pr-feedback.sh

，而非仅使用

gh pr view

。

"机器人发布了行内评论，我需要回复吗？" → 在代码中处理，纳入修复报告，可选择性地在行内回复简短确认。

"多个Agent标记了同一问题" → 修复一次，报告一次（注明所有来源），标注所有审查者。

"建议存在冲突" → 标记为QUESTION，检查项目文档，引用具体建议。

"脚本无法检测PR" → 从仓库根目录运行（而非

.claude/skills/

目录）。当前分支必须关联一个已打开的PR。

"回复脚本返回HTTP 422错误" → 使用

-F in_reply_to=ID

而非

--raw-field

。

-F

标志在

gh

CLI中可正确处理数字ID。

"机器人的建议破坏了可运行代码" → 提交前务必测试建议。部分机器人建议可能不正确或依赖特定上下文。

"未检查最新反馈就提交了" → 在将PR标记为"可合并"或"完成"前，立即运行反馈检查脚本。

Summary

摘要

Key principles:

Always check all three sources (conversation + inline + reviews)
Agent-reviewers use conversation only
External bots use inline (expected)
One Fix Report per round
Tag all reviewers explicitly

Most common mistake: ❌ Only checking conversation or

gh pr view

✅ Always run

.claude/skills/multi-agent-pr/scripts/check-pr-feedback.sh

核心原则：

始终检查所有三类来源（会话区 + 行内 + 审查意见）
审查Agent仅使用会话区
外部机器人使用行内评论（符合预期）
每轮审查仅发布一份修复报告
明确标注所有审查者

最常见错误： ❌ 仅检查会话区或使用

gh pr view

✅ 始终运行

.claude/skills/multi-agent-pr/scripts/check-pr-feedback.sh