Lesson 4.320 min · 5 cards · 8 exercises · 1 mission

Three patterns: reviewer, tester, debugger

Three roles every team needs: a reviewer with a memory, a tester on a cheap model, a debugger that fixes in its own worktree, and how to chain them.

Lesson 4.2 gave you a subagent that writes tests. This lesson builds the three roles every team needs: a reviewer that reads changes and remembers the team's conventions, a tester that runs the tests and reports only what broke, and a debugger that fixes bugs on a separate copy so it never touches the code you're working on. Each role uses a different setting, and each setting has a trap we ran into when we tried it for real.

Three roles, three settings

Role Tools What sets it apart
reviewer Read, Grep, Glob, Bash memory: project: remembers team conventions across sessions
tester Read, Grep, Glob, Bash model: haiku: cheap, fast, reports only failing tests
debugger Read, Edit, Bash, Grep, Glob isolation: worktree: fixes on its own copy of the repo

The common rule: each role gets exactly what it needs. The reviewer doesn't need to edit files, so it has no Edit or Write. The tester only runs commands and reads results. Only the debugger may change code, and it does so somewhere else.

All three files go in todo-api's .claude/agents/ and get committed so the whole team shares them.

Reviewer: read-only, with a memory

Markdown
---
name: reviewer
description: Reviews the current branch against main for todo-api. Use when the user asks for a code review or before opening a pull request.
tools: Read, Grep, Glob, Bash
model: inherit
memory: project
---
You review todo-api changes. Never change project files; the only files you may write are in your memory directory.

1. Check your memory for the team's preferences and past findings
2. Run git diff main...HEAD and read the changed files in full
3. Report by priority: must fix, should fix, consider. Give file:line and a suggested fix for each
4. Save new team preferences or recurring problems to your memory, one short line each

model: inherit means the main conversation's model, since reviewing needs good reasoning.

The memory field gives a subagent a long-lived memory folder. With project, the folder is .claude/agent-memory/reviewer/, which you can commit so the whole team benefits. The other scopes are user (~/.claude/agent-memory/, for every project) and local (.claude/agent-memory-local/, not committed). The docs recommend project. On every run, the subagent reads the start of the MEMORY.md file in that folder.

When we tried it, we told the reviewer: "our team prefers early returns and never logs from route handlers". It flagged the console.log in a route as must-fix, then created MEMORY.md plus a file recording those two conventions. The next review starts from what it already knows.

The trap: turning on memory makes Claude Code grant Read, Write and Edit automatically so the subagent can write its memory files, even when tools has no Write. Our reviewer did use Write to save its memory. Technically it is no longer read-only, so the prompt must say clearly that it may only write in its memory folder. If you need a hard block, use a hook (level 6).

Bash is another open door: the reviewer needs git diff, but Bash can run any command. Block dangerous commands with deny rules in your settings, as in lesson 4.2.

Tester: cheap, short, failures only

Markdown
---
name: tester
description: Runs the todo-api test suite and reports only what failed. Use after code changes or when asked whether the tests pass.
tools: Read, Grep, Glob, Bash
model: haiku
---
Run npm test. Do not edit any file.

If everything passes, reply with one line: the number of tests that passed.
If anything fails, reply with, for each failing test: its name, the assertion that failed (expected vs actual) and the file:line of the test. Nothing else.

This is lesson 4.1's "isolate high-volume output" pattern, packaged as a file. Running tests needs no deep reasoning, so model: haiku is enough, and faster and cheaper. In our run the tester did run on Haiku 5.5 and called npm test just once.

The most valuable part is the report format. "Nothing else" keeps the main conversation down to a few lines even when the suite prints hundreds. The tester differs from lesson 4.2's test-writer: one runs tests, the other writes them. Keeping them apart keeps each role's job clear.

Debugger: fixes on its own copy

Markdown
---
name: debugger
description: Finds the root cause of a bug or failing test in todo-api and fixes it. Use when a test fails or the API behaves unexpectedly.
tools: Read, Edit, Bash, Grep, Glob
isolation: worktree
---
You fix bugs in todo-api.

1. Reproduce the problem with a failing test in test/todos.test.js
2. Find the root cause; explain it in two or three sentences with file:line
3. Make the smallest fix in src/ that makes the test pass
4. Run npm test; every test must pass
5. Commit the test and the fix on your current branch, then report the cause, the fix and the branch name

isolation: worktree gives the debugger a git worktree (a second checkout of the same repo, under .claude/worktrees/). It makes its changes there, and the folder you're working in stays untouched. If it changes nothing, the worktree is removed automatically.

Three things we learned from real runs:

  • The worktree starts from the remote's default branch (usually origin/main), not from where you are. On our first try, the debugger couldn't see our unpushed local commit. To start from your current HEAD, set "worktree": {"baseRef": "head"} in your settings. Uncommitted changes still don't come along.
  • The delegation message beats the agent file. We only said "fix this bug". Claude wrote a delegation message that said "Do NOT commit or push", because you never mentioned committing, and the debugger followed that instead of step 5. Add to your request: "let it commit the fix on its own branch". Next time it committed and reported the branch name.
  • Bring the result back with git. The debugger reports a branch name such as fix/double-delete-404. In your main folder, run git merge fix/double-delete-404, check npm test, then git worktree remove to clean up. Add .claude/worktrees/ to .gitignore.

A worktree is a fresh checkout, so ignored files such as .env aren't there. List the files to copy across in a .worktreeinclude file at the repo root, using .gitignore syntax.

Chaining the roles

The three roles are strongest in sequence. One message is enough:

First use the tester agent to check whether the tests pass.
Then use the debugger agent to fix what fails, and let it commit
the fix on its own branch.

Claude calls the tester first, passes its result to the debugger, then sums up for you. Finish by calling the reviewer on the debugger's branch before you merge.

Two more things worth knowing:

  • Each call creates a new subagent. To have one carry on with everything it already knows, ask Claude to continue: "Continue that review and now check the tests too". Claude resumes that same subagent with its full history.
  • To ban a role for a while, add Agent(debugger) to permissions.deny in your settings. This works for built-in subagents too, as in Agent(Explore).

The trio for todo-api

The lesson's mission puts all three roles to work on todo-api:

  1. Create the three files in .claude/agents/ as above.
  2. Plant a bug on purpose: in POST /todos, change status(201) to status(200) and commit. Add a console.log line to a route.
  3. Call the reviewer with the convention "never log from route handlers". Open .claude/agent-memory/reviewer/ to see what it saved.
  4. Call the tester and then the debugger with the chained message above. Merge the branch the debugger reports and run npm test again.

Once you're used to it, splitting roles feels like splitting work in a real team: everyone has a clear job, exactly the access they need, and a short report at the end. The next level leaves the repo behind: connecting Claude Code to outside tools through MCP.

Practice lesson 4.3

5 flashcards, 8 exercises checked right on the page, 1 mission on your machine.

Start practice

Related reference

Type to search the reference, templates and lessons.