Claude Code subagents for QA are useful when a test automation review has more than one kind of risk. A single AI chat can miss context when it tries to inspect changed code, failing logs, flaky behavior, assertion quality, and release impact at the same time. A better workflow is to split the review into focused passes, then let the QA engineer make the final decision.

This tutorial shows a practical, screenshot-friendly workflow for using Claude Code subagents as parallel QA reviewers. The goal is not to replace CI, code review, exploratory testing, or human judgment. The goal is to organize the review so defects, weak tests, and missing evidence are easier to spot before a test change is accepted.

What Claude Code Subagents Mean for QA

Anthropic describes Claude Code subagents as specialized assistants that can have their own context windows, custom system prompts, and configured tool permissions. For QA teams, that maps well to repeated review roles:

  • Code risk reviewer: checks what changed and which product behavior may be affected.
  • Test evidence reviewer: inspects failing output, rerun commands, screenshots, traces, logs, and environment notes.
  • Assertion reviewer: looks for status-only checks, shallow UI checks, missing negative paths, and over-mocking.

Subagents can be defined at project level for a repository or at user level for personal reuse. That makes them a good fit for QA standards that should travel with one test suite, while still allowing individual SDETs to keep personal helper workflows.

When to Use This Workflow

Use this workflow when the review is broad enough that one prompt becomes noisy. Good examples include:

  • A pull request that changes both application code and Playwright, Cypress, Selenium, API, or unit tests.
  • A flaky test fix where the root cause might be selector timing, test data, service latency, or an incorrect assertion.
  • An AI-generated test branch that needs careful review before merge.
  • A bug fix where QA needs confidence that the regression test actually protects the reported behavior.

Do not use subagents as an excuse to skip deterministic validation. The final evidence should still include commands run, pass or fail status, relevant logs, and any remaining risk.

Step 1: Define the QA Review Roles

Start with three narrow roles. Keep each one focused enough that its output is easy to review.

# Role 1: Changed-code risk reviewer
Goal: explain what product behavior changed and which tests should cover it.
Output: bullet list of risks, affected files, and suggested validation checks.

# Role 2: Test evidence reviewer
Goal: inspect available failure output and decide whether the evidence proves the fix.
Output: commands reviewed, missing evidence, and rerun recommendations.

# Role 3: Assertion and coverage reviewer
Goal: find weak assertions, missing negative cases, brittle selectors, and over-mocking.
Output: prioritized findings with concrete test improvements.

This structure keeps the focus, angle, and source guidance clear: Claude Code helps organize review work, while the tester owns the acceptance decision.

Step 2: Create Project-Level Subagent Files

For a repository workflow, create subagent definitions in a project-level location so the team can review them like normal test tooling. A compact example for an assertion reviewer could look like this:

---
name: qa-assertion-reviewer
description: Reviews automated tests for weak assertions, missing edge cases, brittle selectors, and maintainability risk.
tools: Read, Grep, Glob
---
You are a QA automation reviewer. Inspect test changes and report only actionable risks.
Focus on:
- assertions that do not prove business behavior
- selectors or waits likely to become flaky
- missing negative, boundary, or permission cases
- overuse of mocks that hides integration risk

Return findings ordered by severity. Include file paths and concise evidence.

Keep permissions conservative for review-only subagents. A subagent that only needs to inspect files does not need broad edit or execution access. If a subagent must run commands, make that explicit and keep the command list aligned with the repository test strategy.

Step 3: Prepare a Review Prompt with Clear Evidence

Before invoking subagents, collect the review inputs. This gives each focused reviewer a clean starting point.

  • Pull request summary or local diff.
  • Changed test files and changed product files.
  • Failing command and latest rerun command.
  • Relevant error output, screenshot, trace, or report path.
  • Known constraints such as test data limits, browser matrix, or API environment.

Then use a prompt like this:

Use the QA subagents to review this test automation change in parallel.

Context:
- Product area: checkout promo-code validation
- Changed files: tests/e2e/promo.spec.ts, src/checkout/promo.ts
- Goal: confirm that the regression test protects the reported bug
- Evidence available: failing CI log, local rerun output, screenshot after fix

Ask:
1. qa-code-risk-reviewer: identify behavior and release risks.
2. qa-test-evidence-reviewer: decide whether current evidence is enough.
3. qa-assertion-reviewer: inspect test assertions, selectors, and missing cases.

Return one consolidated QA decision with blockers, recommended fixes, and commands to run before merge.

The important detail is the final consolidated decision. Parallel review is only useful if the QA engineer can turn the outputs into a short accept, reject, or request-changes decision.

Step 4: Review the Subagent Findings Like a QA Lead

Treat subagent output as review input, not truth. A practical triage order is:

  1. Confirm each finding points to an actual file, command, log line, screenshot, or missing test condition.
  2. Merge duplicate findings across reviewers.
  3. Separate blockers from nice-to-have cleanup.
  4. Reject vague advice that does not improve the test or reduce risk.
  5. Write the final QA decision in language that a developer can act on.

For example, ?add more tests? is not actionable. ?Add a negative test for an expired promo code and assert the visible error message plus disabled submit state? is actionable.

Step 5: Validate with Targeted Commands

After reviewing suggestions, run targeted checks. Pick commands that match the changed risk rather than running only the fastest happy path.

# Example validation shape
npm run lint
npm run test:e2e -- promo
npm run test:api -- promo
npm run test:e2e -- promo -- --repeat-each=3

Use equivalent commands for your stack. If a test is suspected to be flaky, include a small repeat run or a focused retry strategy that your team accepts. Record the command, result, environment, and any remaining risk in the review notes.

Screenshot Plan for the Tutorial

  • Screenshot 1: Claude Code showing the project-level subagent files.
  • Screenshot 2: Review prompt with changed files, failing evidence, and requested subagent roles.
  • Screenshot 3: Parallel findings grouped by code risk, evidence risk, and assertion risk.
  • Screenshot 4: Final QA decision with blockers and commands to run.
  • Screenshot 5: Terminal output from targeted validation commands.

Common Mistakes to Avoid

  • Creating too many subagents. Three focused reviewers are usually easier to manage than eight overlapping roles.
  • Giving every reviewer broad tool access. Review-only agents should usually inspect before they edit or execute.
  • Accepting generic findings. Require file paths, evidence, and a concrete fix or validation step.
  • Skipping reruns. AI review can point to risk, but passing commands provide the evidence.
  • Ignoring project standards. Keep locator rules, assertion standards, test data rules, and done criteria in repository guidance.

Reusable QA Decision Template

End every run with a compact decision template:

## QA Review Decision
Decision: request changes | acceptable after rerun | acceptable

Blockers:
- ...

Recommended fixes:
- ...

Validation completed:
- Command:
- Result:
- Evidence path:

Residual risk:
- ...

This makes the workflow useful for QA engineers, SDETs, automation testers, and AI testing learners because it connects AI-assisted review to real release evidence.

References

FAQ

Can Claude Code subagents replace a QA reviewer?

No. Subagents can split review work into focused passes, but a QA engineer still needs to check the evidence, run the right tests, and make the final decision.

How many QA subagents should a team start with?

Start with two or three: changed-code risk, test evidence, and assertion quality. Add more only when a repeated review need is clearly separate.

Should subagents be allowed to edit tests?

For review workflows, start with read-only or limited tools. If your team allows edits, require a separate validation step and review the diff before accepting it.

What evidence should be captured after a subagent review?

Capture the final decision, commands run, pass or fail result, key logs or screenshots, and any residual risk that still needs human attention.

Conclusion

Claude Code subagents for QA work best when they make review responsibilities clearer. Use them to split code risk, test evidence, and assertion quality into focused passes. Then consolidate the findings, run targeted validation, and keep the final QA decision with the human reviewer.