DevOps Peach

Claude Code in Practice · The .claude toolbox – Skills, agents, hooks and MCP · Lesson 2 of 3

Sub-agents: a second pair of eyes that has not seen the work

The most valuable sub-agent in our project is not a fast parallel worker, it is a reviewer with a clean context. How we use agents to write, review and audit, and when running several at once is worth the tokens.

Practice interactively →

A sub-agent is a separate Claude with its own context window, its own instructions and its own tools. The main session gives it a task; it works; only a short report comes back. Two things follow from that, and both matter more than speed.

1. A clean context is a fresh pair of eyes

The session that wrote a quiz "knows" what each question meant, so it reads its own mistakes as correct. Our tech-reviewer agent starts with nothing but the files and a checklist: is the marked answer really right according to current docs, is any distractor also right, are the accepted commands complete? It found a question with two correct answers that three human readers had missed.

Our rule in CLAUDE.md: graded content (quiz, commands, final tests) must pass tech-reviewer before merge. The writer and the reviewer are never the same context.

2. Noisy work stays out of the main session

Reading 40 files to find where something is used fills the main context with text you will never need again. A sub-agent reads them and returns five lines. The main session stays small and sharp for decisions.

flowchart LR
  M["Main session"] --> W["assessment-writer"]
  W --> F["quiz.yaml, lessons"]
  F --> R["tech-reviewer (clean context)"]
  R --> T["Table of issues"]
  T --> M
  %% step M: The main session only plans and decides.
  %% step W: A writer agent produces the content from the notes.
  %% step R: The reviewer has not seen how the content was written.
  %% step T: Only the findings come back, not the 40 files it read.

When parallel agents are worth it

Running several agents at once is tempting and can burn through a plan fast. We run things in parallel only when:

Writing four module maps that share nothing: parallel. Fixing a bug and then writing the test for it: one session, in order.

Writing an agent file

An agent is a Markdown file in .claude/agents/ with a name, a description that says when to use it, the tools it may use, and its instructions. Give reviewers read-only tools. Ask for a fixed report format. Tell it what it must not do ("never commit", "do not edit files"). That is enough; the shorter the file, the more of the agent's context is left for the task.

Use case: Two AIs, one reviewer

The situation

Writing six AWS modules alone in one Claude session would fill the context many times over. We split the work: Codex writes a module from a task file, a Claude reviewer agent checks it, and the owner decides.

The pieces

Piece File Role
Task tasks/aws-03-compute-ec2.md Inputs, outputs, Definition of done, a ## Codex report section to fill in
Instructions for Codex AGENTS.md The same house rules as CLAUDE.md, for the other tool
First gate tools/check_content.py YAML parses, ids unique, word limits, build steps valid
Reviewer .claude/agents/codex-reviewer.md Reads the task, runs the validator, spot-checks answers against docs

One round, step by step

  1. Codex finishes and fills in its report.
  2. We say: "Codex finished aws-03, review it."
  3. The codex-reviewer agent lists changed files (anything outside the task's output list is a finding), runs the validator (every ERROR is a blocker), reads one lesson in both languages, checks quiz answers and command regexes.
  4. It writes a table into the task file and a verdict.
  5. If changes are needed it creates tasks/aws-03-compute-ec2-fix-1.md with only the fixes, ready to hand back to Codex.

What a finding looked like

file id severity issue fix
quiz.yaml q4 blocker Options B and D are both correct for gp3 Change D to an io2-only feature
commands.yaml c2 major Regex rejects --instance-ids before --query Accept both orders

What we took away

Practice interactively →