transcript
show notes
Builds a read-only Claude Code subagent that checks a diff against a GitHub issue's acceptance criteria, tests it on a good and a deliberately broken change, and weighs it against the evals baseline. Closes with how to invoke it by name so the review reliably happens.
This episode is narrated by AI-generated synthetic voices.
A reviewer that checks a change against its issue
A subagent is a helper the main Claude Code session hands a task to. It has its own context window, system prompt and tool list, and it returns only a summary. Because it starts with almost no knowledge, the main session must pass along what it needs. Custom subagents read CLAUDE.md; the built-in Explore and Plan do not.
The worked example is a new request in the shared-list app: show an item count in the list header (issue thirteen). Its two acceptance criteria are that the header shows the count, and that the count stays correct after add, delete and reload. The reviewer, criteria-reviewer, is a Markdown file in the project's .claude/agents folder. Its frontmatter holds a name, a description, a tools line limited to Read, Grep and Glob, and an optional model. The tools line is enforced by the program, unlike an instruction in the body. Leaving it out gives the subagent every tool the main session has. Since the reviewer has no Bash or MCP tools, the main session fetches the issue and runs git diff, then passes both in the handoff.
The reviewer is tested on a correct change and on a deliberately broken one where the delete handler never updates the count. It should pass the first and fail the second. Its report is a lead, not proof: it read code and did not run the app, so the type check, regression tests and a manual click-through still apply.
Whether the reviewer earns its place
The decision comes from the evals baseline: the fast-add bug and the done-flag feature, each run twice with the reviewer line in CLAUDE.md and twice without. Four runs per task is a small sample, so one caught mistake is a hint. The suggested outcome is to keep the reviewer for issue-linked changes, especially database ones.
Three failure modes are covered: a vague description, a handoff with a diff but no criteria (reports that all say "looks good"), and splitting one task across many helpers that share state.
Calling the reviewer by name
To make the review happen for certain, name the subagent in the request or pick it with the at sign. A reusable request reads the issue, runs git diff against main, sends the criteria word for word plus the diff to criteria-reviewer, and lists each verdict with evidence before changing anything. Run it on the broken count change and check with slash context that the main session's context barely grew.
