# Repository Layout & Setup > Recommended repository structure and setup checklist for implementing token optimization across all five tools - **Category**: optimizing-token-usage-practices - **Canonical URL**: https://designpattern.fyi/optimizing-token-usage-practices/part-vi-repo-layout/ --- ## Description Recommended repository structure and setup checklist for implementing token optimization across all five tools ## Additional Notes ## 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 ```markdown # AGENTS.md — Canonical Project Rules ## 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 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 | File | Purpose | Tool(s) | Loading Behavior | |---|---|---|---| | `AGENTS.md` | Canonical cross-tool rules | All 5 tools | Always loaded (except Cursor scoped) | | `CLAUDE.md` | Claude-specific additions | Claude Code | Always loaded | | `GEMINI.md` | Antigravity-specific overrides | Antigravity CLI | Always loaded | | `.codex/agents/*.toml` | Codex subagent definitions | Codex CLI | Per-subagent configuration | | `.antigravity/agents/*.yaml` | Antigravity subagent definitions | Antigravity CLI | Per-subagent configuration | | `.claude/skills/` | Claude Code skills | Claude Code | Load on match | | `.cursor/rules/*.mdc` | Cursor scoped rules | Cursor | Glob-based activation | | `.cursor/agents/*.md` | Cursor subagent personas | Cursor | Per-subagent configuration | | `.cursor/skills/` | Cursor skills | Cursor | Load on match | | `playbooks/*.devin.md` | Devin workflows | Devin CLI | Load on invocation | ## 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.