How to Build an AI Agent in Claude Code


📺

Article based on video by

Tristen O’Brien — Watch original video ↗

A ten-item to-do list can take all day when every task waits for the one before it. I spent a week testing ways to split that list across focused Claude Code agents, and the biggest improvement was not speed—it was knowing exactly what each agent could and could not do.

📺 Watch the Original Video

What a Claude Code AI Agent Actually Does

A Claude Code AI agent is software that takes an objective, works out the steps, uses available tools, and reports back with limited supervision. Instead of answering one question at a time, it can handle multi-step coding, research, file, and automation tasks from plain-language instructions.

The important distinction is control: the agent prepares and coordinates the work, while you still decide what actually gets approved or published.

From a to-do list to delegated work

Imagine giving Claude a list of 10 tasks: research competitors, summarize a document, update a configuration file, and draft an email. The main agent receives everything, classifies each item, breaks complex requests into smaller steps, and sends suitable work to specialized helpers.

Independent tasks can run simultaneously rather than one after another, which is useful when a list contains several research or drafting jobs. Claude Code’s documentation specifically describes spawning multiple agents to work on different parts of a task at the same time.[2]

What surprised me here was how much of the value comes before execution: sorting and preparing the work is often the tedious part.

The main agent and its subagents

The main agent acts like a project manager. It keeps the overall objective, assigns tasks, then combines the returned results into one response.

A subagent is a separate Claude instance with its own context window, instructions, tools, and permissions.[3] One might research, another review code, and a third edit files. Because their intermediate tool calls stay out of the main conversation, the central workflow stays cleaner.[6]

This is like a sous chef who preps several stations at once: each specialist focuses on one job, while the head chef assembles the meal.

Why this is different from a chatbot

A chatbot usually responds to the prompt in front of it. An agent can plan, act, verify, and report across multiple steps.

But here’s the catch: “autonomous” does not mean “hands-off.” Permission settings can restrict tools and actions, including whether a subagent may edit files.[1] For beginners, the best mental model is a structured workflow that automates preparation while keeping you in control—not a robot that publishes or sends everything without asking.

Why Parallel Agents Make a To-Do List More Useful

A plain to-do list tells you what needs doing. A parallel agent workflow also decides who—or what—should handle each task, then works on separate items at the same time. The payoff is simple: if research takes 10 minutes, drafting takes 6, and file inspection takes 3, the total can be closer to 10 minutes than 19.[1]

Parallel versus sequential execution

Sequential execution handles one item, waits, then starts the next. Parallel execution is more like sending several sous chefs to prep different ingredients: a research agent gathers sources, another prepares a schedule, and a third checks files concurrently.

Useful subagent roles include research, drafting, summarization, planning, testing, file inspection, and checklist preparation. In my experience, this is where productivity workflows become genuinely practical—not because the AI “does everything,” but because each worker has a clear job.

Start with three to five clearly separated tasks, not a messy list of 30 vague requests. Parallel work still consumes shared tokens and usage limits, so it should earn its keep by saving meaningful time.[2]

Context isolation and specialization

Each subagent gets its own working context and returns a result to the main conversation. That means a research agent can read a pile of documents without flooding your chat with every search result, log entry, or half-formed thought.[3]

This separation also improves focus. A testing agent can look for failures, while a drafting agent concentrates on wording—similar to having a GPS recalculate one route instead of making everyone in the car debate every turn.

When tasks must stay in order

Not every task belongs in the same parallel batch. Independent work—such as researching a topic while preparing a calendar—can happen together, but a final draft may need the research findings first.

A sensible workflow is: research, then draft, then review. Treat those as stages, while running unrelated tasks inside each stage concurrently. The main agent can then gather the results and produce one coherent answer without pretending that unfinished work is complete.

How to Build the To-Do List Agent Step by Step

The simplest useful version of a to-do list agent has one job: accept your complete list, find the independent tasks, delegate them, verify the results, and return one organized report. Think of it like a project manager with a clipboard—helpful only if it checks whether the work actually happened.

Define the agent’s purpose and input format

Start with a clear objective: break down tasks, identify dependencies, assign the right specialist, and pause when human approval is needed. For each task, require these six fields: task name, goal, deadline, dependencies, required resources, and whether it involves an external action.

That last field matters. “Draft an email” is different from “send an email,” just as planning a trip differs from booking the flight. I’ve found that vague inputs create more cleanup than useful automation.

Write reusable operating instructions

Tell the agent to classify every task as research, drafting, analysis, file work, execution, blocked, or approval-required. Then make the workflow explicit: plan first, execute second, verify third, and report last.

The agent should never treat its first generated answer as completion. For example, a research task might require two independent sources, while a file task might require confirming that the intended file changed.

Create task states and output rules

Use consistent states: pending, active, completed, failed, blocked, and awaiting approval. Each subagent should return the same fields: result, evidence, uncertainty, blockers, next step, and suggested action.

This structure makes a 10-task report readable instead of turning it into a wall of confident-sounding text. Most tutorials get this wrong by focusing on generation and skipping verification.

Assign tools and permissions by role

Create narrowly scoped custom subagents with dedicated prompts and only the tools they need. Claude Code supports separate context windows, custom tool access, independent permissions, and model assignments for these agents.[2][5]

A research agent should usually be read-only; editing or command permissions belong only to agents that genuinely need them. Read operations such as file inspection can be permitted without approval, while edits and shell commands generally require additional permission controls.[1][4]

Finally, run independent tasks in parallel rather than one at a time. The main agent can collect the results, check missing evidence, request approval for external actions, and produce one final report.[3]

Verification, Errors, and Human Approval

A delegated task is not finished when an agent says “done.” It’s finished when you’ve checked that the requested work happened, the supporting files or sources exist, and the result matches the format you asked for. I’ve found this simple verification stage prevents the most embarrassing kind of automation error: a polished answer built on nothing.

Check results before reporting completion

Tell the main agent never to invent a completed result. If a subagent lacks access, hits an error, or cannot verify its claim, the final response should say so plainly.

For example, “Task 2 failed because the folder was inaccessible; retry with permission to read `/reports`” is useful. “All tasks completed” is not. Sound familiar? Confidence is not evidence.

Handle failures without losing unrelated work

One failed subagent should not stop independent tasks. Let the research, draft, and file-organizing agents finish, then label the failed item separately and explain what would make a retry possible.

This is like a kitchen where one ingredient is missing: the sous chef can still prep everything else, but nobody should pretend the dish is complete.

Add approval gates for consequential actions

Pause before sending messages, submitting forms, publishing content, deleting files, spending money, or making another irreversible change. The agent can prepare a draft or proposed command, but the human authorizes the consequential step.

Before asking, show four things: the proposed action, the affected resource, the expected result, and the possible downside. That small checkpoint is especially valuable when a task list contains mixed-risk actions.

Use permission settings as guardrails

Claude Code’s permission modes determine which actions require approval. Manual mode asks before most file edits, shell commands, and network activity, while still allowing routine read-only work.[1][2]

Use allow, ask, and deny rules to control tools, directories, commands, and subagents. Deny rules take priority over ask and allow rules, so sensitive paths or destructive commands stay blocked even if another setting would permit them.[1][7]

The goal isn’t to make the agent timid. It’s to keep the workflow approval-aware: automate preparation, preserve verification, and reserve irreversible decisions for a person.

A Real Example: Running and Improving the Workflow

Imagine handing an agent this list: research a laptop comparison, draft a follow-up email, summarize a PDF, check a project folder, and prepare tomorrow’s meeting agenda. The useful part isn’t just automation—it’s deciding what can happen safely in parallel.

Example input and delegation plan

Before starting, have the main agent create a delegation plan for every item: owner, objective, dependencies, tools, permission level, expected output, and approval requirement. Research and summarization can run independently; an agenda may depend on the folder review.

In Claude Code, open a session, provide the reusable instructions, paste the full list, and start the workflow. The main agent can monitor parallel subagents, then review their outputs before approving selected external actions. Each subagent has its own context, tools, and permissions, which helps prevent unrelated tasks from crowding one conversation.[4]

What the consolidated report should contain

The final report should include completed work, findings, unresolved issues, failed tasks, proposed actions, and items awaiting approval. Five finished tasks are less useful than four finished tasks plus one clearly labeled failure.

I’d also include a confidence or verification note. Plausible text is not proof that a file was checked or an email was sent—this is where most beginner workflows get it wrong.

Common beginner mistakes

Vague prompts produce vague ownership. Excessive permissions create unnecessary risk, while mixing dependent tasks into one parallel batch creates bad sequencing.

For example, don’t ask the agent to “handle the project folder” if you mean “list files only.” Manual permission mode starts read-only and asks before file edits, shell commands, or network access.[1] That friction is helpful.

A practical testing checklist

Start with harmless read-only tasks. Then add file changes, command execution, and network actions one permission layer at a time; Claude Code supports controls for specific subagents as well.[2]

Measure completion accuracy, false claims, unnecessary approval requests, failure recovery, and whether the final report makes next steps obvious. A reliable pattern is: input, classify, delegate, execute, verify, aggregate, request approval, then report. Think of it like a GPS that recalculates—when one route fails, the system should explain the detour instead of pretending it arrived.

Frequently Asked Questions

Can Claude Code run multiple subagents at the same time?

Yes. In my experience, parallel subagents work best when tasks are independent—for example, one can review authentication while another updates the UI and a third runs tests. Give each agent a separate scope, and use worktrees when they may edit overlapping files.

How do I create a custom agent in Claude Code?

Create a Markdown file in `.claude/agents/` for a project-specific agent, or `~/.claude/agents/` for one available across projects. What I’ve found is that a useful definition clearly states the role, instructions, and tools—for example, a reviewer limited to `Read`, `Grep`, and `Glob` cannot modify code.

What permissions should a Claude Code subagent have?

Start with the minimum permissions needed: a research or review agent usually needs read-only tools, while an implementation agent may need editing and test commands. For example, allow `Read` and `Grep` for code review, but deny access to `.env` files and secrets unless the task genuinely requires it.

Can Claude Code ask for approval before sending an email or changing a file?

Yes—permission rules can make Claude pause before tools such as email, shell commands, or file edits, unless those actions were already allowed. A practical setup is to pre-approve safe reads and tests while requiring approval for `git push`, external messages, and changes outside the project directory.

How do I make Claude Code handle dependent tasks instead of running everything in parallel?

Describe the dependency chain explicitly and tell Claude which step must finish before the next begins—for example: inspect the schema, then update the API, then modify the UI, then run integration tests. If several tasks touch the same files or rely on shared output, keep them in one session or assign them sequentially rather than launching parallel agents.

Start with five low-risk to-do items, give each task a clear owner and output format, and keep approval enabled until the workflow proves reliable.

Subscribe to Fix AI Tools for weekly AI & tech insights.

O

Onur

AI Content Strategist & Tech Writer

Covers AI, machine learning, and enterprise technology trends.