Dev, AI

AI agents don't code for you: they orchestrate. Here's how it actually works

Alexandre

·03/02/2026·

Reading time: 12 min

I told Claude "add OG images to the blog." 30 seconds later: 4 files created, an endpoint generated, meta tags updated, build passing. I didn't touch a thing.

A code agent doesn't write Swift for you — it orchestrates 6 systems in parallel, reads 12 files, runs 4 Bash commands, catches an error, fixes it and starts over. All on its own.

I've already shared how I work with Claude Code on a daily basis — the CLAUDE.md, the slash commands, the 6 agents. But I never explained what's really going on under the hood. Why it's different from a chatbot that generates code. And more importantly: the real limitations after 8 months of intensive use.

A technical deep dive into the architecture of code agents in 2026: agentic loop, multi-agent coordination, MCP protocol.

Agent vs chatbot: the difference is in the loop

A chatbot is simple. You ask a question, it answers, done. Even the most powerful models work this way: text input, processing, text output. No action in the real world.

A code agent is a different species. It's a system that can act. Read files, run Bash commands, modify code, run tests, query databases. And most importantly, it loops: it observes the results of its actions and adjusts its reasoning accordingly.

The classic loop of a code agent:

1. REASON     →  analyze the request and context
       ↓
2. PLAN       →  decide which actions to execute
       ↓
3. ACT        →  call tools (Read, Write, Bash, Grep...)
       ↓
4. OBSERVE    →  read the results of actions
       ↓
5. ADJUST     →  correct if needed
       ↓
6. REPEAT until completion

Anthropic calls this the tool-reasoning-action loop. It's what fundamentally differentiates an agent from a copilot. A copilot suggests code you copy-paste. An agent modifies it directly, checks that it compiles, detects errors, fixes them, and lets you know when it's done.

In practice, when I ask Claude Code to add a refresh button to my admin page, here's what happens:

It reads the relevant file (AdminMarketingPage.tsx)
It searches for existing patterns in the project (custom hooks, components, icons)
It modifies the file by adding the button following the project conventions
It verifies that the TypeScript build passes
If there's an error, it adjusts and retries

All in 30 seconds. Without me having to say "look at this file, understand this pattern, follow this convention." It does it on its own because it has access to tools and it loops.

A chatbot answers you. An agent acts, observes, corrects and loops back. The loop changes everything.

The 4 building blocks that power an agent

When I understood the architecture, I realized that my 6 agents all share the same foundational blocks. What changes between them is their specialization and context.

1. The planning module

This is what breaks down a complex request into subtasks. When I say "add auto-generated Open Graph images to the blog + similar articles at the bottom of the page", the agent doesn't dive straight into code. It decomposes: create the image endpoint, update the meta tags, create the similar articles component, integrate everything.

2. Context memory

That's the CLAUDE.md, project conventions, session history. I've already talked about CLAUDE.md in detail in my previous article, but to keep it simple: without memory, an agent generates generic code. With it, it respects the existing architecture and avoids recurring mistakes. This is what makes the difference between a useful agent and one that does whatever it wants.

3. The tool interface

Claude Code's native tools: Read (read files), Write (create), Edit (modify), Bash (run commands), Grep (search code), Glob (find files), WebSearch (web search), Agent (spawn subagents). Each agent can have a different subset of tools depending on its role.

4. The reflection engine

This is the self-critique capability. The agent executes an action, observes the result, and asks itself: "does this answer the request? Does the build pass? Does it follow conventions?" If not, it starts over. It's the most underestimated component, and it's what separates a good agent from a bad one.

Why 6 specialists beat one generalist

For 2 months, I used Claude Code with a single agent. It worked. Then one January morning, I asked: "add auto-generated Open Graph images to the blog + similar articles at the bottom + fix the sitemap." 20 minutes later, I had an endpoint generating images... in Swift. In the Express backend. With SwiftUI imports right in the middle of TypeScript code. The agent had mixed everything up.

That's when I understood: an agent that does everything is like a dev handling iOS + backend + QA + security at the same time. That doesn't exist. Why would AI be any different?

6 agents instead of one isn't over-engineering. It's a senior team instead of an intern doing everything.

My setup in .claude/agents/:

.claude/agents/
  maestro.md         # Orchestrator — NEVER codes
  impl-ios.md        # Senior iOS dev (SwiftUI/Swift 6)
  impl-backend.md    # Backend dev (Express/TypeScript)
  review.md          # Quality gatekeeper (pre-commit, score /100, pre-merge)
  test.md            # Automated QA (detection, execution, analysis)
  audit.md           # Tech debt auditor

Agent	Context loaded	Tools enabled	Expected output
maestro	Global architecture, roadmap	None (delegates only)	Execution plan + agents mobilized
impl-ios	SwiftUI conventions, Design System	Read, Write, Edit, Bash	Valid Swift code + tests
impl-backend	Express, Sequelize, ref.conf.json	Read, Write, Edit, Bash	Endpoints + migrations
review	Quality guidelines, OWASP top 10	Read, Grep, Glob	Score /100 + fixes
test	Existing test suites	Read, Bash, Grep	Results + coverage
audit	Codebase history	Read, Grep, Glob	Tech debt report

The benefit is twofold. Each agent has a reduced context (it only loads what it needs), so it reasons better. And agents don't pollute each other: iOS implementation details don't clutter the backend dev's context.

How agents collaborate without stepping on each other

The real challenge isn't building 6 agents. It's making them collaborate without stepping on each other's toes.

The supervisor pattern

My maestro is the entry point. It doesn't code. It doesn't write specs. It analyzes, decides, delegates and validates. Its description:


You are the Maestro of the Livate team.
You do NOT code. You do NOT write specs.
You analyze, decide, delegate, coordinate,
and validate results.

Maestro never codes. It analyzes, delegates, coordinates and validates. Like a CTO who hasn't touched code in 3 years.

Real example: the OG images feature

Last week, I asked: "add auto-generated Open Graph images to the blog + similar articles at the bottom of the page."

Step 1 — the maestro analyzes:

It identifies 2 independent features, evaluates complexity, and decides to parallelize.

Step 2 — it delegates in parallel:

Agent: impl-backend
Task: Create endpoint /api/og/route.tsx (dynamic OG image)

Agent: impl-ios
Task: Create SimilarArticles.tsx + integration in [slug]/page.tsx

Step 3 — the subagents act:

impl-backend reads the @vercel/og docs, creates the file, adds the meta tags, tests image generation.

impl-ios reads ArticleCard.tsx to understand the existing design, creates the component, integrates it at the bottom of the page, checks visual consistency.

Step 4 — the maestro validates:

Both subagents return a concise summary (not the full code, just the result). The maestro checks that the build passes, conventions are followed, and triggers the commit.

Except. The build passes, but when I test the OG image on Twitter Card Validator, it returns a 404. Why? Because impl-backend created the endpoint but forgot to update the config that blocks unauthorized /api/* routes. Something a dev would've caught in 2 seconds because they know the infrastructure. I had to tell it: "check the middlewares and the route config."

Final result: 4 files created/modified, 1 config adjusted, 25 minutes instead of 20. Not magic, but still 10x faster than doing it by hand.

Memory scope: avoiding pollution

Each subagent returns a summary of 200 tokens max to the maestro. Example: when impl-backend creates an endpoint, it doesn't return the 150 lines of code. It returns:


Endpoint /api/og/route.tsx created
- Generates a 1200x630 image with title + excerpt
- Uses @vercel/og
- Meta tags added in [slug]/page.tsx

The maestro knows it's done, but its context isn't polluted by implementation details. This is what allows chaining features without saturation.

MCP: the protocol that connects AI to the outside world

Claude Code can read files, run Bash commands, search code. But to interact with GitHub, Figma, your database or Google Analytics, you need the Model Context Protocol (MCP). It's the standardized plugin system that connects AI to the rest of the world.

How it works

An MCP server is a small process that runs in the background and exposes tools via a standardized API. Claude can call these tools as if they were native.

Example with GitHub. You configure the server in .claude/mcp.json:


{
  "servers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Once configured, Claude can list issues, create pull requests, comment on reviews, merge a PR. You just say "create a PR for this feature", and Claude uses the corresponding MCP tool.

MCP is USB-C for AI agents. One protocol, all tools become compatible. No more hacking things together.

Concrete use cases

Figma -> Code: the Figma MCP server lets Claude read designs, extract colors, spacing, and generate SwiftUI or React code that matches the mockup.

Database: the PostgreSQL MCP server lets Claude query your DB directly, analyze schemas, generate migrations. "Which users have never commented on an article?" -> Claude runs the query and gives you the answer.

Analytics: a custom MCP server can expose the Google Analytics 4 API. Claude analyzes your traffic stats, detects anomalies, suggests SEO optimizations.

The 3 MCP pitfalls (I fell into all of them)

The complexity explosion. The more MCP servers you add, the more tools Claude has available. Past a certain point, it gets confused and picks the wrong tools. My rule: 5 active MCP servers max. Beyond that, create specialized agents with tool subsets.

Silent failures. A misconfigured MCP server can fail without Claude telling you. I've had sessions where Claude tried to use the GitHub MCP tool, it failed silently, and it moved on. Result: the PR was never created. My rule: always manually verify critical actions.

Credential leaks. MCP servers need tokens. If you hardcode them in .claude/mcp.json, you risk committing them by mistake. My rule: environment variables only, and everything in .claude/ goes in .gitignore.

Lessons learned: the real gains

Now that you know the architecture, let's talk about the real question: does it actually work?

Metric	Before Claude Code	With Claude Code	Gain
Average feature	1-2 days	1-2 hours	10x
Backend refactor	1 week	1 day	5x
Writing a blog post	3-4 hours	1 hour	3x
Full SEO audit	1 day	30 minutes	15x

But it's not just about speed. It's also about quality. Before, my commits were messy. I'd mix multiple features, forget to update docs, leave console.log() calls lying around. Now, Claude follows a strict checklist: build, tests, lint, docs, structured commit message. My Git history is 10x cleaner.

When Claude is better than me

Config files. Docker Compose, Tailwind, TypeScript, ESLint, Liquibase. Claude knows every option, doesn't make typos, and follows conventions. My 150-line docker-compose.yml — I never wrote it by hand.

Unit tests. Writing tests is tedious. Claude generates them in 10 seconds, covers edge cases, mocks dependencies properly. My coverage rate skyrocketed.

Version migrations. Migrating from Next.js 14 to 15 means hundreds of small changes. Claude reads the changelog, identifies breaking changes, and refactors the project in 2 hours. By hand, it would've taken me 2 days.

Repetitive tasks. Renaming 50 variables across 20 files. Adding a field to 15 TypeScript interfaces. Anything mechanical, Claude does in 30 seconds without complaining.

The 5 things AI still gets wrong

It's not magic. 5 situations where Claude struggles:

1. Product decisions

Claude doesn't know why you're building this feature. It can implement a push notification system in 30 minutes, but it'll never tell you if that's actually what your users need. Product vision is 100% on you.

2. Obscure bugs

Last week, an intermittent iOS app crash. Only on iPhone 12 mini, in dark mode, after 20 minutes of use. Claude proposed 10 solutions, none of them worked. I ended up debugging manually with Instruments and Xcode. Bugs that depend on complex global state are still a human's job.

3. Over-engineering

The classic trap. 3 days ago, I asked for a simple sort on the blog article list. By descending date, that's it. What I got: a configurable sorting system with 3 enums for priorities (DATE, VIEWS, LIKES), a cache to store the order, detailed logs on every call, and a config file to enable/disable algorithms. 187 lines for a .sort() that needed 12.

I learned to be ultra-specific: "Sort the list by descending date. One .sort(), nothing else." No room for interpretation. An unconstrained agent is like a dev trying to show off on Hacker News instead of shipping.

4. Performance

Claude produces code that works, but not necessarily optimized code. It won't detect that a SQL query has 3 nested loops instead of a single JOIN. Or that a React component re-renders 50 times per second. Performance optimization is still a senior dev's job.

5. Security

The most insidious one. Claude can generate an Express endpoint that works perfectly, passes all tests, and exposes an obvious vulnerability. Real example: a /api/users/:id endpoint that didn't check whether the logged-in user had permission to modify that ID. Anyone could modify anyone's profile.

Anthropic launched Claude Code Security in February 2026 to detect this kind of thing. But a manual audit remains essential for anything involving auth, payments, or sensitive data.

An agent generates code that works. Not code that survives 10,000 users. The difference is 3 years of production experience.

What's coming in the next 12 months

Code agents aren't a beta for geeks anymore. They're mainstream. And here are 4 things I see coming in the next 12 months.

Agent teams become the norm

Anthropic says it in their 2026 Agentic Coding Report: we're moving from individual agents to coordinated teams. In a year, having a single agent will be considered archaic. Everyone will have an orchestrator + 5-10 specialized agents.

MCP becomes a universal standard

Microsoft, Google, OpenAI, Anthropic are all converging on the Model Context Protocol. By 2027, every SaaS app will have an official MCP server. Figma, Notion, Linear, Stripe, Vercel. You'll be able to drive your entire stack from a terminal.

What I'm hoping for: long-term memory

Today, Claude forgets everything between sessions (except what's in the CLAUDE.md). I'd love for it to remember that I prefer strict TypeScript, that I use React Query, that I hate nested ternaries. For it to adapt to me over weeks, without me having to re-document everything in the CLAUDE.md.

The dev becomes an architect of agentic systems

Code becomes a commodity. Anyone can generate 10,000 lines in 1 hour. What has value is knowing what to build, understanding user needs, structuring context for agents, and validating the quality of generated code.

The 2027 dev spends more time reading code they didn't write than typing it. They orchestrate, validate, correct. The keyboard becomes secondary.

In 2027, you'll have an agent watching your repo while you sleep. And another one auditing the first.

5 tips if you're getting started

1. Start small. Don't configure 10 agents on day one. Start with 1 generalist agent, add a solid CLAUDE.md, and iterate. When a type of task keeps recurring (tests, refactoring, auditing), that's when you create a dedicated agent.

2. Document your patterns. The CLAUDE.md is your best investment. 2 hours putting in the architecture, conventions, recurring mistakes. Update it every week. That's what makes the difference between an agent generating random code and one that respects your project.

3. Always validate critical actions. Never auto-merge, never auto-deploy, never delete without manual validation. Agents are powerful, but they make mistakes. A human must have the final say on what goes to production.

4. Commit before every refactor. When Claude breaks 12 dependencies trying to "clean up", you roll back in 10 seconds. Git is your safety net.

5. Let it explore before coding. Before "implement X", ask "how does Y work in the project?". Claude will read the files, understand the patterns, and its implementation will be consistent with what already exists.

Conclusion

Code agents aren't an improved copilot. They're a paradigm shift. We're moving from "I type code" to "I structure context and orchestrate agents."

The agentic loop. The 4 building blocks. Multi-agents. The MCP protocol. That's the invisible infrastructure changing the game. And the real value is no longer in the line of code — it's in product vision, understanding user needs, and the ability to pilot a team of agents without getting dragged into over-engineering.

8 months working this way. An app in production. A blog. A backend. All solo. Not because AI coded everything, but because I stopped coding and started orchestrating.

And you, do you code with agents? What are you struggling with? Context saturation? Over-engineering? Send me a message on Twitter/X or drop a comment, I'm curious to hear what's blocking you.

Alex

Key takeaways

A chatbot answers you. An agent acts, observes, corrects and loops back. The agentic loop changes everything.
6 specialized agents isn't over-engineering. It's a senior team instead of an intern doing everything.
MCP is USB-C for AI agents. One protocol, all tools become compatible.
AI still misses 5 things: over-engineering, duplication, security, integration tests, and UX. The dev remains essential.
The value is no longer in the line of code. It's in product vision and the ability to orchestrate.

← Back to articles

10 Ways to Cut Your Token Bill by 5x (Copilot, Claude Code, Cursor)

7/17/2026•15 min

Dev, AI

10 Ways to Cut Your Token Bill by 5x (Copilot, Claude Code, Cursor)

Opus at $25/M tokens, Haiku at $5. 10 practical levers to reduce your consumption by 60 to 90% across all AI agents.

Lire l'article→

The vibe coding trap: 97% of AI-generated apps never ship

4/9/2026•4 min

Dev, AI

The vibe coding trap: 97% of AI-generated apps never ship

Forbes named it today. 92% of devs use AI coding tools daily, 46% of new code is AI-generated — and 97% of vibe-coded apps never make it to production.

Lire l'article→

4/4/2026•7 min

Dev, AI

How I cut my Claude Code token usage in half

Not with /compact. With what I set up BEFORE opening a session. CLAUDE.md, hooks, and proactive rules: my setup to cut token consumption by 40 to 60%.

Lire l'article→

Comments

Got a take on this article?

Create a free account in 10 seconds to comment, like, and get the next articles straight to your inbox.

Don't have an account yet?

AI agents don't code for you: they orchestrate. Here's how it actually works

Agent vs chatbot: the difference is in the loop

The 4 building blocks that power an agent

Why 6 specialists beat one generalist

How agents collaborate without stepping on each other

The supervisor pattern

Real example: the OG images feature

Memory scope: avoiding pollution

MCP: the protocol that connects AI to the outside world

How it works

Concrete use cases

The 3 MCP pitfalls (I fell into all of them)

Lessons learned: the real gains

When Claude is better than me

The 5 things AI still gets wrong

1. Product decisions

2. Obscure bugs

3. Over-engineering

4. Performance

5. Security

What's coming in the next 12 months

Agent teams become the norm

MCP becomes a universal standard

What I'm hoping for: long-term memory

The dev becomes an architect of agentic systems

5 tips if you're getting started

Conclusion

Key takeaways

Related articles

10 Ways to Cut Your Token Bill by 5x (Copilot, Claude Code, Cursor)

The vibe coding trap: 97% of AI-generated apps never ship

How I cut my Claude Code token usage in half

Comments

Comments