Module 6 of 6
Agentic Workflows & Subagents
Claude Code isn't just a chatbot that answers questions — it's an agent that plans, uses tools, checks its own work, and iterates until a job is done. This module covers what makes a workflow "agentic," why you'd delegate parts of a task to a subagent instead of doing everything in one long conversation, and walks through practical scenarios where each approach pays off.
What makes a workflow "agentic"?
In a plain chat, you ask a question and get an answer — the model reasons over the text in front of it and stops. An agentic workflow is different: you give Claude Code a goal, and it repeatedly does something closer to plan → act → observe → adjust, on its own, until the goal is met or it needs your input.
- Plan — Claude breaks a fuzzy goal ("clean up this module's error handling") into concrete steps.
- Act — it uses tools: reading files, searching the codebase, running commands, editing code, calling out to the web or other systems.
- Observe — it looks at the real result of that action (a test failure, a file's actual contents, command output) rather than guessing.
- Adjust — it changes course based on what it just observed, and repeats, asking you for a decision or permission at the points that matter.
This loop is what lets Claude Code handle multi-step, open-ended work — "fix the failing tests," "migrate this module to the new API," "investigate why the build is slow" — instead of only answering one-shot questions. It's also why Claude Code asks for permission before running certain commands or making certain edits: agency means it can take real actions, so you stay the one deciding which actions are allowed.
Rule of thumb: if you could describe the task as a single question with a single right answer, a normal prompt is enough. If the task requires exploring an unfamiliar codebase, running things to see what happens, or course-correcting partway through, you're in agentic-workflow territory — let Claude Code drive the loop instead of trying to hand-hold every step yourself.
What is a subagent?
A subagent is a separate, focused Claude Code instance that the main agent (or you) dispatches to handle one piece of a larger task, then reports back with a result. Think of it like delegating to a specialist: the main conversation stays focused on the overall goal, while the subagent goes off, does deep or noisy work in its own context, and returns a distilled answer.
This matters because of the context window (covered in Core Concepts): every file read, command output, and search result the main agent sees eats into the same limited budget. If the main agent has to personally read fifty files to answer one question, that's fifty files of "noise" sitting in its context for the rest of the conversation. A subagent can do that exploration in its own context and hand back a short summary — the main conversation only pays for the answer, not the search.
Why reach for a subagent
- Keep the main context clean. Large, exploratory searches ("find every place we call this deprecated function") produce a lot of intermediate noise that would otherwise clutter the main thread.
- Parallelize independent work. If a task splits into pieces that don't depend on each other — e.g. reviewing three unrelated modules — subagents can work on them at the same time.
- Specialize. A subagent can be given a narrow role, its own instructions, and even a different model suited to that role (a fast, cheap model for a big grep-and-summarize job; a stronger model for a tricky design decision).
- Get a second, independent opinion. A subagent that didn't write the code can review it with fresh eyes, closer to how a human reviewer would.
The trade-off: dispatching a subagent has overhead (it has to be given enough context to do its job, and its summary is a compression of everything it saw) and adds a bit of latency. For small, quick, self-contained questions, just asking directly is faster and simpler.
Practical scenarios
| Scenario | Agentic approach |
|---|---|
| "Why is this integration test failing?" in a codebase you don't know well | Let Claude Code run the test, read the failure, search for the relevant code, form a hypothesis, and re-run — several loops of plan/act/observe rather than one guess. |
| "Find every place across this large repo that references an old internal API" | Dispatch a subagent to do the broad search and come back with a clean, deduplicated list, instead of flooding the main conversation with raw search output. |
| "Review this pull request for correctness issues and style issues" | Use separate subagents for each concern (or a review-focused subagent with fresh eyes) so the feedback isn't colored by having just written the code. |
| "Refactor this module, update its tests, and update the docs that reference it" | Independent pieces (tests, docs) can be handed to subagents to work on in parallel while the main agent drives the core refactor. |
| "What does this one function do?" | No agentic workflow needed — a direct prompt with the file open is enough. Save the overhead for tasks that actually need exploration or iteration. |
Working well with agentic workflows
- Give a clear goal, not just a first step. "Get the test suite passing" lets Claude Code plan and iterate; "run this one command" gives it nothing to adjust toward.
- Stay in the loop at decision points. Agentic doesn't mean unsupervised — Claude Code will pause for permission before risky or destructive actions. Treat those prompts as real checkpoints, not rubber-stamps.
- Delegate the noisy parts. If a step is going to involve reading many files or running many searches just to produce one fact or summary, that's a good candidate for a subagent rather than doing it inline.
- Review the summary, not just trust it. A subagent's report is a compression of what it saw — for anything high-stakes, spot-check its conclusion the way you would a colleague's handoff.
- Don't over-engineer small tasks. Simple, well-scoped questions don't need a multi-agent pipeline — that's just more coordination overhead for no benefit.
Recap: an agentic workflow is Claude Code planning, acting with tools, observing real results, and adjusting — repeatedly — toward a goal, with you approving the consequential steps. A subagent is a way to delegate a chunk of that work to a separate, focused instance so the main conversation's context stays clean and the work can specialize or run in parallel. Reach for both when a task needs exploration or iteration; skip them for quick, single-answer questions.