Project 14 — Subagent for Research

Enforces: subagent definition (name/description/tools/model), context isolation, briefing, and parallelism (from introduction-to-subagents) Surface: Claude Code (terminal) · Time: ~60 min · Difficulty: 🟡 intermediate

Why this project

A subagent runs in its own context window, with its own tool whitelist and system prompt, and returns a single summary to the parent. That isolation is the point: noisy work (file scans, research) stays out of your main thread, you can run several at once, and you can put a cheap model on cheap work. But the subagent starts with zero context from your conversation — so the brief is everything. This project makes you feel both the power and that constraint.

What you'll build

A custom Explore/research subagent defined in .claude/agents/, a delegated task you watch run in isolation, and a parallel run of two subagents researching different things at once — with a clear read on what context did and didn't cross the boundary.

Steps

Define the subagent — Create .claude/agents/researcher.md. Frontmatter sets identity, when-to-invoke, allowed tools, and model:

---
name: researcher
description: >
  Read-only research agent. Use to investigate a focused question across the
  codebase or docs and return a sourced summary. Does not edit files.
tools: Read, Grep, Glob, WebSearch, WebFetch
model: claude-haiku-4-5-20251001
---

You are a precise research agent. Given a single focused question:
1. Gather evidence using your read-only tools.
2. Return a tight summary with file:line or URL citations for every claim.
3. Do not speculate beyond what you found; say what's missing.

Note the cost move: read-only tools + a Haiku model for cheap fan-out work.

Delegate one task — Ask the main agent to use the researcher: "Use the researcher subagent to find every place we read environment variables and how they're validated." Watch it spawn with a prompt, run independently, and return only its final summary.
Observe context isolation — Tell the main session a fact (e.g., "We're standardizing on pydantic-settings.") after the subagent started, then inspect the subagent's brief. Confirm it never saw that — its context is whatever the parent put in the prompt, nothing more. This is the lesson: "based on the above" doesn't work across the boundary.
Write a self-contained brief — Re-delegate, this time packing everything the subagent needs (paths, the constraint, the output format) into the prompt. Compare the quality of the result against the under-briefed run.
Run two in parallel — Kick off two researcher subagents at once on independent questions (e.g., "how config is loaded" and "how logging is configured"). Confirm they run concurrently and each returns its own summary, isolated from the other.
Commit — Add .claude/agents/researcher.md so the team has the role.

Acceptance criteria — you're done when

A subagent is defined in .claude/agents/ with name, description, a tools whitelist, and a model.
You delegated a real task and saw only the subagent's final summary return to the parent.
You demonstrated context isolation: a fact known to the parent was not available to the subagent.
A well-briefed delegation visibly outperformed an under-briefed one.
You ran two subagents in parallel on independent questions and got two isolated summaries.
You journaled the briefing detail that most changed the result in learning-journal-template.

Stretch goals

Add isolation: worktree and have a write-capable subagent edit files without touching your working tree.
Give the subagent a tighter tool whitelist and watch it refuse out-of-scope actions.
Add a second subagent type (e.g., verifier) with a different model and system prompt.

Self-assessment rubric

Level	Signal
🟢 Got it	You delegate scoped work with self-contained briefs by instinct and reach for parallel subagents when work is independent.
🟡 Almost	Subagents work, but your briefs still lean on "the above," so results are uneven.
🔴 Revisit	You over-delegate trivial tasks or expect the subagent to share your context. Re-watch introduction-to-subagents and re-read subagents.