How Claude Code Agents Work: Explore, Plan, and Build

Summarize with:

ChatGPT

Grok

Perplexity

Claude

Quick answer: Claude Code agents are autonomous workers built into Anthropic’s terminal-based coding tool. Instead of a back-and-forth chat, you give Claude Code an objective, and it reads your repository, writes a plan, edits files, runs tests, and reports back. The three built-in sub-agent types are Explore (read-only research), Plan (strategy without edits), and General-purpose (full read, write, and execute access).

If you asked me what actually separates Claude Code from ChatGPT or GitHub Copilot, I would not start with the underlying model.

I would start with the workflow, because that is where the real difference lives.

Open a terminal inside a Git repository and type one prompt:

Add request validation to every FastAPI endpoint, write tests for
the new validation logic, update the documentation, and commit
everything using a descriptive Git commit message.

That is the whole ask, no back-and-forth required.

A standard chat assistant would probably ask you five follow-up questions before touching a single line of code.

Claude Code just starts working.

It searches the project to map out the API structure, finds every endpoint, edits the right files, writes tests, fixes whatever breaks, updates the docs, and creates a commit that actually explains what changed.

From where you are sitting, it stops feeling like a chat and starts feeling like handing a ticket to a teammate who does not need hand-holding.

That shift from answering to actually finishing the job is the whole reason Claude Code agents are worth learning properly.

The feature making that possible is the sub-agent system.

Instead of forcing one long session to reason about your entire codebase at once, Claude Code can spin up specialized workers that investigate a subsystem, sketch an implementation plan, or edit code on their own, then report back to the main session.

The three main agent types are:

• Explore, which investigates your project without touching anything
• Plan, which designs an implementation strategy before any code changes
• General-purpose, which edits files, runs commands, and gets the actual work done

This changed how I plan my own work sessions.

I stopped asking “can the model write this function” and started asking “what is the biggest chunk of work I can safely hand off.” That is a different question, and it leads to a very different way of using the tool.

By the time you finish this guide, you will know when to reach for each sub-agent type, how to set up persistent project memory with CLAUDE.md, and how to string agents together into workflows that save real time without taking your hands off the wheel.

What You Need Before You Start Working With Claude Code Agents

This guide assumes you are comfortable in a terminal and can move between directories with basic commands like cd, ls, or dir.

You do not need to be a Bash wizard, but you should not be scared of a blinking cursor on a black screen either.

Here is what to have ready:

• Node.js 18 or later installed on your machine
• A Claude Pro, Max, Team, or Enterprise subscription, or an Anthropic API key if you plan to automate Claude Code without a browser
• A Git repository to practice on
• Basic familiarity with Python, JavaScript, or another programming language

If you have never touched Claude Code before, my earlier post, getting started with Claude Code, covers the basics before you get into sub-agents.

What Are Claude Code Agents, Exactly?

Claude Code agents are autonomous workers that complete multi-step development tasks using your local repository, terminal, and development tools.

Unlike a browser-based chat, Claude Code can open files, run Bash commands, edit source code, and check its own work before handing you a finished result.

Most AI coding assistants still work like a conversation.

You ask, you get an answer, you decide what to do with it.

That is fine for a single SQL query or a quick explanation of a scikit-learn pipeline, but it falls apart once a task touches twenty files, needs several terminal commands, or depends on understanding a repository nobody explained to you.

Claude Code handles that differently because it works inside your Git repository directly.

It investigates before deciding anything, instead of waiting for you to paste files into a chat window.

Suppose you ask:

Replace every custom customer ID validator with Pydantic models,
update the FastAPI endpoints, rewrite the affected pytest tests,
and summarize the migration.

A typical chatbot answers that with example code and a request for more context.

Claude Code searches the repository, finds the existing validation logic, edits the relevant files, runs the test suite, fixes whatever regressions it introduces, and reports back on what actually changed.

That is the difference between answering a question and finishing a job.

How Does the Agent Loop Actually Work?

Every Claude Code agent runs the same basic cycle: read information, decide what to do next, act, then check the result before repeating.

The loop itself is simple.

What makes it useful is that Claude Code can run it dozens of times in a row, recovering from a bad attempt instead of giving up after the first failure.

Say you ask Claude Code to fix a failing test suite.

In practice, that usually plays out like this:

1. Read: pull the failing test output and the relevant source files
2. Decide: figure out the most likely fix
3. Act: edit the code
4. Observe: rerun the tests and check the result

If the tests still fail, Claude Code loops back to Read with the new failure message attached.

If they pass, the task is done.

That is the easiest mental model I know for understanding Claude Code.

It is not solving the whole problem in one leap.

It is making a series of small, informed decisions based on what happened right before.

A sub-agent runs the exact same loop, just inside its own isolated context window.

A single tool call performs one action.

A sub-agent can spend dozens of reasoning steps chasing one objective before it reports back to the main session.

Why Does Claude Code Bother With Sub-Agents at All?

Large repositories rarely fit inside one working context.

A monorepo mixing Python services, a React frontend, SQL migrations, and Terraform configuration holds far more information than any single agent should try to reason about at once.

So instead of treating the whole repository as one giant task, Claude Code hands off focused investigations to specialized workers.

One Explore agent might dig into authentication, another might inspect the database models, and a third checks the API routes.

The main session, often called the orchestrator, pulls those findings together before deciding what happens next.

There is a practical bonus here too: a lot of that investigation can run in parallel.

Instead of you reading every directory yourself, or waiting on one agent to crawl the entire repository start to finish, several sub-agents can explore different corners of the project at the same time.

You will see this pattern through the rest of the guide.

Explore agents gather information, Plan agents organize an approach, and General-purpose agents actually build the thing.

How Do You Install and Set Up Claude Code?

Before any of the sub-agent workflows below make sense, you need a working install.

The good news: this part takes about five minutes, and Anthropic has made the sign-in step noticeably less annoying than it used to be.

Installing Claude Code

Claude Code ships as an npm package, so you need Node.js 18 or later on your machine.

If you do not already have it, the npm installation docs walk through it for every operating system.

Install it globally with:

npm install -g @anthropic-ai/claude-code

Anthropic also ships a native installer if you would rather skip Node entirely, curl -fsSL https://claude.ai/install.sh | bash on macOS and Linux.

Pick one method and stick with it.

Mixing npm and the native binary is a fast way to lose an afternoon to PATH confusion, and I say that from experience.

Verify the install worked:

claude --version

If that prints a version number, you are set.

It is also worth confirming Git is installed, since most Claude Code workflows read repository history, create commits, or diff changes at some point.

Grab it from the official Git install guide if you need it.

Signing In (No API Key Required for Most People)

Older Claude Code guides walk you through generating an API key and exporting it as an environment variable.

That is no longer the default path.

Run claude for the first time, and it opens a browser window so you can log in with your existing Claude account instead.

If you already pay for Claude Pro, Max, Team, or Enterprise, that subscription covers Claude Code with no extra API billing.

An Anthropic API key is only worth setting up if you are running Claude Code inside a CI pipeline, a headless server, or another automation context where a browser login is not possible.

One thing worth flagging: if you have both a subscription and an ANTHROPIC_API_KEY environment variable set, the API key takes precedence and gets billed separately, which is an easy way to pay twice for the same tool without noticing.

Your First Claude Code Session

With Claude Code installed and signed in, move into any Git project with cd my-project, then launch it with claude.

Before asking it to write anything, spend a couple of minutes watching how it explores a repository.

I usually start with prompts like these:

• “What does this repository do?”
• “Explain the architecture.”
• “Find every TODO comment.”
• “Which modules hold the core business logic?”
• “How is authentication implemented?”

None of those produce a new feature.

What they do is give Claude Code the same context a new hire would gather before touching a single file.

In my experience, two or three minutes of exploration up front consistently produces better first attempts than jumping straight into a feature request.

The next step, and the one with the biggest long-term payoff, is setting up persistent project memory with CLAUDE.md.

Why Is CLAUDE.md the Most Important File in Your Repository?

CLAUDE.md is a persistent instruction file.

It tells Claude about your stack and your preferences before it starts reasoning about a task, so you are not re-explaining the same conventions every single session.

When people first hear about Claude Code agents, they usually obsess over prompt wording.

I think that is backwards.

A well-written CLAUDE.md does more for your results than any amount of prompt tweaking, because every agent you spin up starts from the same shared understanding of the project.

Think about onboarding a new engineer.

You would not hand them a ticket on day one and walk away.

You would explain the repository, show them how to run the tests, point out a few conventions, and warn them about the parts of the codebase nobody is allowed to touch without a very good reason. CLAUDE.md

does exactly that job, just once, in writing, for every future session.

This matters even more once you start building real autonomous workflows.

An agent working independently needs reliable project context.

Without it, Claude Code burns time rediscovering things you already know, or worse, guessing at standards that do not match how your team actually works.

What Should Actually Go In Your CLAUDE.md?

A good CLAUDE.md is not a rewrite of your README or your internal docs.

It is the specific set of instructions Claude Code keeps needing while it reads code, writes features, and runs your tools.

I organize mine into five sections: project overview, tech stack, coding conventions, common commands, and files to leave alone.

Project overview

Start with two or three lines describing what the project actually does.

Customer analytics platform built with FastAPI.
The application serves machine learning predictions through REST APIs.
Production deployments run through GitHub Actions.

Those three lines alone tell Claude Code it is working with FastAPI, GitHub Actions, and a machine learning application, not some generic Python repository.

Technology stack

List the major libraries and frameworks that define the project, with version numbers when they matter.

Python 3.12
FastAPI
Pydantic v2
SQLAlchemy
PostgreSQL
Pytest
Ruff

Pydantic v2 handles validation differently than v1, and Claude Code should not have to guess which API you are actually using.

This matters even more if you are running an older package version, since it stops the model from building on the wrong assumptions.

Coding conventions

This section captures the rules you find yourself repeating in code review.

Always use type hints.
Prefer dependency injection.
Write tests for every new feature.
Keep business logic separate from API routes.
Reuse existing utility functions before creating new ones.

These are engineering rules, not formatting preferences.

Claude Code can usually infer formatting from the files already in front of it, but it has no way of knowing your team expects dependency injection on every endpoint unless you write that down.

Common commands

Claude Code often checks its own work by running your actual development commands, so give it the real ones instead of making it guess.

Run tests:
pytest

Run one test file:
pytest tests/test_api.py

Lint:
ruff check .

Format:
ruff format .

Start the dev server:
uvicorn app.main:app --reload

This section pays off fastest on repositories with custom scripts, Docker workflows, or tools like poetry, uv, or tox that a generic guess would never land on.

Files and directories to avoid

Every repository has files that should never change automatically.

Never edit generated files.
Do not modify Alembic migrations.
Avoid changing Terraform configuration unless requested.
Do not update dependency versions automatically.

This one section has stopped more unwanted edits for me than everything else in the file combined.

One sentence telling Claude Code to leave generated code alone costs a lot less than reviewing a dozen files you never asked it to touch.

A Working CLAUDE.md Example

Here is a simplified version for a Python API project.

The markdown formatting here is not decoration, it genuinely helps Claude Code parse the file more reliably.

# Project Overview
Customer analytics platform built with FastAPI.

## Technology
- Python 3.12
- FastAPI
- PostgreSQL
- SQLAlchemy
- Pydantic v2
- Pytest
- Ruff

## Coding Standards
- Use type hints everywhere.
- Write tests for new features.
- Prefer dependency injection.
- Keep business logic separate from API routes.

## Common Commands
pytest
ruff check .
ruff format .

## Avoid Editing
generated/
alembic/versions/
terraform/

Do not aim for a perfect first draft.

My own CLAUDE.md has changed several times as I noticed the same instruction coming up again and again in conversations.

Treat it like source code you actively maintain, not documentation you write once and forget.

Project-Level or User-Level: Where Should CLAUDE.md Live?

Claude Code supports two scopes for these instructions, and knowing the difference keeps repository rules separate from your own personal habits.

Project-level CLAUDE.md

A project-level file sits right inside the repository, next to your source code.

my-project/
├── CLAUDE.md
├── app/
├── tests/
└── pyproject.toml

Everything in this file applies only to that one repository.

I use it for technology choices, testing commands, conventions, and any rule specific to that codebase.

Because the file lives with the source, everyone on the team gets the same instructions the moment they clone the project.

User-level CLAUDE.md

Claude Code also reads a global configuration file that follows you across every project, more of a personal operating manual than repository documentation.

Explain architectural trade-offs.
Suggest performance improvements when appropriate.
Default to Python examples unless another language is requested.
Keep explanations concise.

Those preferences hold regardless of whether I am working in FastAPI, React, or PyTorch that week.

One detail that confused me early on: these two files are not mutually exclusive.

Claude Code loads the user-level CLAUDE.md first, then layers the project-level file on top with repository-specific instructions.

Think of it as a hierarchy: the global file defines how you like to work, the project file explains how this particular repository works, and together they hand every agent both your personal preferences and the project context before it reasons about anything.

What Are the Three Types of Claude Code Sub-Agents?

Claude Code ships with three specialized sub-agent types because different jobs need different permissions.

An agent investigating a codebase has no business editing files, while an agent implementing a feature needs Bash, Git, and your test suite at minimum.

When I first started using Claude Code, I reached for the general-purpose agent for everything because it looked like the most capable option, which, in hindsight, was a bit like hiring a senior engineer to go find a stapler.

After a while I noticed I was burning more time and tokens than I needed to.

Most workflows get faster once you explore first, plan second, and implement last.

Explore vs. Plan vs. General-Purpose at a Glance

Here is how the three stack up side by side.

The names describe exactly what they do, but each one earns a distinct role in a larger workflow, so it is worth walking through them one at a time.

The Explore Agent: Your Read-Only Investigator

A Claude Code Explore agent searches a repository and summarizes what it finds without touching a single file.

It is the one I reach for most often when I open an unfamiliar project, since it beats scrolling through dozens of modules myself.

Good use cases include:

• Finding where authentication lives
• Tracing a request across several services
• Auditing logging or error handling
• Locating deprecated APIs
• Summarizing an unfamiliar package or directory
• Spotting duplicated business logic

Because Explore agents cannot edit files or run shell commands, they are also the safest ones to run several at once, which is where the parallel workflows later in this guide come in.

Picking a thoroughness level

Explore agents support different investigation depths, and matching the depth to the task saves both time and tokens.

If I just need to find a function, I stick with quick.

If I am prepping for a refactor that touches several packages, an extra minute for a deeper pass usually pays for itself several times over.

The Plan Agent: Strategy Before a Single Line Changes

A Plan agent studies a requested change and produces an implementation strategy without modifying the repository.

I almost never skip it, because reviewing a plan for an extra minute is a lot cheaper than discovering halfway through an implementation that three other modules depend on the code you are about to change.

A typical plan includes:

• Files that should change
• A recommended implementation order
• Dependencies and integration points
• A testing strategy
• Risks or assumptions worth flagging

Once you have reviewed the plan, you can either send it back for revisions or hand it straight to a general-purpose agent to build.

The General-Purpose Agent: Where the Actual Work Happens

A general-purpose agent can read files, edit source code, run Bash commands, run your tests, and keep working until it satisfies the objective you gave it.

It has the same repository context as the other two agents, plus permission to actually change things and check its own output.

Typical tasks include:

• Implementing new features
• Refactoring several modules at once
• Migrating dependencies
• Updating documentation
• Coordinating changes across multiple packages

General-purpose agents cost more tokens because they simply do more work: reading, writing, executing, and verifying.

That is the whole case for the explore, plan, implement pattern.

The cheaper agents answer the early questions, and you only spend the expensive tokens once the path forward is already clear.

Beyond the Built-In Three: Custom Subagents

Explore, Plan, and General-purpose are not the ceiling.

Claude Code also lets you define fully custom subagents as Markdown files with YAML frontmatter, stored in .claude/agents/ inside a project or in ~/.claude/agents/ for something that follows you everywhere.

Each one gets its own system prompt, its own tool permissions, and its own name, so you might end up with a code-reviewer, a security-scanner, and a test-runner that Claude routes to automatically based on the task in front of it.

Anthropic’s own subagents documentation covers the full configuration format.

I would not start here.

Get comfortable with the built-in three first, notice which investigations or checks you keep asking for by hand, then turn the repeated ones into a named subagent.

That is a better use of your time than designing a roster of custom agents before you have a single real workflow to test them against.

Running Your First Claude Code Agent Workflows

The best way to get real value out of Claude Code is to hand it an objective instead of asking for one small piece at a time.

Across Python projects, data pipelines, and web apps, I keep coming back to the same five-step shape:

1. Explore the repository
2. Create a plan
3. Review the plan
4. Implement the changes
5. Verify the results

None of that is mandatory, but it mirrors how a careful engineer already approaches a large change.

A minute spent understanding the repository usually saves several minutes undoing edits you did not actually want.

An hour spent tightening a prompt can save you an entire afternoon of cleanup later.

Workflow 1: Get Oriented in an Unfamiliar Codebase

An Explore agent is the right starting point whenever you inherit a repository or come back to one you have not opened in months.

Instead of clicking through directories on your own, ask Claude Code to investigate and report back.

Use an Explore agent to explain how authentication works.
Identify the main modules involved, summarize the request flow,
and highlight any technical debt or TODO comments.

What comes back will not be a wall of pasted source code.

You will usually get a clear explanation of the flow, the files that matter, and a short list of things worth a second look.

I treat that summary as the starting point for the next prompt instead of writing a fresh one from scratch.

Workflow 2: Plan Before You Touch Any Code

Once you understand the repository, ask a Plan agent to design the approach before any code changes.

This is one of the easiest habits to build, and it has saved me from more than one refactor that would have gone sideways.

Create an implementation plan for adding role-based access control.
Identify the files that should change, potential risks,
dependencies, and a recommended implementation order.
Do not modify any code.

Review that plan before moving on.

If it looks solid, hand it directly to a general-purpose agent.

If something feels off, it is far easier to fix a design document than to undo edits scattered across a dozen files.

One trick worth stealing: open a second Claude Code session and ask it to review the first one’s plan with a critical eye.

This is my current goal: add role-based access control to this repository.
Review this existing implementation plan critically.
Write a short report on its strong points and its weak points.

Workflow 3: Explore Several Subsystems at Once

Exploration does not have to happen one step at a time.

If your project has several independent subsystems, investigate them simultaneously instead of waiting on one long sequential pass.

For example, you could launch one Explore agent on the API layer, another on the database models, and a third on the machine learning pipeline, all at once.

While they work independently, the main session pulls their findings into a single response.

Look at the following components: the API layer, the DB models,
and the ML pipeline. Look for weaknesses in each.
Spawn subagents to do this work in parallel, have each one write
a short report, and combine the findings into one summary document.

I do not reach for parallel agents on every task, but on a large monorepo or a mature application with several services, it genuinely changes how fast you get oriented.

Multiple corners of the codebase get analyzed at the same time instead of one long queue.

Best Practices for Getting the Most Out of Claude Code Agents

Most problems people run into with Claude Code have nothing to do with the model itself.

They come from vague prompts, missing project context, or asking an agent to solve a problem it was never given enough information to understand.

These are the habits that have moved the needle the most for me.

Write Prompts an Agent Can Actually Execute

Claude Code performs best when the objective, the scope, and the definition of done are all explicit.

Instead of describing the end goal in general terms, spell out which repository to inspect, which files it should touch, and how you will know the task succeeded.

Vague: Improve the API.

Specific: Update the FastAPI authentication endpoints to use Pydantic v2 validation, generate or update the relevant pytest tests, run the test suite, and summarize every file that changed.

The second version gives Claude Code a real objective, real boundaries, and a real way to check its own work.

That combination usually means fewer follow-up prompts and a lot less manual cleanup on your end.

Manage Context Before It Becomes a Problem

Long sessions eventually pile up enough context that Claude Code starts spending tokens remembering old discussion instead of reasoning about the task in front of it.

When you notice that happening, run /compact to summarize the conversation while keeping what actually matters.

A solid CLAUDE.md helps here too, since project conventions do not need repeating every session.

Claude Code loads that context automatically, which leaves more of the working budget for the task you actually asked it to do.

Think About Token Cost Before You Reach for the Biggest Agent

Not every task calls for a general-purpose agent.

Need to find where a function is defined?

An Explore agent is faster and cheaper.

Reviewing a large architectural change?

A Plan agent usually gives you enough to work with, without touching a single file.

Save general-purpose agents for work that genuinely needs execution: editing files, running Bash, running tests.

Matching the agent to the task keeps both your runtime and your token bill under control.

Know When an Agent Is Overkill

Every agent run carries some overhead.

It investigates, reasons, and verifies its own work, and that process costs time even when the underlying change is small.

You probably do not need an agent to:

• Rename a single variable
• Fix a typo in a Markdown file
• Explain a Python error message
• Answer a quick SQL question

In those cases, a plain conversation, or just making the edit yourself, is usually faster.

My personal test before launching an agent: would explaining this task take longer than just doing it?

If yes, I keep it simple.

Final Thoughts

Claude Code agents change what AI actually does during software development.

Instead of handing you isolated snippets, they investigate repositories, design implementations, edit code, run tests, and work through multi-step objectives with comparatively little hand-holding.

The biggest thing I have learned is that better workflows beat better prompts almost every time.

A clear CLAUDE.md, a few minutes of exploration, and an actual plan before implementation consistently outperform jumping straight into code generation, no matter how carefully you word the request.

You will probably land on your own version of this workflow the more you use Claude Code.

Mine still starts the same way almost every session: explore first, plan second, implement last.

It is a simple habit, but it has saved me more review cycles than I can count, and it is the reason I trust autonomous workflows a lot more now than I did the first week I installed this thing.

So the next time you open a terminal and stare down a messy pull request, ask yourself one question before you touch a single file: what is the biggest piece of this you could actually hand off?