Maxxwell by Rindler
Writing

Keeping multiple coding agents on one plan

2026-09-19

You don’t hit the wall because agents write bad code. You hit it because three of them quietly stopped sharing the same picture of the repo.

You don’t hit the wall because agents write bad code. You hit it because three of them quietly stopped sharing the same picture of the repo.

This is a step-by-step way to keep many AI coding agents aligned on one architecture, set of constraints, and history. It’s the practical counterpart to the pillar piece AI coding agent orchestration: the complete guide for multi-agent development.

Why shared context beats one giant prompt

With more than one agent on a repo, the failure mode is drift:

Anthropic calls context a “critical but finite resource,” and OpenAI’s Agents SDK treats the session as the memory object. The pattern that works in practice is layered context:

The goal here is simple: a single source of truth that every agent sees, plus guardrails that keep edits from diverging.

Step 0 - Prerequisites and mental model

Before wiring anything, line up three assumptions:

  1. Agents are smart, low-context devs. Cursor explicitly recommends treating agents this way. They won’t remember everything unless you feed it every time.
  2. The repo is the ground truth. Architecture, invariants, and constraints live in git, not inside a prompt.
  3. Each agent session is a process with a lifecycle. It has:
    • A brief (goal).
    • A context store (what it should know).
    • A working tree (where it writes).

We’ll build shared context using four concrete mechanisms:

Step 1 - Build a repo-level context store that’s short and operational

The first mistake in multi-agent coding is dumping an essay into AGENTS.md. A 2026 study found that long AGENTS.md-style files didn’t improve task success, while inference cost went up more than 20% on average. So keep the repo context store tight.

Create AGENTS.md or CLAUDE.md in your repo root:

touch AGENTS.md

Structure it as instructions, not prose:

# Agents instructions for this repo

## Architecture overview
- Service is split into `api`, `worker`, `frontend`.
- `api` is the only layer that talks to the database.

## Non-negotiable constraints
- No direct DB access from `frontend` or `worker`.
- All external calls go through `infra/http_client.ts`.
- Feature flags defined in `config/flags.yml` must gate new behavior.

## Coding standards
- Tests in same package/module as implementation.
- Use existing logging helper; do not introduce new logger.

## How to add a feature
1. Update or add a feature flag.
2. Add API surface.
3. Add worker job if needed.
4. Add frontend wiring.
5. Add tests for all layers.

Then wire it into your agents:

The constraint is: keep it under ~1-2k tokens. Everything else goes into normal documentation.

Step 2 - Use design-constraint and documentation agents as gatekeepers, not authors

Documentation agents help keep architecture and constraints stable. But they shouldn’t be editing code in the hot path. Their job is to answer “what should we do?” and “does this fit?” for other agents.

Set up two kinds of supporting agents:

  1. Design-constraint agent
    • Input: a patch or plan from a coding agent.
    • Output: a verdict against constraints in AGENTS.md, plus corrections.
  1. Documentation agent
    • Input: the change that actually merged.
    • Output: updates to AGENTS.md, design docs, and usage docs.

For example, a design-constraint check using OpenAI’s SDK:

system = """
You are the design-constraint reviewer for this repo.
You enforce the rules in AGENTS.md and architectural docs.
For the proposed change, respond with:
- PASS or FAIL
- Specific constraints violated
- Concrete edits required to comply
"""

user = """
Here is AGENTS.md:

{agents_md_contents}

Here is the diff:

{git_diff}
"""

# Call model with system + user and parse its PASS/FAIL.

Wire this into your pipeline:

The coding agent doesn’t get to rewrite invariants without going through these seats.

Step 3 - Isolate agent working trees to prevent divergent writes

The cleanest way to avoid agents trampling each other is to give each one its own working tree. Git worktrees exist for exactly this use case. CommandSlate and ctx both call out that sharing a working tree across agents causes conflicts.

Create isolated worktrees:

# From the main repo
mkdir -p /tmp/agent-worktrees

# One worktree per agent session
git worktree add /tmp/agent-api-fix feature/agent-api-fix
git worktree add /tmp/agent-refactor worker/refactor-queues

Run each agent inside its own path:

# Agent 1 terminal
cd /tmp/agent-api-fix
agent-run --goal "Add rate limiting to API" --context ../AGENTS.md

# Agent 2 terminal
cd /tmp/agent-refactor
agent-run --goal "Refactor worker queue handling" --context ../AGENTS.md

Rules for isolation:

This doesn’t just avoid merge hell. It keeps each agent’s session memory decoupled and easier to reason about.

Step 4 - Treat agent session memory as a bounded context and trim it

OpenAI’s Agents SDK frames the session as the memory object. Anthropic’s context-engineering guidance says windows are finite, and recommends trimming and compression. If you run agents for hours, you need to curate what they remember.

Practical pattern:

Example: basic trimming of a text log before sending it back to the agent:

def compress_session_log(events, max_tokens=1500):
    """Keep decisions, discard noise."""
    important = []
    for e in events:
        if e["type"] in {"decision", "architecture", "constraint"}:
            important.append(e["text"])
    # Naive truncation; you can swap in token-based truncation.
    return "\n".join(important)[-max_tokens:]

Feed this compressed memory into the next turn instead of the full transcript. You keep the context that matters - what the agent decided and why - and drop the rest.

If you’re using OpenAI prompt caching, keep your fleet-level instructions stable. Any change in tools or system text invalidates the cache.

Step 5 - Use a session management dashboard to see alignment, not just output

The DORA 2025 report says ~90% of devs use AI, more than 80% see productivity gains, but 30% still report little to no trust in AI-generated code. The missing piece is often visibility: knowing what each agent is doing so you can judge whether it’s still aligned.

A practical dashboard - whether you script it in tmux or run a tool - should give you:

A minimal homegrown view:

# Example layout: scripts + tmux

# List sessions and branches
ls /tmp/agent-worktrees

# Inspect last decisions for one session
cat /tmp/agent-api-fix/.agent/log.decisions

Maxxwell is essentially this, built out:

That last property matters for trust. You get the coordination benefits without letting an orchestrator silently rewrite your repo.

If you’re evaluating orchestration tools like The Cog, Helmor, CommandSlate, or ctx, look for:

Step 6 - Install checks in the merge path to catch divergence

The safest place to detect drift is at merge time. Whatever your orchestration stack, add automated checks between “agent wrote code” and “code landed on main.”

Concretely:

  1. Run tests and static analysis in CI.
    • AI helps throughput but can increase instability; DORA calls this out.
  2. Constraint review via the design-constraint agent.
  3. Architecture diff review: flag files or modules whose shape changed.

A simple guard that catches direct DB access from the wrong layer:

# In CI, fail if frontend touches DB client
grep -R "db_client" frontend/ && {
  echo "Frontend may not use db_client directly" >&2
  exit 1
}

Then add a job that calls your design-constraint agent for any non-trivial diff. You’re not trusting the agent blindly; you’re routing its changes through a documented set of checks.

Step 7 - Keep shared context version-controlled and auditable

The final piece is making shared context first-class infra. Cursor already treats rules as persistent reusable context, and Anthropic’s skills guidance pushes progressive disclosure of instructions. Do the same for your repo.

Treat these files and artifacts as code:

Version them, review them, and change them with intent. Context engineering is now part of your architecture work.

FAQ

How do I keep multiple AI coding agents aligned on one codebase?

Use layered context:

This gives all agents the same constraints and architecture without blowing up their context windows.

What is a context store for multi-agent coding?

A context store is the durable set of instructions, constraints, and patterns that every agent reads before or during a run. In practice it’s:

It acts as the single source of truth for architecture and design constraints.

How do I prevent divergent code changes between agents?

You prevent divergence by combining isolation and review:

This stops agents from silently rewriting shared modules in incompatible ways.

What does a documentation agent actually do in this setup?

A documentation agent:

It doesn’t own the merge; it keeps the human-readable context in sync with what agents and humans actually shipped.

Why use a manager like Maxxwell instead of DIY tmux scripts?

Tmux scripts give you multiplexed terminals but little shared state. A manager like Maxxwell:

If you’re already running multiple agents and feel like the bottleneck is your own attention, that extra layer of orchestration is what keeps the fleet legible without ceding control.