Running Two AI Code Agents in One Codebase 🦆 ⇄ 🦆

I didn’t set out to build “multi-agent infrastructure.”

I just wanted Claude and Codex to coexist without stepping on each other.

That turned into something more deliberate.

The Core Constraint

Two agents.
One repository.
Zero ambiguity about who is responsible for what.

If you let both read and write freely without guardrails, you get drift.

Different assumptions.
Different commit styles.
Different workflow interpretations.

Eventually, you get a mess.

So the first rule was simple:

Each agent gets its own primary instruction file.

• Claude reads CLAUDE.md

• Codex reads AGENTS.md

Generally, they contain the same shared rules, but each agent treats its own file as canonical.

That small separation reduces a surprising amount of confusion.

Preventing Instruction Drift

Parallel files introduce a new problem: sync.

So I added a classification rule: If a rule that we're adding/modifying is agent-specific, then we update only that agent’s file.  If it's a rule that should apply across all agents, we update both files. If something is intentionally asymmetric, both files explicitly say so.

No silent divergence or “oh I forgot to copy that section over.”

It’s boring discipline, but boring discipline scales.

Traceability Matters More Than You Think

Both agents follow the same commit conventions:

• Conventional Commits
• gitmoji
• Structured ticket references

The only difference is the suffix applied to all commits and jira comments:[ai][claude]or[ai][codex]

That tiny tag changes everything.

When something breaks, I don’t have to try to guess (or remember) which agent did what. When something works unusually well, I can see patterns.

What This Really Is

The lesson here isn't even really about AI.  It’s about acknowledging that once you have multiple contributors, especially those that need extra oversight — human or not — you need:

• Clear ownership boundaries

• Explicit synchronization rules
• Observable output markers
• Shared validation standards

Otherwise you don’t have collaboration, you have entropy... and entropy is subtle at first, but ultimately becomes expensive.