How to brief a subagent for review and check its report

Ask someone to "check the page" and you leave the reviewer plenty to decide: hunt for broken behavior, judge the styling, or suggest a different way to write the code. What comes back can be a tidy list of findings that barely helps with your actual task. Let's look at how to hand a Claude Code subagent a brief it can act on, and then check whether it did what you asked.

If you haven't set up the reviewer role yet, start by creating the role and running it once. Here we focus on the brief itself and on how complete the answer is.

1. What to hand the reviewer

A reviewer checks someone else's work and comes back with findings and the evidence behind them. In our examples that's a custom subagent named reviewer that can only read and search files: Read, Grep, Glob. It studies the code but doesn't fix it, and it doesn't open the page in a browser. Calling it reviewer doesn't create such a role by itself; we assume it's already set up in your project.

On a normal fresh run, a subagent like this doesn't automatically receive the whole history of your conversation. The main agent you talk to writes it a separate assignment. So an important requirement, e.g. "two items with the same name count as separate entries", has to land in the brief, or in a document the reviewer is told to read. How this works is described in the documentation on subagent context; we're talking about launching a custom role here, not about a fork that carries a copy of the conversation.

Compare "take a look at the project" with "check entry deletion and the counter update; do not change the code". The second one already says where to look and what you're not expecting it to do. All that's left is to spell out what counts as a correct result.

For a short one-off check, a message is enough. When there are many criteria, or the check will be repeated after fixes, it's easier to save a brief: a short description of the task that lives alongside the project. Not a ten-page specification. Just the few conditions the reviewer would otherwise have to guess.

You won't anticipate every question, and you don't have to. When the input is missing something, the reviewer should flag the gap in its report. The main agent can then come back to you about it. A good brief cuts down on misreadings, but it doesn't guarantee a good answer: the model can get things wrong even with a clear task.

2. Four parts of a brief

The goal says which behavior needs checking. For a shopping list page that's adding, deleting and the entry counter. "Make the project better" is too broad; there's no way to tell which improvement matters right now.

The input names the files and the expected behavior. A path to app.js on its own isn't enough if the code doesn't say whether duplicate names are allowed. That's a product decision, and you have to state it. Also say what the reviewer can use to check: in our case that's reading the code and nothing else. No browser.

The boundaries separate this check from the tasks around it. Styling, the mobile layout and keeping the list between sessions are out of scope right now, for instance. Files stay unchanged. If a file is missing, the part of the check that depends on it stops and the reviewer says so, instead of inventing what was in it.

The result describes what you want back: the scope actually checked, findings with evidence, and the limits. Don't demand that it find five bugs. The Claude Code guidance on review calls out the risk in that kind of framing: an instruction to look for flaws pushes toward findings even where the work is correct.

Each branch adds something the others don't: a file path won't tell you the expected behavior, and a goal leaves the ban on edits unsaid. Put these conditions together so the reviewer can weigh them against the code.

So instead of "check the shopping list page" we hand over the brief below. You can send it as a message or save it to REVIEW_BRIEF.md in the project root:

# Shopping list review
Goal: check adding, deleting and the counter by reading the code.
Input: index.html and app.js in the project root.
Expected: an added item shows up in the list;
the counter equals the number of items; deleting one entry
does not delete another entry with the same name.
Boundaries: do not change files; styling, the mobile layout
and keeping the list between sessions are out of scope.
If a file or a requirement is missing, name the gap,
do not invent it, and return the result for the part you can cover.
Result: follow the reviewer format; say what was checked
and what was left unchecked. No findings is an acceptable outcome.

We get to the reviewer format right below. If your role has no permanent format yet, you can fold it into the same one-off message. The field names aren't mandatory; what matters is the information they keep you from forgetting.

Asking for "the three most significant findings first" limits the size of the answer, not the depth of the check. If you need a limit like that, ask separately whether there are other findings. The agent must not stop after the third one and call the task checked.

3. What to keep in files

The conditions of one task keep changing: today it's the counter, tomorrow it's saving the list. Those live in the brief. But asking it to show where the bug is and what the evidence is comes up in nearly every review. That one is easier to write down once, in the role instructions.

Here, an output contract simply means an agreed format for the answer. These are ordinary instructions for the reviewer, not a special Claude Code setting and not an automatic quality check. The format helps you find what you need in the report; it doesn't make any of it true.

The two branches at the top do different jobs. The brief sets the content of the check, while the role instructions set, among other things, the shape of the report. For the reviewer to use a saved brief, tell it to read the file. At the bottom you get a report whose evidence and completeness you still have to judge.

Here's a section you can add to the body of an existing role file .claude/agents/reviewer.md, below its frontmatter:

## Result format
List the files and criteria you checked.
For every finding: the place, the expected behavior, the evidence,
the conditions of the check and the impact; explain the priority.
Separate what the code confirms from unverified assumptions.
Name the limits and the missing data separately.
If you found no problems against the criteria, say exactly that.

This is a fragment of the instructions, not the whole subagent file. Our role only reads and searches, so it has no use for a permanent "files changed" field. In a broader report the information about changes has to match the facts: you can't hardcode the line "files changed: none" regardless of what actually happened.

Once the brief is saved, the request to the main agent can be this short:

Have reviewer read REVIEW_BRIEF.md in the project root
and check the files it names against its criteria.
Return the full report as it comes back.

We explicitly told it to read the document, rather than just naming the file. The file itself guarantees nothing, though: the reviewer can still skip a condition. What a saved brief buys you is something to compare the result against, and the option to run the same check again. When the requirements change, update the document first, or the next pass will be judging the old task.

4. How to check the report

Start by looking at what was actually checked. The brief listed adding, deleting, the counter and entries with the same name staying independent. A report that only talks about the counter isn't a result for the whole task. Even when its one finding is completely right.

It helps to line up every criterion from the brief against the answer. In our sample partial report it came out like this:

A missing line about identical names doesn't mean there are no bugs there. And one well-supported finding about the counter doesn't cover the part of the assignment that got skipped. Send the report back with a specific follow-up:

The brief covers deleting one of two entries with the same name.
The report does not address that criterion. Check it with the tools you have
and give the evidence for the result, or the reason you could not check it.
No need to repeat the other conclusions unchanged. Do not change the code.

Judge the credibility of the significant findings separately: put the place each one names, the requirement and the evidence side by side. There's a detailed example in the article on reading a review report. You need both checks here: coverage of the brief and soundness of the result. A suggested test scenario isn't the same thing as a test that was run.

At the first fork you decide whether enough was checked for your task. If not, you ask for what's missing, or accept only the part that was checked, judging its evidence too. At the second fork you tell sound conclusions from questionable and wrong ones. Unclear evidence is worth asking about; you can reject a finding proven wrong, or advice that is off-task.

A report with no findings can pass this check too. For example: "Checked the add and delete paths, the independence of identical entries and the counter update in index.html and app.js. Found no problems against those criteria; did not run it in a browser". A result like that doesn't promise the project is free of bugs. It reports an outcome within the limits it names, and if you need more, you verify the key paths yourself.

But "could not find app.js at the given path, so I could not check the delete behavior" is a different animal: it means missing input, not absence of bugs. Here you pass the correct path and let the check continue. A short honest answer is worth more than a long report with the gap buried inside it.

Accepting a report doesn't mean ordering a fix for everything in it. You're agreeing that the result of the check is sound; which changes to make right now is a separate decision.

5. When you need another pass

When a report is missing the evidence, you don't have to start the review over. Send back the specific gap, and only that. Say the shortened version of the counter finding only names the bug, with no walk-through of the calls. Then the request to the main agent can look like this:

Send the report back to reviewer for clarification: the counter finding
does not name the path where the counter gets updated after a deletion.
Have it check that path and add the evidence for the conclusion.
Do not change the code.

If it turns out the update already happens in another function, the finding has to be dropped. Not swapped for a different one just to keep the number of findings up. If the bug is confirmed, you can hand the fix to the main agent in a separate request, naming the specific finding and how much it's allowed to change.

After the fix, another pass over the same brief is worth the time:

Have reviewer read REVIEW_BRIEF.md again and check
the current deletion and counter code. The earlier finding:
after a deletion the counter was not updated.
Have it say whether the problem is gone and what the conclusion rests on,
and also check that entries with the same name
are still independent. Do not change the code.

Now you're after an answer to one specific question: is the problem closed, and did the fix break the behavior around it. To confirm how the page behaves, run the same scenario in the browser yourself. If the repeat review was code-only, that limit carries over into the new report.

The report may come back shorter, longer, or with no new findings. That's not how you measure success. What matters is that the old defect is gone, the conclusion rests on the current code, and the unchecked parts are still visible. Decided to postpone the fix? Then keep the confirmed finding and the reason for the delay; re-running a review over unchanged code just to get a different answer buys you nothing.

6. From a brief to a checked result

When you work with Claude Code, a brief keeps your expectations intact while the main agent hands the task to the reviewer. A permanent format makes the answer easier to read. But you still have a part to play:

• the main agent writes the brief and passes it to a suitable role; you set the expected behavior and the boundaries;
• the reviewer studies the files and returns the evidence for its conclusions; checking the coverage and the significant findings is on you;
• the main agent can clarify the report or fix a confirmed bug in a separate request; you decide what to change and how the result gets confirmed.

For the shopping list the outcome isn't just the advice "add a call to this function", but a checked explanation: which action left the number stale, where the update broke, and what changed after the fix. That's a result you can work with.