I added Gemini to a codebase where Claude had been shipping code for months. The repository had a CLAUDE.md file defining conventions, commit patterns, and project context. The question: would a second AI agent create chaos or unlock something new?
The useful discovery had nothing to do with model capabilities. It was about shared context files.
The Insight
AI agents do not need to share a brain to share a project. They need shared context, and that context must be explicit. My CLAUDE.md and GEMINI.md files define project conventions, preferred patterns, and accumulated knowledge. Each agent reads these files, contributes to the codebase, and leaves artifacts the other can learn from.
The implication is measurable: two mediocre models with excellent shared context outperform two frontier models with no shared context. The quality of a multi-agent setup is almost entirely determined by the quality of the context files.
What Context Actually Matters
"Use TypeScript" and "follow standard formatting" are useless context. What matters is project-specific knowledge that takes humans weeks to absorb:
Architectural decisions with reasoning. Not "we use Express" but "we use Express because we need streaming responses for the AI pipeline and Hono didn't support that at the time."
Known failure modes. "The Vercel build fails silently if you import from the scripts directory. Keep those imports server-side only."
Domain vocabulary. What terms mean in this specific project, not their general definitions.
Without this, every AI interaction starts from zero.
The Trade-offs
Context files go stale. If you do not update CLAUDE.md after architectural changes, the AI will confidently follow outdated conventions. I have had Claude revert a deliberate refactor because the context file still described the old pattern.
Models interpret the same context differently. Claude follows context files literally. Gemini treats them as suggestions. You end up writing context that works for both, which means being more explicit than you would like.
Maintenance is real. Every significant change requires updating context files. This is useful documentation discipline, but it is not free.
Auditing degrades. When two agents commit to the same branch, git blame tells you which agent but not which context led to the decision.
When It Helps
Multi-agent setups help when you have complementary tasks: one agent generates code, another reviews it. Claude gives better architectural feedback. Gemini iterates faster on implementation.
They do not help when you parallelize the same type of work. Two agents writing code simultaneously on the same files creates merge conflicts and inconsistency.
The setup is worth the overhead for projects with clear generation/validation separation. For everything else, one well-configured agent is simpler and more consistent.