Use Subagents for Code Review and Triage

TL;DR

Use subagents when review or triage work benefits from separate specialist attention. Give each subagent a narrow lens, minimal tools, and a strict output contract. The main Claude session should combine the results, remove duplicate or low-confidence findings, and keep a human in control of public comments, labels, assignments, and merge decisions.

This guide is about review and triage operations after you have already chosen subagents as the right Claude Code extension surface.

Prerequisites & Requirements

• {"task": "Review target is defined", "description": "The workflow points to a pull request, issue search, release branch, or incident queue"}
• {"task": "Subagent roles are narrow", "description": "Each role has one review lens such as security, tests, docs, release risk, or issue routing"}
• {"task": "Tool scope is reviewed", "description": "Read-only access is used by default and write-capable tools require approval"}
• {"task": "Output contract is documented", "description": "Findings include evidence, severity, confidence, and recommended next action"}
• {"task": "Human owner is known", "description": "A maintainer decides what gets posted, labeled, assigned, or merged"}

Core Concepts Explained

Subagents isolate review attention

Claude Code subagents are useful when a task deserves its own role, instructions, and context. For code review and triage, that separation helps avoid one large prompt trying to be a security reviewer, test planner, docs reviewer, and issue router at the same time.

Review subagents should be evidence-first

A review subagent should not only say "this might be risky." Ask it to cite the file, line, diff hunk, test failure, documentation gap, issue link, or external source that supports the finding. This keeps the final review actionable and prevents low-confidence comments from crowding out real blockers.

Triage subagents classify instead of deciding alone

Issue triage often involves labels, ownership, severity, reproducibility, and duplicate detection. A subagent can prepare a recommendation, but final action should stay with a human owner unless the team has explicit automation rules.

The main session is the editor

The main Claude session should reconcile subagent outputs before anything is posted. It can merge duplicate findings, discard unsupported claims, rank the remaining risks, and turn several specialist reports into one clear review.

Step-by-Step Workflow

1. Choose the review lanes. Pick two to five focused lenses instead of one giant reviewer. Common lanes are security, correctness, tests, docs, release risk, dependency impact, and issue routing.

2. Write narrow subagent prompts. Each prompt should describe the exact job, what evidence counts, what to ignore, and what output format to return. Avoid broad mandates such as "review everything."

3. Scope tools to the lane. A docs reviewer may only need repository reads. A test planner may need file reads and existing test output. A triage reviewer may need issue and pull request metadata. Start read-only.

4. Give structured inputs. Provide the pull request summary, changed files, relevant issue links, failing checks, or filtered issue search. Small, relevant packets produce better reports than a raw context dump.

5. Ask for confidence and evidence. Require each finding to include evidence, severity, confidence, and a concrete next step. Ask subagents to say "no finding" when evidence is insufficient.

6. Reconcile in the main session. Combine reports, remove duplicates, check contradictions, and keep only findings that a maintainer could verify.

7. Human-review outward actions. A human should approve public comments, labels, assignments, close/reopen decisions, and merge blockers before they leave the Claude session.

Useful Subagent Roles

Prompt Shape

Use a compact prompt contract for each subagent:

Role: Review this pull request for test coverage gaps only.
Inputs: PR summary, changed files, existing test output, linked issue.
Ignore: style-only comments and product decisions outside the diff.
Return:
- Findings with file/path evidence
- Missing tests ranked by user impact
- Confidence: high, medium, or low
- Suggested validation command, if one is already documented

For issue triage:

Role: Triage this filtered issue list for duplicates and ownership.
Inputs: issue titles, bodies, labels, assignees, links, recent comments.
Return:
- Likely duplicates with evidence
- Suggested label changes with reason
- Suggested owner or team, if clear
- Items that need human clarification

Review Checklist

• {"task": "One lens per subagent", "description": "No subagent tries to review every dimension at once"}
• {"task": "Evidence required", "description": "Findings cite files, lines, check output, issue links, or quoted context"}
• {"task": "Read-only default", "description": "Subagents cannot post comments, mutate labels, or push changes by default"}
• {"task": "False-positive filter", "description": "The main session drops unsupported or duplicate findings"}
• {"task": "Human approval", "description": "Maintainers approve public comments and workflow actions"}
• {"task": "Privacy review", "description": "Sensitive reports, credentials, and customer data stay out of prompts"}

Troubleshooting

• Subagents return overlapping findings: make the roles narrower and add an "ignore" list to each prompt.
• Findings are too vague: require direct evidence and ask for "no finding" when the evidence is weak.
• Triage suggestions are too aggressive: separate recommendations from actions, and keep labels or closure decisions human-approved.
• The workflow uses too much context: provide a PR summary, changed-file list, and focused excerpts before sending full logs or issue histories.
• A subagent wants write access: first ask whether the same result can be achieved by returning a recommendation to the main session.

Duplicate Check

This guide is specifically about using Claude Code subagents as review and triage specialists. Existing entries cover broad agent development, parallel subagent distribution, subagent creation commands, and local code review skills, but they do not provide a source-backed guide for evidence-based review and issue-triage workflows with subagents.

References

• Claude Code subagents - https://code.claude.com/docs/en/sub-agents
• Claude Code settings - https://code.claude.com/docs/en/settings
• GitHub pull request review docs - https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request
• GitHub issue and pull request search docs - https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/filtering-and-searching-issues-and-pull-requests