Claude Code Agents: A Practical Guide to Autonomous Coding Workflows

If someone asked me what makes Claude Code different from ChatGPT or GitHub Copilot, I wouldn't start with the language model. I'd start with the workflow.

Imagine opening a terminal inside a Git repository and typing a single 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.

Instead of asking dozens of follow-up questions, Claude Code begins working. 

It searches your project to understand the API structure, identifies every endpoint, edits the appropriate files, generates tests, fixes any failures, updates your documentation, and creates a Git commit summarizing the changes.

From your perspective, it feels less like chatting with an AI and more like assigning work to a capable teammate. 

That shift is what makes Claude Code agents so exciting.

The feature that makes this possible is Claude Code sub-agents. Rather than forcing one AI session to reason about an entire repository, Claude Code can launch specialized workers that investigate different parts of the project, build implementation plans, or modify code independently before reporting back to the main session. 

Rather than trying to solve every problem inside a single conversation, Claude Code can delegate work to specialized agents. 

The three main agent types are: 

• Explore, which focuses on exploring projects
• Plan, which focuses on building implementation plans, and
• General-purpose, which is used for editing code and executing commands.

I've found this changes how I approach development. Instead of asking, "Can the AI write this function?" I find myself asking, "What's the largest piece of work I can safely hand off?" 

By the end of this guide, you'll know how to use Claude Code agents effectively, when each sub-agent type makes sense, how to configure persistent project memory with CLAUDE.md, and how to build autonomous workflows that save time without giving up control. 

Prerequisites

This guide assumes you're comfortable using a terminal and navigating directories with basic command-line commands such as cd, ls, or dir. 

You do not need to be an expert in Bash, but you should feel comfortable working from the command line.

You'll also need:

• Node.js installed on your machine
• An Anthropic API key
• A Git repository to experiment with
• Basic familiarity with Python, JavaScript, or another programming language

If you're completely new to Claude Code, I also recommend reading Claude Code: A Guide With Practical Examples before diving into sub-agents.

What Are Claude Code Agents?

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

Unlike ChatGPT or Claude Chat, Claude Code can inspect files, execute Bash commands, edit source code, and verify its own work before returning a result.

Most AI coding assistants still follow a conversational workflow. 

You ask a question, receive an answer, and then decide what to do next. 

That works well for writing a SQL query or explaining a scikit-learn pipeline, but it starts to break down when a task spans 20 files, requires several terminal commands, or depends on understanding an unfamiliar repository.

Claude Code approaches those problems differently. 

Because it works directly inside your Git repository, it can investigate the code before making decisions. Instead of asking you to paste files into a chat window, it reads the project itself and gathers the context it needs.

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 traditional chatbot will probably generate example code and ask for more information. 

Claude Code searches the repository, identifies the existing validation logic, edits the relevant files, runs the test suite, fixes any regressions it introduced, and reports the completed work.

That shift from answering questions to completing objectives is what makes agentic coding with Claude Code feel different in day-to-day development.

How does the agent loop work? 

Every Claude Code agent follows the same decision cycle: read information, decide what to do next, act, then evaluate the result before repeating the process. 

The loop is simple, but repeating it dozens of times allows an agent to recover from mistakes instead of stopping after a single failed attempt.

Imagine asking Claude Code to repair a failing test suite. The workflow usually looks something like this:

Diagram showing how Claude Code operates while fixing failing tests

I think this is the easiest mental model for understanding Claude Code. 

The agent isn't trying to solve the entire problem in one step. It's making a series of small decisions based on what happened after the previous action.

A sub-agent follows exactly the same loop, but it does so inside its own isolated context. 

That distinction matters because a tool call performs one action, while a sub-agent can spend dozens of reasoning steps working toward a single objective before reporting back.

Why does Claude Code use sub-agents? 

Claude Code uses sub-agents because large repositories rarely fit inside a single working context. A monorepo with Python services, React applications, SQL migrations, and Terraform configuration contains far more information than one agent should reason about at once. 

Instead of treating the repository as one enormous task, Claude Code delegates focused investigations to specialized workers. 

One Explore agent might analyze authentication, another might inspect the database models, while a third reviews API routes. The orchestrator combines those findings before deciding what to do next.

This architecture has another practical advantage: many investigations happen in parallel. 

Rather than reading every directory yourself or waiting for one agent to inspect the entire repository, several sub-agents can explore different areas at the same time.

You'll see this pattern throughout the rest of the tutorial. Explore agents gather information, Plan agents organize the implementation, and general-purpose agents perform the actual development work.

If you'd like a broader introduction to how autonomous AI systems work beyond Claude Code, the DataCamp article LLM Agents Explained: Architecture, Frameworks, and Use Cases provides an excellent conceptual overview.

How Do You Install and Set Up Claude Code? 

Before we can start using Claude Code agents, we first need a working installation. 

Fortunately, getting started only takes a few minutes.

Installing Claude Code

Claude Code is distributed as an npm package, so you'll need Node.js installed on your machine. For instructions, I recommend following the npm docs on installation methods for Node.js and npm.

Install Claude Code globally with:

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

Next, create an Anthropic API key from the Anthropic Console and add it to your environment.

On macOS or Linux:

export ANTHROPIC_API_KEY="your_api_key_here"

On Windows PowerShell:

$env:ANTHROPIC_API_KEY="your_api_key_here"

To verify everything is installed correctly, run:

claude --version

If Claude Code prints its installed version, you're ready to go.

At this point, it's also worth confirming that Git is available since many Claude Code workflows involve reading repository history, creating commits, or comparing changes. 

If you do not have Git, follow the Git installation instructions to get started.

Both commands should execute successfully before moving on.

Your first Claude Code session

With Claude Code installed, navigate into any Git project by using cd my-project.

Then launch Claude Code: claude.

Before asking it to write code, spend a few minutes learning how it explores a repository. I usually begin with prompts like these:

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

Those questions don't produce new features, but they give Claude Code the same context a new teammate would gather before writing code. 

I've found that investing 2 or 3 minutes in exploration usually produces better implementations than jumping directly into a feature request.

The next step is configuring persistent project memory with CLAUDE.md. In my experience, no single file has a bigger impact on the quality of Claude Code's work over the long term.

Why Is CLAUDE.md the Most Important File for Claude Code?

CLAUDE.md is a persistent instruction file that tells Claude about your preferences and how your project works before it starts reasoning about a task. 

Instead of re-explaining your tech stack, coding conventions, and development workflow every time you open a new session, you document them once and let every future agent build on that shared context.

When people first learn about Claude Code agents, they usually focus on prompts. I think that's backwards. 

A well-written CLAUDE.md does more for the quality of your results than endlessly refining prompt wording because every agent starts with the same understanding of your project.

Think about how you'd onboard a new engineer. 

You probably wouldn't start by handing them a Jira ticket. You'd explain the repository, show them how to run the test suite, point out a few coding conventions, and warn them about the parts of the codebase that shouldn't be touched. 

CLAUDE.md serves exactly the same purpose.

The payoff becomes even more obvious once you start using Claude Code autonomous workflows.

An agent that's expected to work independently needs reliable project context. 

Without it, Claude Code spends time rediscovering information or making assumptions that may not match your team's standards.

What should you put in your CLAUDE.md?

A good CLAUDE.md isn't a replacement for your project documentation or your README.md. It's a collection of the instructions Claude Code repeatedly needs while reading code, writing features, and running development tools.

I usually organize mine into five sections: project overview, tech stack, coding conventions, common commands, and directories to avoid. I’ll go over each one briefly.

Project overview

Start with a short description of 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 immediately tell Claude Code it's working with FastAPI, GitHub Actions, and a machine learning application instead of a generic Python repository.

Technology stack

Next, literally just list the major libraries and frameworks that define the project.

Python 3.12
FastAPI
Pydantic v2
SQLAlchemy
PostgreSQL
Pytest
Ruff

I always include version numbers when they matter. 

The recommended approach for Pydantic v2 differs from Pydantic v1, and Claude Code shouldn't have to guess which API you're using. 

This is especially important if you’re using an older package, so it isn’t building off wrong assumptions.

Coding conventions

This section captures the rules you find yourself repeating.

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.

Notice that these are practical engineering rules rather than style preferences. 

Claude Code can usually infer formatting from existing files, but it won't automatically know that your team expects every endpoint to use dependency injection or every feature to include a pytest test.

Common commands

Claude Code often validates its own work by running development commands. Giving it the exact commands your team uses avoids unnecessary trial and error. 

This could be anything like specific task actions or CI scripts.

pytest
Run one test file:
pytest tests/test_api.py
Lint:
ruff check .
Format:
ruff format .
Start the development server:
uvicorn app.main:app --reload

This section is especially useful on repositories with custom scripts, Docker workflows, or tools such as poetry, uv, or tox.

Files and directories to avoid

Every repository has files that shouldn't change automatically.

Examples include:

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

I've found this section prevents more mistakes than almost any other. A single sentence telling Claude Code to leave generated code alone is much cheaper than reviewing dozens of unnecessary file changes.

An Example CLAUDE.md

Here's a simplified example for a Python API project. 

Take note of how I use markdown formatting to make things more human-readable and provide Claude more context.

# 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/

Don't worry about making your first version perfect. 

My own CLAUDE.md has changed several times as I've noticed recurring instructions that were worth documenting. Treat it like source code, not documentation that never changes. 

If you'd like a deeper dive into writing effective instruction files, DataCamp's Writing the Best CLAUDE.md: A Complete Guide for Claude Code covers larger examples and more advanced patterns.

Should you use a project-level or user-level CLAUDE.md?

Claude Code supports two scopes for persistent instructions. Understanding the difference keeps project rules separate from your personal preferences.

Project-level CLAUDE.md

A project-level file lives inside the repository.

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

Everything in this file applies only to that repository. I use it for technology choices, testing commands, coding conventions, directory structure, and repository-specific rules. 

Because the file lives alongside the source code, every contributor gets the same instructions after cloning the project. Think of it as providing every agent a manual before they get started.

User-level CLAUDE.md

Claude Code also supports a global configuration file.

This file follows you from project to project. I think of it as my personal operating manual rather than project documentation.

For example, my user-level file might include instructions like:

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

Those preferences make sense regardless of whether I'm working with FastAPI, React, or PyTorch.

How the two files work together

One detail that confused me when I first started using Claude Code is that these files aren't mutually exclusive. 

The user-level CLAUDE.md is loaded first, then the project-level CLAUDE.md adds repository-specific instructions.

I think of it as a hierarchy. 

The global file defines how I like to work. The project file explains how this repository works. 

Together, they give every agent both personal preferences and project context before it begins reasoning.

Claude Code combines user-level preferences with project-specific instructions before starting a task.

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

Claude Code uses three specialized sub-agent types because different development tasks require different tools. 

An agent investigating a repository doesn't need permission to edit files, while an agent implementing a feature probably needs access to Bash, Git, and your test suite.

When I first started using Claude Code, I reached for the general-purpose agent every time because it seemed like the most capable option. 

After a while, I realized I was paying more in time and tokens than I needed to. Most workflows become faster if you explore first, plan second, and implement last.

Comparing the Three Claude Code Sub-Agents

The names are fairly descriptive, but each agent fills a distinct role in a larger workflow.

What Is a Claude Code Explore Agent?

A Claude Code Explore agent is a read-only investigator that searches a repository and summarizes what it finds without changing any files.

This is the agent I use most often when opening an unfamiliar project. Rather than scrolling through dozens of Python modules or JavaScript components myself, I ask the Explore agent to explain how a subsystem works and point me toward the files that matter.

Good use cases include:

• Finding where authentication is implemented
• Tracing a request through several services
• Auditing logging or error handling
• Locating deprecated APIs
• Summarizing a package or directory
• Identifying duplicated business logic

Because Explore agents can't edit files or execute shell commands, they're also the safest agents to run in parallel.

Choosing a thoroughness level

Explore agents support different investigation depths.

If I only need to locate a function, I use the quickest setting. If I'm preparing for a refactor across several packages, waiting another minute for a deeper investigation usually pays for itself.

What Is a Claude Code Plan Agent?

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

I almost never skip this step. Spending an extra minute reviewing a plan is much cheaper than discovering halfway through an implementation that another subsystem depends on the code you're changing.

A typical plan includes:

• Files that should change
• Recommended implementation order
• Dependencies and integration points
• Testing strategy
• Risks or assumptions

Once you've reviewed the plan, you can either refine it or hand it directly to a general-purpose agent.

DataCamp's Claude Code Plan Mode: Design Review-First Refactoring Loops explores this review-first workflow in much more detail.

What Is a General-Purpose Claude Code Agent?

A general-purpose agent can read files, edit source code, execute Bash commands, run tests, and continue working until it satisfies the requested objective.

This is the agent that actually builds software. It has access to the same repository context as the other agents, but it also has permission to make changes and verify its work.

Typical tasks include:

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

General-purpose agents consume more tokens because they perform substantially more work. 

That's another reason I like the Explore → Plan → Implement pattern. 

The cheaper agents answer the early questions, leaving the more expensive implementation work until the path forward is clear.

By this point, we've covered the pieces that make Claude Code agents successful: persistent project memory through CLAUDE.md and specialized sub-agents for investigation, planning, and implementation. 

Next, we'll put those pieces together by building complete agentic workflows that you can start using in your own projects.

Running Your First Claude Code Agent Workflows

The best way to get the most value out of Claude Code is to give it an objective instead of asking for singular components.

I've settled into a simple workflow that works well across Python projects, data science repositories, and web applications:

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

That process isn't mandatory, but it mirrors how experienced engineers approach larger changes. 

Spending a minute understanding the repository usually saves several minutes of correcting unnecessary edits later. 

Creating a more thorough prompt, even taking an hour to fine-tune that prompt, can save you hours of work later.

Workflow 1: Explore an unfamiliar codebase

An Explore agent is the best place to start when you inherit a new repository or return to a project you haven't touched in months. 

Rather than reading directories manually, ask Claude Code to investigate the architecture and summarize what matters.

For example:

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.

The result won't be a wall of copied source code. Instead, you'll typically receive a concise explanation of the authentication flow, the files involved, and any areas that deserve attention. 

I often use that summary as the starting point for the next task instead of writing another prompt from scratch.

Workflow 2: Plan before you implement

Once you understand the repository, ask a Plan agent to design the implementation before writing code. 

This is one of the easiest habits to adopt, and it's saved me from several refactors that would have gone in the wrong direction.

A prompt might look like this:

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 the plan before moving forward. If everything looks reasonable, you can hand that plan directly to a general-purpose agent. 

If not, it's much easier to adjust a design document than it is to undo changes across a dozen files.

A great way to take advantage of this step is to use another Claude Code session to review the first one’s work. A simple prompt might go:

This is my current goal: to add role-based access control to this repository. 
Take a look at this existing implementation plan and do an adversarial review.
Once done, create a report that summarizes the strong and weak points of the plan.

Workflow 3: Parallelize repository exploration

One of my favorite features of Claude Code is that exploration doesn't have to happen sequentially. If your project contains several independent subsystems, you can investigate them at the same time.

For example, you might launch one Explore agent to inspect the API layer, another to review the database models, and a third to examine the machine learning pipeline. 

While those agents work independently, the orchestrator combines their findings into a single response.

I don't use parallel agents for every task, but they're a great fit for large monorepos or mature applications with many services. Instead of waiting for one long investigation, you can often understand the repository much faster because multiple parts of the project are being analyzed simultaneously.

The best way to do this is to use one large agent to orchestrate multiple agents. 

This agentic orchestration is a great way to have parallel work done without multiple sessions that are all shared into a singular context. 

A good prompt might look like this:

I want you to look at the following components: 
Inspect the API layer, review the DB models, and examine the ML pipeline. 
Look for weaknesses. 
I want this done in parallel, so spawn subagents using Opus/Sonnet models 
in order to do this work and have each generate a concise report and share out 
one master document that outlines the work needed to be done.

Best Practices for Claude Code Agents

Most problems people encounter with Claude Code aren't caused by the model. They're caused by vague prompts, missing project context, or asking it to solve a problem it doesn't fully understand.

After using Claude Code regularly, these are the habits that have had the biggest impact on my results.

Write prompts that agents can execute

Claude Code performs best when the objective, scope, and success criteria are explicit. 

Instead of describing the end goal in broad terms, tell the agent exactly what repository it should inspect, which files it should modify, and how you'll know the task is complete.

For example:

❌ 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 modified file.

The second prompt gives Claude Code a clear objective, boundaries, and a way to verify success. That usually leads to fewer follow-up prompts and less manual cleanup.

Manage context before it becomes a problem

Long conversations eventually accumulate enough context that Claude Code spends tokens remembering previous discussions instead of reasoning about the current task.

When that happens, use /compact to summarize the conversation while preserving the important context. I've found it's better to compact early than wait until performance noticeably declines.

A good CLAUDE.md also helps here because project conventions don't need to be repeated every session. Claude Code loads that context automatically, leaving more time for the work you're asking it to perform.

For more advice on context management, test-driven development, and prompt design, see Claude Code Best Practices: Planning, Context Transfer, TDD.

Think about token costs

Not every task needs a general-purpose agent.

If you only need to find where a function is defined, an Explore agent is usually faster and less expensive. 

If you're reviewing a large architectural change, a Plan agent often gives you enough information without modifying the repository.

Reserve general-purpose agents for tasks that actually require execution. Things like editing files, running Bash commands, or running tests. Matching the agent to the task keeps both runtime and token usage under control.

Know when not to use agents

Claude Code agents introduce some overhead because there is some context and token exchange. 

They investigate the repository, reason through the task, and verify their work. For very small changes, that overhead isn't always worthwhile.

You probably don't 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 situations, a normal Claude Code conversation or even a manual edit is often faster. I usually ask myself one question before launching an agent: Would I spend more time explaining this task than doing it myself? If the answer is yes, I keep it simple.

Final Thoughts

Claude Code agents change the role AI plays during software development. Instead of generating isolated snippets, they can work through more complicated problems like investigating repositories, designing implementations, modifying code, executing tests, and working through multi-step objectives with relatively little supervision.

The biggest lesson I've learned is that better workflows matter more than better prompts. 

A clear CLAUDE.md, a few minutes of repository exploration, and a thoughtful implementation plan consistently produce better results than jumping straight into code generation.

As you spend more time with Claude Code, you'll probably develop your own workflow. Mine still starts the same way almost every time: explore first, plan second, implement last.

It's a simple habit, but it has saved me countless review cycles and helped me trust autonomous workflows much more than I did when I first started using them.

If you'd like to learn more about the broader ideas behind autonomous systems, I recommend the following resources:

• Introduction to AI Agents 
• Introduction to Claude Models 
• Claude Code Hooks: A Practical Guide to Workflow Automation 
• Claude Agent SDK Tutorial: Create Agents Using Claude Sonnet 4.5 
• How to Build Claude Code Plugins 
• Claude Code 2.1: A Guide With Practical Examples 
• Model Context Protocol (MCP): A Guide With Demo Project 
• AI Agents with Hugging Face smolagent