Claude Code ships with three built-in sub-agents and routes to them automatically. Each runs in its own context window and returns only a summary, so your main session does not fill up with file dumps and test output. On a multi-module Spring Boot app, that is the difference between a session that stays sharp and one that goes vague after twenty minutes.
Here is what each does and exactly when it helps.
The three agents at a glance
| Agent | What it does | Read or write | Model | You invoke it by |
|---|---|---|---|---|
| Explore | Searches and understands the codebase: finds files, traces callers, locates definitions | Read-only | Fast, cheap (Haiku by default) | A read prompt (“find…”, “trace…”, “where is…”) |
| Plan | Researches the codebase, then hands you a plan to approve before any edits | Read-only | Inherits the session model | A “plan …” prompt or plan mode |
| General-purpose | Handles tasks that need both exploration and modification in one unit | Read and write | Inherits the session model | A build prompt (“add…”, “change…”, “implement…”) |
All three are routed automatically. The verb in your prompt decides which one runs.
Which agent handles which layer
A request rarely lives in one layer. Here is how the work splits across a typical Spring Boot request path, what you actually type, and why each agent fits.
| Layer | What you prompt | Agent | Why that agent |
|---|---|---|---|
@RestController endpoint |
“Map all callers and DTOs for OrderController” then “Add a GET /orders/{id} endpoint with DTO and test” |
Explore, then General-purpose | Explore reads the call graph cheaply; General-purpose both reads and writes the new code |
| Service facade | “Trace what OrderService orchestrates” then “Add a cancelOrder method to the facade” |
Explore, then General-purpose | The orchestration spans many beans, so Explore reads them cheaply; the build needs read plus write |
| Business object | “Find where the discount rule lives” then “Change it to cap at 30%” | Explore, then General-purpose | Explore locates the rule without bloating context; General-purpose edits it |
| DAO / repository | “Show every query and @Transactional use in OrderRepository” then “Add findByStatusAndRegion“ |
Explore, then General-purpose | Read-heavy scan suits Explore; adding a query needs read plus write |
| Kafka consumer / producer | “Find every consumer of order-events” then “Add a @KafkaListener for order-cancelled“ |
Explore, then General-purpose | Topic usage is spread across files (Explore); wiring a listener is a build task |
| Dependent stream / external API | “Where do we call the payment client?” then “Add a 2s timeout and fallback” | Explore, then General-purpose | Explore finds the call sites; General-purpose implements the handling |
| Spring Batch job | “Trace the reader, processor, writer in ReconJob” then “Add a job for nightly reconciliation” |
Explore, then General-purpose | Step graph is read-only discovery; new job config is read plus write |
@Transactional / @Service / @Component wiring |
“Plan moving the transaction boundary up to the facade” then approve before edits | Plan first, then build | A boundary move is expensive to get wrong, so research and approve on paper first |
| Boot 2 to 3 migration | “Plan the Jakarta namespace and config migration” then approve | Plan first, then build | Touches many files irreversibly; Plan lets you catch a bad approach before edits |
| OpenTelemetry metrics and traces | “Find existing spans in the order flow” then “Add a span around the payment call” | Explore, then General-purpose | Explore surveys existing instrumentation; General-purpose adds the new span |
The pattern: for most layers, prompt twice. First a read prompt (Claude routes to Explore, which is read-only and runs on a cheap, fast model, so the file volume never hits your main context or costs Opus tokens). Then a build prompt (routes to General-purpose, which both reads the surrounding code and writes to it as one connected unit). For anything that moves a boundary or migrates versions, open with “plan …” so Plan researches first and you approve before code changes. You never name the agent; the verb in your prompt does the routing.
Explore (read-only, fast model)
Searches and understands the codebase without changing it. Use it for the read-heavy questions that would otherwise pull thirty files into your main thread:
- Trace a
@Transactionalboundary across the service layer. - Find every consumer of a Kafka topic or every caller of a shared
@Servicebean. - Map which
@RestControllerclasses depend on a given DTO before you change it. - Locate where a bean is actually wired when there are three
@Configurationcandidates.
It picks a thoroughness level itself: quick lookup, medium, or very thorough sweep.
Plan (research before edits)
Explores the relevant files, then hands you a concrete plan before any code changes. Reach for it on the changes that are risky to improvise:
- Refactoring the authentication or authorization layer.
- Splitting a service out of a monolith.
- A Spring Boot 2 to 3 migration (Jakarta namespace, config property renames).
- Swapping a persistence layer or introducing a new one.
You read and approve the plan first, grounded in your actual package structure rather than a generic recipe.
General-purpose (explore and modify)
The workhorse for self-contained implementation tasks that need both reading and writing:
- Add a REST endpoint with its DTO, service method, and test.
- Wire a new repository method and the JPQL or derived query behind it.
- Add a validation rule across a request object and its controller.
The one detail that bites Spring developers
Explore and Plan skip your CLAUDE.md by design, to stay fast. General-purpose and any custom agents load it. So if your team conventions live in CLAUDE.md (logging pattern, @RestControllerAdvice structure, test naming), Explore and Plan will not follow them, the implementation agents will.
Also: sub-agents cannot spawn sub-agents. The hierarchy stays one level deep.
How to work with it on a Spring Boot codebase
- Let Explore map the service layer first. Before “add caching to
ProductService“, ask it to trace every caller and the@Transactionalboundaries. The thirty files it reads stay in its context, not yours. - Make Plan do the migration homework. For a Boot 2 to 3 jump or a security refactor, get the plan before edits. It reads your actual
pom.xml,application.yml, and package layout instead of guessing. - Keep team conventions where the implementer sees them. Explore and Plan skip
CLAUDE.md. So put your logging pattern,@RestControllerAdvicestructure, and test naming there for General-purpose, but expect to restate them when you ask Explore to investigate. - Watch the integration suite. A Testcontainers or
@SpringBootTestrun dumps a wall of output. Let a sub-agent run it and report only the failing tests, so your main thread keeps the decisions, not the stack traces.
Next post: writing your own custom sub-agents, a read-only reviewer locked to your team’s standards and a test-runner that knows your suite.
How to see what your agents are doing
You do not trigger the default agents. Claude routes to them automatically based on the task. You can still see and control them:
- Watch it run: when Claude delegates, the terminal shows the Task or Explore tool firing. Run
/agentsand the Running tab lists live and finished sub-agents so you can open or stop them. - Force a specific one: name it in the prompt,
@agent-<name>it, or run the whole session as one withclaude --agent <name>. - Caveat: sub-agents have no live “thinking” output. You see that one is running and get its summary back, not a play-by-play.
The usage report (tokens, cost, which agents ran)
Built into Claude Code, no extra tooling:
/usage— on Pro, Max, Team, or Enterprise, attributes recent usage to sub-agents, skills, and MCP servers as a percentage of the total. Pressdorwfor last 24 hours or 7 days. Figures are approximate and local to this machine only. Needs v2.1.174+./cost— current session’s token usage, estimated cost, duration, and lines changed.
This matters for cost. Three sub-agents on one task is roughly four times the spend of a single-thread session, and Claude can over-delegate. If /usage shows sub-agents eating 80% of a session that produced one PR, that is your signal to scope tighter. For history beyond the built-in 24h/7d window, npx ccusage reads the local logs (kept 30 days by default).