From 1 to 18: Building an Agent Army in Less Than a Week

The most common mistake I see people make with AI agents is keeping them general. One agent, one massive prompt, every task. It works well enough that you don’t immediately notice the problem. Then you start doing real work, and the cracks appear.

Over five intense days, I went from 1 generalist agent to 18 specialists. This is the story of how that happened, why it was necessary, and what the final architecture looks like. (The memory infrastructure these agents rely on is covered in Three-Tier Memory.)

Why Generalists Fail at Scale

A generalist agent can do everything. It can also do everything badly at the same time.

The problem isn’t capability — modern AI models have the knowledge. The problem is context. When an agent loads instructions for every domain it might touch, the context window fills up before the actual work starts. By the time it gets to your task, it’s already carrying the cognitive weight of a dozen things it doesn’t need right now.

The second problem is focus. An agent that might be asked to do anything develops hedging behaviors. It adds qualifications. It checks things that don’t need checking. It treats every task like it might be the one that requires careful handling, because it can’t predict which one will.

Specialists don’t have this problem. A kotlin-implementer doesn’t hedge about TypeScript. It loads Spring Boot knowledge and nothing else. A git-agent doesn’t think about test suites. It knows branches, commits, rebases, and push patterns. The specialization isn’t just about what they know — it’s about what they don’t have to consider.

The Progression

Starting point: the generalist era. One agent. It writes code, runs tests, makes commits, creates PRs, sends Slack messages. It does all of it slowly and makes generic mistakes — test commands that work on the wrong module, commit messages that describe the wrong thing, PRs with context that’s technically correct but misses the point.

First split: implementer, tester, reviewer. Three agents, each with a focused job. Better immediately. The reviewer starts catching things the implementer introduces. But they’re still too broad — the implementer works in both Kotlin and TypeScript, and it handles both with the competence of someone who sort of knows both languages.

Tech-stack specialization: the step that changed everything.

The kotlin-implementer knows Spring Boot, Maven, Kotlin idioms, our backend conventions. It doesn’t know React exists. The typescript-implementer knows Vite, React 19, Tailwind CSS, our frontend patterns. It doesn’t know what a JVM is.

The test agents split the same way. The mvn-tester knows Maven lifecycle phases, Surefire configuration, how to isolate a failing test in a multi-module build. The npm-tester knows Jest, test coverage flags, how to run a single spec file.

The quality of each agent’s work improved noticeably when it stopped having to maintain knowledge of the other tech stack in the same context window.

Pipeline agents: where the system became something qualitatively different.

A git-agent that does nothing but version control. It knows branching strategies, commit message conventions, rebase vs. merge decisions, how to handle merge conflicts cleanly. It’s not thinking about whether the code is correct — that’s already been reviewed. It’s thinking about whether the git history is clean.

A github-pr-handler that reads ticket context, matches it to code changes, writes a PR description that a human reviewer will actually find useful, and applies the right labels and reviewers. It knows PR conventions in our codebase. It’s read dozens of previous PRs in the training context.

A jenkins-handler that reads CI failure logs, diagnoses whether the failure is a flaky test, an actual regression, or an infrastructure issue, and responds appropriately — retrying flaky tests, reporting regressions, paging the on-call for infra failures.

A slack-handler that knows the channels, the tone, the audience. It doesn’t send the same message to the engineering channel and the stakeholder channel. It knows the difference between “deployed successfully” and “the PR is ready for review.”

The Final Architecture: 18 Agents

After five days:

• jira-ticket-handler — reads tickets, extracts acceptance criteria, flags ambiguity
• planning-writer — turns ticket context into an implementation plan
• kotlin-implementer — Spring Boot / Kotlin backend work
• typescript-implementer — React / Vite / TypeScript frontend work
• mvn-tester — runs Maven test suites, interprets results
• npm-tester — runs npm/pnpm test suites, interprets results
• code-reviewer — checks implementation against conventions and acceptance criteria
• code-refiner — applies reviewer feedback without rewriting everything
• git-agent — all version control operations
• github-pr-handler — PR creation, description, labeling, reviewer assignment
• jenkins-handler — CI monitoring and failure triage
• slack-handler — team notifications and status updates
• agent-optimizer — reads operational logs, identifies patterns, updates agent instructions
• feedback-recorder — captures human feedback and routes it to the optimizer
• Plus 4 domain-specific agents for our particular service ecosystem

The Design Decisions That Made It Work

AGENT.md vs CLAUDE.md separation.

Every agent has an AGENT.md file: pure tech-stack knowledge. Spring Boot patterns, Maven commands, Kotlin idioms. Nothing project-specific. And a CLAUDE.md file: project-specific context. Our conventions, our service names, our deployment setup.

This means agents are portable. The kotlin-implementer can be dropped into a different project by swapping the CLAUDE.md while keeping the AGENT.md. The tech-stack knowledge transfers. The project knowledge doesn’t bleed between projects.

The symlink setup.

All 18 agents live in a single version-controlled repository. Each agent directory is symlinked to ~/.claude/agents/ — the path where Claude Code looks for sub-agents. One source of truth, available everywhere, version-controlled like code.

When I update an agent’s instructions, it takes effect immediately across all projects that use it. No copying, no drift between copies.

The evolution cycle.

Agents log notable events during operation — unexpected behaviors, useful patterns, decisions that required clarification. A separate agent-optimizer reads these logs periodically, identifies patterns that appear 3+ times, and updates the relevant agent instructions.

The loop: agents observe → optimizer learns → agents improve. It’s not automatic — the optimizer runs on a schedule and a human reviews proposed changes. But it means the agent system gets systematically better over time, not just occasionally when I remember to update something. (The evolution of this design — and what went wrong when the memory files grew to 95KB — is covered in The Memory Bloat Crisis.)

What It Actually Cost

18 agents sounds like complexity. It is. Setting this up took five intense days of dedicated work. Most of that wasn’t writing instructions — it was learning which splits were valuable and which weren’t, finding the boundaries where specialization produces real gains versus just adding overhead.

A few splits I tried that didn’t pay off: separating read-operations from write-operations (too much handoff overhead), splitting by domain area within the backend (the agents kept needing each other’s context anyway), having a separate documentation agent (the implementer and reviewer between them handled it fine).

The splits that worked were the ones that mapped to genuinely different knowledge domains and genuinely different mental modes. Writing Spring Boot code and writing React code require different things from the context window. Reviewing code and committing code are genuinely different cognitive operations. Those boundaries are real.

If I were starting fresh: go to 4 or 5 agents first. Implementer, tester, reviewer, git, and deployment. Get those working and calibrated before adding more. The 18-agent architecture is the result of iteration, not the starting point. (See My First Autonomous Ticket for what this pipeline looked like when it first ran end-to-end.)