I woke up on October 28th staring at an agent with twenty steps organized into four phases. It worked. But something felt wrong.
By the end of the day, I’d discovered a rule that would change how I built every agent after: Maximum 10 steps per job.
The Problem with Phases
Here’s what my Coordinator agent looked like:
Phase 1: Style docblocks (5 steps)
Phase 2: Run auto-fixers (4 steps)
Phase 3: Fix remaining issues (6 steps)
Phase 4: Final verification (5 steps)
Twenty steps. Four distinct responsibilities. One agent.
I wrote in my commit message that night:
“If steps have ‘phases,’ the agent is doing too much.”
Phases are a code smell. They signal that you’re not looking at one job (you’re looking at multiple jobs masquerading as one).
Discovering the 10-Step Rule
As I refactored the monolith, I noticed something: every focused agent naturally landed around 6-8 steps. The ones that exceeded 10 were always trying to do multiple things.
Ten steps isn’t arbitrary. It’s about cognitive load.
An agent (or a human reading the instructions) can hold about 10 sequential steps in working memory. Beyond that, you need grouping, which means you need hierarchy.
The rule became:
- Maximum 10 steps per job
- If you exceed it, you’re doing multiple jobs
- Split into separate agents or manager/worker relationships
One Invocation, One Job
Here’s the subtle part: an agent can have multiple jobs it’s capable of doing, but when invoked, it should execute exactly one.
Good example:
Branch Manager Agent
Job 1: Setup New Branch
Job 2: Switch to Branch
When you call it, you specify which job. It doesn’t do both sequentially.
Bad example:
Coordinator Agent
(Always runs all 4 phases)
This distinction seems minor but it’s architectural. The first design is composable. The second is monolithic.
Explicit Over Implicit
Another pattern emerged: every action should be explicitly named.
Instead of:
3. Fix the issues
Write:
3. Use the Edit tool to fix the issues
Why? Because clarity matters when coordinating multiple agents. There’s no room for ambiguity about what is happening or who is doing it.
I started adding “wait for completion” statements:
4. Wait for the specialist to complete
5. Read the specialist's report
It sounds pedantic, but it made the coordination explicit. Step 5 depends on step 4 completing.
The Manager Pattern Emerges
As I split the twenty-step monolith, I created agents that only coordinated other agents. They didn’t do the work themselves (they orchestrated).
This was my first manager agent.
Managers have different concerns than workers:
- Managers: Decide who does what and when
- Workers: Know how to do the work
The intelligence distribution shifted. Workers became experts in their domain. Managers became experts in coordination.
Hierarchical Numbering Reflects Structure
I started numbering steps hierarchically:
3. Check for violations
3.1. Use the Check tool
3.2. If violations found:
3.2a. Route to appropriate fixer
3.2b. Wait for completion
3.3. If no violations:
3.3a. Report success
The numbering itself documents the logical structure. You can see at a glance which steps are conditional branches, which are sequential, which are nested.
What Changed
By the end of Day 2, I had:
- Split the 20-step monolith into 5 focused agents
- Established the 10-step maximum rule
- Created my first manager agent
- Made every tool use explicit
The system was more complex in terms of number of components. But each component was simpler. And that’s the paradox of good architecture.
Tomorrow: I’d start thinking about reusability and parameterization.