Parallel Agents in a Shared Repository. Rethinking AI-Assisted Development Through Context Architecture
For a while, most AI-assisted development workflows looked deceptively straightforward.
You opened a chat window, pasted a problem, waited for code generation, copied the output into your editor, and repeated the process. As long as the project remained small, the workflow felt almost magical. A landing page could be scaffolded in minutes. APIs appeared instantly. Boilerplate disappeared. Even moderately complex integrations suddenly felt manageable.
But somewhere between the second authentication flow and the fifth backend refactor, the workflow started slowing down in ways that were difficult to describe precisely.
The issue was not model intelligence. The models were often producing excellent code. The issue was context accumulation.
Every new feature required retransmitting prior decisions. The frontend depended on backend assumptions. The database schema influenced billing logic. Middleware affected route structure. Deployment constraints shaped environment handling. Gradually, development stopped feeling like writing software and started feeling like manually reconstructing memory for a stateless system over and over again.
The prompts became longer than the actual implementation tasks.
At some point, I realized that the problem was not prompting quality. It was architecture.
That realization came after watching a YouTube video where the creator built a B2B micro-SaaS using multiple AI agents running simultaneously. On the surface, the video looked similar to many AI coding demonstrations online. The creator built a SaaS product that generated AI lead magnets, integrated authentication, connected Stripe billing, and deployed through Vercel.
But underneath the product demo was something much more interesting.
The workflow itself was engineered like a distributed system.
Instead of feeding the entire project into one gigantic conversational thread, the creator divided the system into structured documents. There was a master PRD, an architecture contract, module-specific requirement documents, and isolated implementation contexts for different AI agents.
The more I thought about it, the more it resembled how actual engineering organizations function.
Frontend teams do not continuously load the entire backend codebase into memory while implementing UI interactions. Infrastructure engineers do not reread onboarding copy before configuring databases. Real systems scale through bounded contexts and carefully maintained interfaces.
Most AI workflows completely ignore this principle.
They flatten everything into one giant context window and hope the model can continuously reconcile all architectural assumptions simultaneously.
The workflow from that video approached the problem differently.
And after adapting it into my own development environment, it became obvious that this was less about prompt engineering and more about information architecture.
The Planning Phase Became More Important Than the Coding Phase
The biggest shift was realizing that parallel agents fail very quickly without explicit ownership boundaries.
If multiple models operate against the same repository without coordination, they start overwriting assumptions rather than collaborating. One agent changes response shapes while another still consumes outdated contracts. Frontend components begin depending on backend behavior that no longer exists. Infrastructure assumptions drift silently across sessions.
The failure mode resembles distributed systems without interface contracts.
So before writing code, I started building a planning layer inside the repository itself.
The workflow usually started with a single prompt whose only job was decomposition.
Analyze this application idea and divide it into:
1. Global architecture
2. Backend ownership
3. Frontend ownership
4. Shared contracts
5. Infrastructure setup
6. Flow dependencies
Generate separate markdown documents for each area.
The goal is parallel AI execution with minimal context overlap.
That prompt alone changed the development flow significantly.
Instead of generating implementation immediately, the models first generated coordination structure.
The repository started evolving into something like this:
ai-docs/
├── GLOBAL_CONTEXT.md
├── AGENT_BACKEND_API.md
├── AGENT_FRONTEND_UI.md
├── AGENT_CONTRACTS.md
├── AGENT_INFRA_SETUP.md
└── FLOW.md
Or in larger projects:
docs/
├── 01-prd.md
├── 02-architecture.md
├── 03-frontend-modules.md
├── 04-backend-modules.md
├── 05-youtube-backend.md
├── 06-instagram-backend.md
├── 07-pinterest-backend.md
└── 08-frontend-anime-poster.md
At first, this looked like over-documentation.
Eventually, it became obvious that these markdown files were not documentation in the traditional sense.
They were coordination primitives.
The numbering itself turned out to matter. It created deterministic reading order for agents. Without it, different models occasionally inherited architectural assumptions in inconsistent sequences.
Once context becomes infrastructure, ordering itself starts becoming important.
The Repository Became Shared Runtime Memory
The most important file was usually the global context document.
Not because it contained implementation details, but because it established worldview consistency across agents.
A simplified version looked something like this:
# Product Scope
- Secure notes
- One-time secrets
- Encrypted notepad
- AI formatter utility
# Architecture
- Frontend: Next.js
- Backend: Hono Worker
- DB: Cloudflare D1
# Trust Model
- Encryption/decryption is client-side
- Server stores only encrypted payloads
- Passwords are never persisted
This document intentionally stayed high level.
The goal was not to explain everything.
The goal was to ensure every agent inherited the same architectural assumptions before touching implementation details.
After that came isolation.
Backend logic moved into backend-specific markdown files.
Frontend rendering behavior moved into frontend files.
Infrastructure setup remained isolated.
Contracts received their own ownership layer.
The repository stopped functioning like static source code.
It started functioning more like shared runtime memory for reasoning systems.
Running Multiple Agents in Parallel
Once the repository had persistent context layers, I stopped using AI models sequentially.
Instead, I started assigning scoped ownership to different systems.
OpenAI Codex (Github Copilot) handled implementation-heavy repository work because it interacted efficiently with the codebase itself and consumed relatively fewer tokens during iterative modifications.
Anthropic Claude Opus 4.6 (Antigravity) became primarily responsible for backend architecture reasoning, database logic, API consistency, and implementation planning.
Google Gemini (Antigravity) focused mostly on frontend workflows, UI coordination, component generation, and rendering behavior.
The important part was contextual isolation.
Claude did not receive frontend implementation context.
Gemini did not receive deep infrastructure discussions.
Codex operated largely against localized implementation files.
Every model usually received only:
- The global context document.
- Its module-specific markdown file.
- The contracts document.
- The flow document if orchestration logic mattered.
That changed the prompts completely.
Instead of giant prompts trying to carry the entire repository state, prompts became lightweight execution instructions.
For backend work:
You are responsible only for backend implementation.
Read:
- GLOBAL_CONTEXT.md
- AGENT_BACKEND_API.md
- AGENT_CONTRACTS.md
- FLOW.md
Constraints:
- Do not modify frontend concerns
- Preserve contract compatibility
- Avoid introducing new response shapes
For frontend work:
You are responsible only for frontend implementation.
Read:
- GLOBAL_CONTEXT.md
- AGENT_FRONTEND_UI.md
- AGENT_CONTRACTS.md
Constraints:
- Consume backend contracts as source of truth
- Do not access database logic directly
- Avoid undocumented backend assumptions
The prompts themselves became shorter because the architecture had moved into persistent repository context.
That distinction matters much more than most prompt engineering discussions acknowledge.
The Flow Document Became the Orchestrator
One surprisingly effective addition was the FLOW.md file.
Initially, I created it simply to keep track of execution order between services. Over time, it became the central coordination layer between agents.
A simplified version looked something like this:
# User Flow
1. User signs up through onboarding.
2. Frontend calls auth endpoint.
3. Backend creates account.
4. Billing middleware checks subscription state.
5. Webhook updates metadata.
6. Dashboard unlocks generation quota.
7. Generation engine processes request.
8. Result stored and returned.
This reduced coordination failures dramatically.
Without it, frontend agents occasionally assumed backend states that had not been implemented yet. Or generation systems expected metadata fields that authentication middleware never created.
The flow document acted like shared execution memory between otherwise isolated reasoning systems.
That was when the workflow stopped feeling like chatting with AI models and started feeling more like orchestrating distributed services.
Why Large Context Windows Often Make Things Worse
There is a widespread assumption that larger context windows automatically solve software coordination problems.
In practice, large contexts often create a different kind of instability.
As contexts grow, the model has to continuously determine:
- Which assumptions are still valid.
- Which architectural decisions supersede earlier ones.
- Which details are relevant to the current task.
- Which implementation artifacts are outdated.
Eventually, the prompt resembles a system dump rather than a focused engineering instruction.
Humans do not work this way.
A backend engineer does not continuously keep the entire frontend rendering pipeline mentally active while implementing queue retries. Real engineering systems scale because cognition is partitioned.
Most AI workflows currently ignore this entirely.
The result is similar to forcing every service in a distributed system to reload the entire database for every request.
Technically possible.
Operationally inefficient.
Once contexts became modular, the models started behaving more predictably because information locality improved.
The frontend agent reasoned about frontend concerns.
The backend agent reasoned about backend concerns.
The implementation agent focused on repository modifications.
The architecture itself reduced cognitive noise.
Documentation Stopped Being Passive
Traditional engineering documentation tends to decay because it is rarely operationally enforced. But once AI systems begin depending on documentation continuously, stale markdown files immediately produce degraded outputs.
If backend contracts change but the contracts document remains outdated, frontend agents generate incorrect assumptions. If trust-model rules evolve but the global context file is stale, implementation drift begins appearing across sessions.
The markdown files stop being explanatory material.
They become runtime coordination infrastructure.
This creates a surprisingly strong incentive to maintain clean documentation because documentation quality directly affects implementation quality.
The repository starts evolving into something larger than source code.
It becomes a cognitive workspace designed for both humans and reasoning systems operating simultaneously. That may ultimately become one of the defining architectural shifts of AI-assisted development.
The future probably does not belong to one infinitely large coding agent operating against massive conversational memory. It likely belongs to multiple reasoning systems operating inside carefully designed contextual boundaries.
The most important realization from running agents in parallel inside a shared repository was surprisingly simple. The models themselves did not fundamentally change.
The environment around them became better architected.
Parallel Agents in a Shared Repository. was originally published in Towards AI on Medium, where people are continuing the conversation by highlighting and responding to this story.