Claude Code Agents and Subagents Explained

Most people treat Claude Code like a chatbot that writes code. That's dramatically underselling it. Claude Code is an agent. It reads your codebase, makes decisions, executes commands, and iterates on its own work. It can also spawn additional agents to work in parallel. Once you understand that, you use it completely differently.

I've taught over 100 people to use Claude Code. The single biggest shift is when they stop treating it like a chat interface and start treating it like a team of developers they're managing. That mental model shift (from "tool I type prompts into" to "autonomous worker I direct") is what separates people who build toy projects from people who ship real products.

Claude Code Is Already an Agent

Before we get into subagents, let's be clear about what Claude Code already does on its own. When you give it a task, it doesn't just generate a response. It:

• Reads files across your entire project to understand context
• Decides which files need to be created or modified
• Writes code across multiple files
• Runs shell commands (installing packages, running tests, starting servers)
• Checks its own work by running the code
• Fixes errors it encounters and tries again
• Iterates until the task is complete

That's fundamentally different from ChatGPT or Copilot. Those tools generate text and hand it to you. Claude Code takes action. It's the difference between a consultant who writes a report and a contractor who builds the house. You don't copy-paste Claude Code's output. It directly modifies your project.

What Subagents Are

Here's where it gets interesting. Claude Code can spawn subagents: parallel instances of itself that work on independent tasks simultaneously. Think of it as a lead developer who delegates subtasks to junior devs, coordinates their work, and assembles the results.

When Claude hits a complex task that has naturally independent parts, it can spin up subagents to handle each one. Each subagent gets its own context, reads the files it needs, and works independently. The main Claude instance coordinates everything and combines the results.

You don't need to explicitly ask for subagents. Claude decides when to use them based on the task. But knowing they exist helps you structure your prompts to take advantage of them.

When Claude Uses Subagents

Claude is most likely to spawn subagents for tasks that have clear parallel components:

Large codebase exploration

When you ask something like "find every place in this codebase where we handle user authentication," Claude might spawn multiple subagents to search different directories simultaneously. Instead of reading files one by one, it parallelizes the search. On large projects, the speed difference is dramatic.

Multi-file refactors

Renaming a concept across your codebase, changing an API's response format, or migrating from one library to another. These tasks touch many files but the changes to each file are independent. Subagents can handle different files at the same time.

Research and analysis

When Claude needs to understand a complex system (say, tracing how data flows from your API through your frontend), it might spawn subagents to analyze the backend and frontend code in parallel, then pull the findings together.

Full-stack feature building

The most impressive use case. When building a feature that spans frontend and backend, Claude can spawn subagents to work on the database schema, API endpoints, and UI components simultaneously. Each subagent understands the interface contract and builds to it.

How to Prompt for Agentic Behavior

You can't force Claude to spawn subagents. But you can structure your prompts to make agentic behavior more likely and more effective:

Give complex, multi-part tasks

Instead of breaking a feature into tiny steps and feeding them one at a time, give Claude the whole picture. "Build a user settings page with profile editing, password change, notification preferences, and account deletion, including the API endpoints and database migrations." Claude is more likely to parallelize when it can see all the independent pieces upfront.

Be clear about the scope

"Refactor the entire authentication system to use JWT tokens instead of session cookies. Update the login flow, the middleware, the protected routes, and the tests." This gives Claude a clear picture of all the surfaces that need to change and lets it plan the work distribution.

Describe the end state, not the steps

"I want a dashboard that shows real-time sales data, with filters by date range and product category, a chart showing trends, and a table with the raw data. It should use our existing Supabase database." This lets Claude decide the best approach and parallelize as it sees fit. If you dictate every step, you prevent it from working autonomously.

Real Example: Full-Stack App in One Session

One of my favorite student stories. A product manager in my class wanted to build an internal tool for tracking customer feature requests. She gave Claude Code this prompt:

Build a feature request tracker. Users should be able to submit feature requests with a title and description. There should be an admin view where I can see all requests, sort by votes, and mark them as planned, in progress, or completed. Users can upvote requests. Use Next.js, Supabase for the database, and make it look clean with Tailwind.

Claude Code spent about 12 minutes working through this. It set up the Next.js project, created the Supabase tables, built the API routes, created the submission form, the public board view, and the admin panel. It ran the dev server, tested navigation, and fixed 2 styling issues it noticed.

The result was a fully functional app. Not a prototype. A working application with database persistence, real-time vote counts, and role-based views. She deployed it to Vercel that afternoon and her team was using it the next day.

Without the agentic architecture (Claude's ability to work across the full stack autonomously, hold the entire project in context, iterate on its own work), this would've been a multi-day engineering task. With Claude Code, it was a lunch break.

The Agent Tool

Under the hood, Claude Code has an internal capability called the Agent tool. This is how it spawns subagents. When Claude determines a task would benefit from parallel work, it creates subtasks and dispatches them as separate agent instances.

Each subagent can:

• Read files in your project
• Search for patterns across the codebase
• Analyze code and return findings
• Make targeted edits to specific files

The main agent coordinates them, waits for results, resolves any conflicts, and continues with the overall task. You'll sometimes see Claude mention that it's "dispatching a subtask" or "delegating research." That's the Agent tool at work.

Claude Code Teams: Persistent Multi-Agent Workflows

Anthropic has been building out collaborative features that let multiple Claude Code instances work together more formally. The idea: you define roles (one instance focused on frontend, another on backend, another on testing) and have them collaborate on a shared codebase.

This is still evolving. But the trajectory is clear: we're moving from "one human talking to one AI" to "one human orchestrating a team of AI agents." If you get comfortable with the single-agent Claude Code today, you'll be well-positioned when the multi-agent workflows mature.

Why Agentic Coding Is the Future

Here's my contrarian take: in 2 years, writing code manually will feel like hand-washing clothes. Not because it doesn't work. Obviously it does. But having an autonomous agent that can read your codebase, plan changes, execute them across multiple files, run tests, and fix issues is so dramatically more productive that doing it by hand will seem quaint.

The people who understand this now, who learn to direct agents rather than write code, will have an enormous advantage. Not just in speed, but in the scope of what they can build. A single person directing Claude Code can produce what used to require a team of 3-4 engineers. That's not a marginal improvement. That's a fundamental change in what's possible for individuals and small teams.

The skill that matters isn't coding. It's clear thinking, system design, and knowing what to build. Claude Code handles the how. You handle the what and the why. That's the job description of the future. And learning to work with agents, starting with Claude Code, is how you get there.

Want to learn more? Read about what Claude Code is, how to connect it to external tools with MCP servers, or how to use plan mode to keep Claude pointed in the right direction.