Multi-Agent Setup
The simplest multi-agent setup is:
- Put shared instructions in a root
AGENTS.md. - Add agent-specific companion files only when a tool benefits from them.
- Avoid copying the same rule into three places.
A Good Split
Section titled “A Good Split”AGENTS.md
- shared commands
- coding standards
- test expectations
- verification requirements
CLAUDE.md
- Claude-specific memory or workflow details
GEMINI.md
- Gemini-specific configuration notes if needed
Avoid Drift
Section titled “Avoid Drift”The main risk in a multi-agent repo is divergence. If one file says “run pnpm verify” and another says “run npm test,” the agent choice starts changing the workflow.
Use one shared source for durable project rules and keep the companion files thin.
Nested Context
Section titled “Nested Context”If a monorepo or subproject needs its own instructions, add a nested context file near that part of the codebase. Make sure the nested file only contains local differences, not a rewritten copy of the whole root guide.