DEV Community: João Camarate

Keeping context and decisions consistent across parallel AI agents

João Camarate — Wed, 08 Jul 2026 12:32:19 +0000

You start the morning with four Claude Code agents running, each in its own git worktree, each on a separate task. By mid-afternoon something is off. One agent has re-implemented a helper another already wrote. A second built against an interface that a third changed an hour ago. A fourth made a naming choice that contradicts a decision you made — out loud, to yourself — at 9am. Every diff is reasonable on its own. The system they add up to is not.

This is the failure mode that shows up the moment you go from one agent to several. The code each agent produces is fine. What drifts is everything between the agents: the decisions, the conventions, the current shape of the interfaces they all depend on. Running the agents in parallel is the easy part. Keeping them coherent is the hard part, and it's a different problem.

Why parallel agents drift

An agent's context is per-session. Each Claude Code instance has its own context window, populated by what it has read and done in that session. Nothing about that window is shared with the agent running in the next worktree. There is no common memory they all write to and read from. So when agent A decides "we use the repository pattern for data access," that decision exists in exactly two places: agent A's context, and your head. Agent B never hears about it.

Three kinds of state cause the drift, and they're worth separating because they need different handling:

Decisions already made. Architecture, naming, conventions, the approach you settled on for a cross-cutting concern. These are durable — once made, they should bind every agent, including ones you spawn tomorrow.
The current contract. The shape of the interfaces, types, and APIs that agents share. This changes during the work: agent A edits a signature, and agents B and C are now building against a version that no longer exists.
What's in flight. Who is touching which files right now. Two agents editing the same module in separate worktrees won't see each other until the merge, where the conflict surfaces as a surprise.

Single-agent work hides all three, because one session holds the whole picture. Parallelism is what exposes them.

The bottleneck isn't the model's context window. It's yours.

The instinctive fix is to be the shared memory yourself — hold the decisions in your head and hand-feed them to each agent. That works at two agents. It breaks at four or five, because you become the integration layer: the only place the parallel streams reconcile is your working memory, and your working memory does not scale with agent count. You spend the day re-briefing, catching contradictions, and re-litigating decisions an agent has quietly forgotten. Throughput went up; your cognitive load went up faster. (We wrote about that tradeoff in more depth in the cognitive load of running parallel Claude Code agents.)

So the real question isn't "how do I run more agents." It's "how do the decisions get made once and then bind every agent, without routing through me each time."

The ways teams handle it today

There's a spectrum of approaches, each with a real tradeoff. Most people running parallel agents use some mix.

Context files (CLAUDE.md and friends)

Put conventions and decisions in a file every agent reads on startup. This is the right baseline and you should do it. The limit is that it's static: it captures decisions you can write down in advance, not the ones you make mid-stream, and it goes stale the moment the work moves past it. It binds the durable layer, not the in-flight one.

Copy-paste briefs

Hand each agent a tailored brief at spawn time. Flexible and precise, but it puts you back in the loop for every task, and it only carries what you remembered to include. This is the approach that makes you the bottleneck.

A shared task queue

Tools like Beads, or a kanban of tasks each in its own worktree, give agents a common backlog and a record of what's done. This handles "what's in flight" well — agents can see the work surface. It does less for "decisions already made," which still live outside the queue unless you write them into each task.

Plan first, then fan out

Spend an hour up front — non-agentic — resolving the design and the interfaces before any agent starts. One practitioner described it as conducting an ensemble: the score is set before the musicians play. This is the highest-leverage habit on the list, because most drift comes from decomposing into parallel tasks before the shared decisions are settled. The catch is that it only covers what you can foresee; anything decided after the fan-out still needs somewhere to live.

The pattern underneath all four: the durable decisions need a shared home that every agent reads from and writes to, and the interfaces need to be settled before the work is split, not renegotiated inside five worktrees at once. Tooling helps to the degree it enforces those two things rather than leaving them to your memory.

compound engineering is the only AI coding idea that actually compounds

João Camarate — Thu, 02 Jul 2026 17:29:00 +0000

I've been building software with AI agents every day for months. The biggest thing I've learned has nothing to do with which model or which tool is hot this week. Its this: most people's AI output is flat. Every task starts from zero. The agent is just as sharp and just as forgetful as it was last week.

Kieran Klaassen and Dan Shipper at Every gave this problem a name - compound engineering. The idea is almost stupidly simple: each piece of work should make the next one easier, not harder. They run several products with basically single-person eng teams on the back of it. Once you feel the difference its really hard to go back.

It's usually drawn as a four step loop. Plan, work, assess, compound.

Plan - before a line of code, the agents go read the codebase, the conventions, the framework versions, and hand you a plan you correct.
Work - the plan drives the build. The agent writes the feature and the tests.
Assess - review agents check it. Correctness, security, architecture.
Compound - whatever you learned this time gets captured into durable rules and docs the system actually reads next time.

Everyone does the first three. Almost nobody does the fourth.

And the fourth is the whole point. Its the only step that actually compounds. Skip it and you dont have compound engineering - you have a very fast autocomplete with extra steps.

Every ships this as an open source claude code plugin, a set of /ce: commands that scaffold the plan, run the work, run the review. Genuinely good on-ramp. If you live in the terminal go grab it.

But the plugin isnt the loop. The loop is a discipline. The hard part was never typing /ce:plan - its doing the compound step honestly, every single time, when youre tired and the feature already works and you just want to merge and go to bed. Thats exactly where it dies.

I ran this by hand for a while and the same leaks show up every time.

The compound step is optional, so it doesnt happen. Writing down what you learned is boring and nothing breaks when you skip it. So you skip it. And the system quietly stops compounding.

Your memory is scattered. Lessons end up as random edits to a CLAUDE.md that slowly turns into a swamp, or worse, they live in your head. No record of why a decision got made, or that you corrected the agent on this exact thing last week.

Nothing is gated. The loop is a convention, not a wall. The second youre moving fast, work jumps from plan straight to merge and assess + compound fall off the back of the truck.

The deeper version of this - how decisions and context drift across a pile of parallel agents - is its own rabbit hole. I went into that one separately.

So heres the only question I actually care about now, every time I wire up an agent loop: a month from now, will this system be better at building my product than it is today? Or just as fluent, and just as forgetful?

If theres no compound step, you already know the answer.

Build the fourth step. Thats the whole game 🙌

Why 20 Claude Code instances break down (and what to do)

João Camarate — Fri, 26 Jun 2026 11:39:04 +0000

The instinct makes sense. You're running three or four parallel Claude Code agents and the throughput is noticeably higher than sequential work. So you push further — to eight, to twelve, to twenty. If a few agents are good, more must be better.

What people find instead is that the gains flatten and then reverse. Not just "more overhead" — the failure mode at 20 agents is qualitatively different from the failure mode at 5. New things break that didn't break before, and they break in ways that aren't immediately obvious.

This is a breakdown of what those failure modes actually are, because naming them clearly is the prerequisite for avoiding them.

the failure modes that appear at scale

1. API throughput becomes the bottleneck

Five agents hitting the Anthropic API simultaneously is fine. Twenty agents, each running long-context tasks, can saturate your per-minute token limits — especially during the heavy context-loading phases at the start of each session. When that happens, agents stall, you get rate-limit errors mid-task, and the "parallel" run becomes a staggered one you didn't plan for.

This is fixable with backoff logic or scheduling agents to start in waves, but it's work that has nothing to do with software development, and it now falls on you.

2. machine resources cap out before you expect

Each Claude Code agent is a PTY session running a full claude process. On a well-specced MacBook Pro, three to five is comfortable. Ten starts to feel it. Twenty is a memory and CPU problem — you're running what amounts to twenty active terminal sessions plus whatever those sessions are reading and writing. The machine slows down, context-switching becomes sluggish, and the environment itself becomes a source of noise.

If you're not watching system resources while running at high agent counts, you're probably already past the point where the host is hurting the runs.

3. task decomposition becomes intractable

Decomposing a feature into five truly independent tasks is hard. Decomposing it into twenty is harder by a factor that's not linear. The dependencies between tasks multiply; the interfaces that tasks need to share get finer-grained; the risk of two agents working on the same module in different directions grows with each additional task you carve out.

Most people who try to run twenty agents simultaneously don't actually decompose correctly for twenty tasks. They decompose for five and hand the rest under-specified work. Those agents then make assumptions — about the interface shape, about the conventions, about what the other agents are doing — and those assumptions collide at merge time.

4. supervision collapses

At three to five agents, you can maintain a working mental model of what each one is doing. You check in periodically, catch the drift when it starts, redirect before it compounds. The supervision is real, even if it's imperfect.

At twenty agents, this breaks. You don't know what most of them are doing. Errors propagate for a long time before you see them because your attention is too distributed to catch them early. An agent that's been building against a stale assumption for 30 minutes has produced a lot of output before you notice, and all of that output needs to be re-evaluated or discarded.

the typical twenty-agent session: you're watching two or three closely, dimly aware of the rest. the ones you're not watching are making decisions. some of those decisions are wrong, and you'll find out when you try to merge.

5. context cascade failures multiply

Each agent's context window is per-session — it holds what that agent has read and done, nothing from the other agents running in parallel. When you're running five agents and you make a decision that affects all of them, you can re-brief all five in a few minutes. When you're running twenty, re-briefing twenty agents is a significant chunk of time, and if you don't do it completely you have a mixed state: some agents operating on the new decision, some on the old one, and you don't know which is which.

We wrote about this in detail in keeping context and decisions consistent across parallel AI agents — the short version is that the problem isn't solvable just by adding more agents. The context coherence requirement grows linearly with agent count, and the cost of maintaining it falls entirely on you.

6. the git merge ceremony becomes a project of its own

Worktrees give each agent an isolated environment. That's correct — without them you'd have file conflicts immediately. But isolation defers the merge, it doesn't eliminate it. Twenty worktrees means twenty branches with diverging state, some of which will have touched the same files from different angles, and all of which need to be sequenced back into a coherent main branch.

Merging twenty branches isn't twenty times as hard as merging one branch. It's harder than that, because the interactions between branches accumulate. If you've run twenty agents on a feature for an afternoon, you may spend the next morning just doing the merge work — and the cognitive load of holding twenty changesets in your head simultaneously while resolving conflicts is substantial.

the diagnostic question

Before pushing to higher agent counts, one question cuts through the intuition:

Of your N agents, how many are actually making progress versus waiting on you?

If three of your five agents are blocked waiting for your review, your re-brief, or your arbitration of a conflict — running five agents is providing the throughput of two. Adding more agents doesn't fix this. It adds more agents waiting in the queue.

The throughput ceiling in most parallel-agent setups isn't the number of agents. It's the rate at which one human can review output, make decisions, and maintain shared context. Adding agents past that ceiling produces waiting agents and deferred work, not faster delivery.

a practical ceiling: most engineers who run parallel Claude Code agents seriously land at 3–5 as the stable operating range. not because more agents can't produce output, but because more agents can't be supervised effectively by one person. the number that feels chaotic is usually a signal that the human bottleneck has been exceeded, not that the agents are broken.

what to do instead

fewer, better-structured agents

The return on running more agents diminishes well before 20. The return on running fewer agents more carefully is higher than it looks. Three agents with clear, complete task briefs, well-separated concerns, and one human who can actually supervise all three will routinely outperform ten agents with overlapping work and a supervision gap.

The question is not "how many agents can I spawn?" It's "what's the maximum number I can supervise well?" For most people working alone on a codebase, that's somewhere between three and six.

lock the design before you fan out

The biggest cause of agent conflicts at scale is premature decomposition — breaking work into parallel tasks before the interface decisions are settled. An agent that starts building the data layer before the API contract is fixed will produce work that needs to be re-done the moment the contract is resolved.

The pattern that works: resolve the design and the key interface decisions non-agentic, or with one dedicated planning agent, before any implementation agent starts. Decompose into parallel tasks against a fixed specification, not a live one. The upfront time pays back multiple times in avoided merge conflicts and re-work. (This is what a structured pipeline enforces by construction.)

automated review before it reaches you

If you're reviewing all agent output yourself, you're a single-threaded bottleneck in what's supposed to be a parallel system. Some of that review can be done by agents: type checks, test runs, lint, security scan, architecture review against the specification. These can run automatically when an agent finishes, before the output reaches your queue.

What remains for you to review is higher-signal: intent alignment, design judgment, the things that require your context about the product. Everything mechanical is pre-filtered. The queue you're looking at is shorter and more meaningful.

shared context, not parallel re-briefing

Every decision you make in a parallel-agent session that needs to reach multiple agents requires either you re-briefing each one (which doesn't scale) or a shared source that agents read from. CLAUDE.md handles the static layer — conventions, architecture, the things set before you start. The dynamic layer — decisions made mid-session, current interface shape, what other agents are doing — needs somewhere else to live.

Without it, you're the only mechanism for propagating mid-session decisions to all agents, and that breaks at agent counts above five or six.

what is spec-driven development? (with ai coding agents)

João Camarate — Fri, 19 Jun 2026 16:20:08 +0000

Most AI coding workflows start the same way - you open the agent, describe what you want in a sentence or two, and watch it write code. It feels fast. Then the diff comes back and it built the wrong thing, or the right thing the wrong way, and you spend the next hour correcting it through follow-up prompts. The agent was never confused about how to write the code. It was confused about what you actually wanted.

spec-driven development is a direct response to that failure mode. Instead of prompting an agent straight to code, you first produce a spec - a written description of the requirements, the design, and the tasks - and you correct that spec until it is right. Only then does the spec drive implementation. The decision about what to build happens once, explicitly, on paper, before any code exists.

what spec-driven development actually means

The term has become popular through tools like AWS Kiro, which put "specs" directly in the IDE, and GitHub's spec-kit, which brings the same idea to Copilot, Claude Code, and other agents. But the idea is older than any of these tools - writing down what a system should do before building it is just engineering, and the AI tooling is a new wrapper around an old discipline.

The shared shape across the tools is a three-part artifact, usually written as plain markdown:

requirements - what the feature does, who uses it, what success looks like, and the acceptance criteria. This is behavior, not implementation. No stack, no file names.
design - the technical plan that satisfies those requirements. Architecture, data models, the interfaces involved, the constraints and standards the code has to respect.
tasks - the design broken into small, reviewable, testable units. Each one is concrete enough to hand to an agent and check on its own, like "add a registration endpoint that validates email format and rejects duplicates."

Each part feeds the next. Requirements constrain the design, the design decomposes into tasks, and the tasks are what the agent implements. The human reviews and corrects at each step, so by the time code generation starts, the agent is working from a document you have already agreed with rather than guessing at thousands of unstated details from a one-line prompt.

why this matters now

For most of software's history, the expensive, slow part was writing the code. Specs felt like overhead because the typing was the bottleneck and you could just refactor your way out of a misunderstanding. That economics has changed. When an agent can produce a feature's worth of code in minutes, writing the code is no longer the constraint. The bottleneck moved to deciding precisely what to build.

A spec is how you make that decision once, in a form both you and the agent can read. Vague intent forces the model to fill in gaps, and it fills them with plausible guesses that you only discover are wrong after the code is written. A spec moves the guessing forward, into a cheap document, where a wrong assumption costs a sentence to fix instead of a sprint to unwind.

The point of a spec is not documentation. It is to surface the disagreement between what you meant and what the agent understood while that disagreement is still one paragraph instead of two thousand lines.

where it helps

you review intent, not diffs

Reviewing a large diff is reverse-engineering - you read the code and try to reconstruct what the author intended, then judge whether that intent was correct. A spec inverts the order. You agree on the intent first, in language, then the implementation is checked against an intent you already approved. Reading "validate email format and reject duplicates" and deciding it is right takes seconds. Reading the endpoint, the validation, and the database query to infer the same thing takes much longer and you can still miss the gap.

you catch the wrong build before you pay for it

The most expensive mistake in AI-assisted work is building the wrong thing well. A spec is the cheapest place to catch it. If the requirements say the feature should do X and you wanted Y, you find out before a single task runs, not after the agent has produced a polished, tested, completely misaimed implementation.

you can parallelize honestly

Once a design is decomposed into discrete tasks with clear boundaries, you can fan multiple agents out across them without them colliding or duplicating work. The spec is the shared contract that keeps independent work coherent. Without it, parallel agents each invent their own interpretation of the same vague goal and you spend the saved time reconciling them.

the honest limits

spec-driven development is not free and it is not always worth it. The discipline carries real costs, and being fair about them is the only way to use it well.

It is overkill for small work. A one-line fix, a copy change, a rename - writing a requirements-design-tasks document for these is slower than just doing them, and pretending otherwise is how a good practice turns into busywork. The size of the spec should match the size and risk of the change, and for trivial work that means no spec at all.

Specs go stale. A spec is only the source of truth if it is maintained. The moment the code drifts from the document and nobody updates the document, the spec becomes a confident, out-of-date lie - worse than no spec, because people trust it. This is the failure that sank earlier model-driven approaches, and it has not gone away.

And agents do not always obey. A larger context window and a detailed spec do not guarantee the model follows every line. Specs reduce ambiguity, they do not eliminate the need to review the output. Some practitioners also find verbose markdown specs tedious to review in their own right, which is a real tradeoff rather than a solved problem. Treat the spec as a tool for making intent explicit, not as a contract the model is forced to honor.