Repository Layout & Setup

Recommended Repository Layout

your-repo/
├── AGENTS.md                   # canonical, cross-tool: conventions, commands, guardrails
├── CLAUDE.md                   # Claude-Code-only additions (compaction guidance, subagent routing)
├── GEMINI.md                   # Antigravity-only overrides (kept thin)
├── .codex/agents/               # Codex subagent definitions (model/sandbox per role)
├── .antigravity/agents/          # Antigravity subagent YAML definitions
├── .claude/skills/               # Claude Code skills (progressive disclosure)
├── .cursor/
│   ├── rules/
│   │   ├── 000-project.mdc      # thin, always-apply, points back to AGENTS.md
│   │   └── 200-high-risk-paths.mdc  # scoped, glob-matched, loads only near risky code
│   ├── agents/                   # Cursor subagent personas (review/verify/test)
│   └── skills/                   # Cursor skills (or point at .claude/skills/)
└── playbooks/
    ├── dependency-upgrade.devin.md   # general SDLC: incremental dep upgrades, PR per risk group
    └── hugo-docs-check.devin.md      # narrower example: docs build + link check

AGENTS.md is the only file all five tools read natively or near-natively. Everything else exists purely to hold one tool’s extra, tool-specific capability — none of it should restate what’s already in AGENTS.md. That’s the drift-prevention mechanism: one canonical file for shared rules, thin or scoped tool-specific files layered on top.

Concrete File Examples

AGENTS.md - Canonical Cross-Tool Rules

# AGENTS.md — Canonical Project Rules

<!--
  Single source of truth, read natively (or near-natively) by Claude Code,
  Codex CLI, Antigravity CLI, and Devin CLI.

  Keep this file lean: every line here loads into every agent's context,
  every session, regardless of task. Anything task-specific, infrequently
  needed, or only relevant to one tool belongs in a Skill, a Playbook, or
  a tool-specific override file (CLAUDE.md, GEMINI.md) — not here.
-->

## Stack

- [Language/framework — e.g. TypeScript, Next.js 15 App Router]
- [Database / ORM]
- [Package manager] — state it explicitly; agents default to whichever is
  most common in training data if you don't.

## Commands

Run these before considering any task complete:

```bash
[lint command]
[test command]
[typecheck command]

Conventions

• One responsibility per function/class/file. If a file exceeds roughly [300] lines or a function exceeds roughly [40] lines, split it before adding more — don’t append.
• Keep dependency fan-out low: depend on an interface/abstraction rather than a concrete deep chain, so a small change doesn’t require pulling a wide dependency graph into context to verify.
• [Naming conventions, export style, etc.]
• Never modify files in [/legacy/ or other frozen paths].

Skills

See .claude/skills/, .codex/ skill config, .gemini/config/skills/ (or wherever each tool discovers them) for task-specific instructions — deployment, migrations, code review, release notes. This file intentionally does not duplicate skill content; it only points at where to find it.

Guardrails

• Never force-push or rewrite shared git history without explicit confirmation.
• Never commit secrets, credentials, or .env files.
• Ask before running destructive database operations.
• Stop and report on the first build/test failure rather than attempting speculative fixes.

### CLAUDE.md - Claude Code Specific Additions

```markdown
# CLAUDE.md — Claude Code Additions

<!--
  Shared conventions, commands, and guardrails live in AGENTS.md — Claude
  Code reads that file too. This file holds only what's specific to how
  Claude Code itself operates a session.
-->

See `AGENTS.md` for project conventions, commands, and guardrails.

## Compaction guidance

When compacting (`/compact`), preserve:

- Any failing test output and the diff that produced it
- Open TODOs and unresolved questions from the user
- The current task's acceptance criteria

Discard exploratory file reads that didn't lead to a change.

## Subagent routing

- Default subagent model: Haiku — for test runs, log triage, and doc
  lookups.
- Escalate to Sonnet only when the subagent's task requires code
  generation, not just retrieval or summarization.
- Reserve Opus for the primary session on architecture-level decisions.

## Session hygiene

- Before starting an unrelated task, prefer `/clear` over letting stale
  context linger through auto-compact.
- Flag any MCP server unused for two or more weeks for removal from this
  project's config — it still costs prefix tokens every turn even if
  nothing calls it.

## Effort

- Default to a lower `/effort` setting for routine edits; only raise it
  for multi-file refactors or architecture-level reasoning.

Key Pattern: Notice how CLAUDE.md starts with a pointer to AGENTS.md and only contains Claude-specific operational details (compaction, subagent routing, session hygiene). This avoids duplication while providing tool-specific guidance.

Tool-Specific File Examples

The previous sections contain detailed examples for:

• Cursor .mdc rules: See Part V for 000-project.mdc and 200-high-risk-paths.mdc examples
• Devin Playbooks: See Part IV for dependency-upgrade.devin.md example
• Subagent configurations: Each tool’s section contains configuration patterns

File Purpose Summary

Setup Checklist

Initial Setup

• Write AGENTS.md first: Conventions, build/test/lint commands, guardrails, a pointer to your skills index. Keep it lean — strip anything that reads like an auto-generated architecture overview or README duplication; agents can already read the README and discover file-level detail themselves.

• Add CLAUDE.md with Claude-specific additions only, plus a one-line pointer to AGENTS.md. Don’t duplicate content that belongs in the shared file.

• Add GEMINI.md with Antigravity-only overrides; confirm it isn’t also being loaded by a separate Gemini CLI install on the same machine (both write to ~/.gemini/GEMINI.md).

• Confirm Devin’s read_config_from setting (~/.config/devin/config.json) has agents_standard: true so it’s actually reading your AGENTS.md.

Skills and Playbooks

• Move any repeatable multi-step workflow into a Skill (Claude/Codex/Antigravity/Cursor) or a Playbook (Devin) instead of a paragraph in a Rules file. This is the primary mechanism for reducing token overhead through progressive disclosure.

• In Cursor specifically, split any always-apply rule that’s grown past a screen or two into scoped .mdc rules with real globs — an always-apply rule that’s really only relevant to src/api/** is paying the always-loaded tax for no reason.

Model Configuration

• Set per-subagent model tiers in each tool’s subagent config — not just the primary session model. Reserve expensive models (Opus, GPT-4, etc.) for high-value tasks, use cheaper models for routine operations.

Maintenance

• Re-audit all five tools’ config quarterly. The biggest silent cost driver in these files isn’t any single bad line — it’s accumulated, never-pruned instructions nobody remembers adding.

• Monitor for rule drift: Ensure tool-specific files don’t gradually accumulate content that belongs in AGENTS.md. The shared file should remain the single source of truth for cross-tool rules.

Common Pitfalls

Path Conflicts

• Gemini CLI + Antigravity CLI: Both write to ~/.gemini/GEMINI.md, causing silent context pollution. Separate deliberately using ~/.gemini/AGENTS.md for shared rules.

Duplication

• Copying content between AGENTS.md and tool-specific files: Defeats the purpose of having a shared canonical file. Reference AGENTS.md from tool-specific files instead of duplicating.

Always-Loaded Bloat

• Over-sized always-apply rules: Especially problematic in Cursor where scoped rules are the native primitive. Split large always-apply rules into glob-matched scoped rules.

Missing Progressive Disclosure

• Putting task-specific instructions in always-loaded files: Move these to Skills or Playbooks that load on-demand instead.

Assumed Parity

• Assuming AGENTS.md parity across tools: Claude Code only gained AGENTS.md support in spring 2026 and still treats CLAUDE.md as richer for Claude-specific features. Don’t assume full parity.

Key Takeaways

1. One Canonical Source: AGENTS.md is the single source of truth for cross-tool rules. Everything else should reference it, not duplicate it.

2. Progressive Disclosure: Use Skills, Playbooks, and scoped rules to load instructions only when relevant. This is the primary token optimization mechanism.

3. Tool-Specific Layers: Each tool has unique capabilities (Cursor’s scoped rules, Devin’s Playbooks, etc.). Leverage these rather than fighting against them.

4. Regular Maintenance: Token optimization isn’t set-and-forget. Quarterly audits prevent the accumulation of redundant instructions.

5. Model Tier Strategy: Per-subagent model routing is as important as file organization. Reserve expensive models for high-value tasks.

The concrete examples provided in this guide (AGENTS.md, CLAUDE.md, Cursor .mdc rules, Devin Playbooks) demonstrate these principles in action. Adapt them to your project’s specific needs while maintaining the core discipline: small always-loaded rules, large on-demand instructions.