One config to rule them all: AGENTS.md, CLAUDE.md, and Copilot instructions for a sane multi‑agent workflow

If your team runs more than one coding agent, the fastest way to regain control is to treat agent instructions like any other piece of infrastructure: versioned, reviewed, and standardized. The good news is every major tool now reads a project‑level config file. The less fun part is that each vendor picked a different filename and sometimes a different format. In this guide I’ll show the unified layout I ship on client repos, why it works across Cursor, Claude Code, Codex, Copilot, Gemini/Antigravity, and OpenCode, and how to bake in cost/perf guardrails from day one.

Why a universal agent config beats one‑off prompts

The old pattern—pasting context into a chat box—breaks the moment you add a second agent. In 2026, the frontier models have largely converged; your experience is now dominated by the “harness” around the model: how the tool reads your repo, persists plans, runs tasks, and respects your policies [2]. That also means a single, shared source of truth for instructions pays off immediately. Bonus: nearly all major agents now support the Model Context Protocol (MCP), so one set of MCP servers (docs, APIs, search) can power multiple tools [2].

There’s also a hard cost angle. Teams are re‑evaluating tools as usage‑based bills pile up; some high‑profile shops overspent their 2026 budgets early, and the only sustainable response is to measure and govern per‑engineer AI spend—and make the default agent behaviors cheaper [3].

The files each agent actually reads (2026 reality check)

Here’s the current state of play, simplified from vendor docs and field usage:

• Claude Code reads CLAUDE.md at the project root (and can also pick up from a user dir) [1].
• OpenAI’s Codex CLI and several others honor a universal AGENTS.md in the repo; Codex also supports a local‑only AGENTS.override.md for developer‑specific tweaks you should gitignore [1].
• Gemini CLI (transitioning toward Antigravity) checks GEMINI.md; Cursor uses rules under .cursor/rules with an MDC flavor; Copilot reads .github/copilot-instructions.md and optionally scoped instruction files under .github/instructions/ [1].

A maintainable layout for multi‑agent teams

I standardize on a universal file plus tool‑specific overrides. Paraphrasing the structure recommended in the DeployHQ guide and extending it with a couple of safety defaults [1]:

your-project/
├─ AGENTS.md                 # Universal, tool-agnostic ground truth
├─ AGENTS.override.md        # Local-only developer overrides (gitignored)
├─ CLAUDE.md                 # Claude-specific additions (hooks, workflow knobs)
├─ .github/
│  └─ copilot-instructions.md # Copilot-specific guidance
├─ .cursor/
│  └─ rules/
│     └─ repo.mdc            # Cursor scoped rules (MDC)
└─ ...

And the matching .gitignore entry so private overrides never leak:

# Agent local overrides
AGENTS.override.md

Concrete starter templates you can paste in

1) AGENTS.md (universal)

This is the document most tools will fall back to. Keep it tight and operational.

# AGENTS.md

## Repository Facts
- Monorepo: packages/app (Next.js), packages/api (FastAPI), infra/ (Terraform)
- Primary runtime: Node 20, Python 3.11; package manager: pnpm 9
- CI: GitHub Actions; default branch: main; release: semantic-release

## Goals
- Ship small PRs (<300 LOC changed) with tests and docs.
- Preserve public API compatibility unless an ADR says otherwise.

## Constraints
- Do not commit secrets. Use env vars and Doppler.
- No direct pushes to main. Always open a PR.
- Prefer existing libraries; get approval before adding dependencies.

## Definition of Done
- Unit tests added/updated; `pnpm -w test` passes.
- Lint/format clean: `pnpm -w lint && pnpm -w format:check`.
- Changelog entry via conventional commits.

## Tools & MCP
- MCP servers available:
  - firecrawl: mcp://firecrawl (docs + web search)
  - vector: mcp://repo-embeddings (code navigation)
- Use these before calling external web APIs.

## Communication
- When uncertain, propose a plan in the PR description and request review.

2) CLAUDE.md (Claude Code specifics)

Claude Code shines as a programmable terminal agent; recent builds expose deep workflow hooks (on 30+ events) and dynamic workflows—use them to wire your repo’s rituals instead of freehand shelling [2].

# CLAUDE.md

## Workflow Hooks
- on_branch_create: run `pnpm -w install && pnpm -w build`
- on_task_plan: ask for confirmation if > 3 files will change.
- on_before_commit: run `pnpm -w lint && pnpm -w test`.
- on_after_pr_open: comment checklist and link preview URL.

## Guardrails
- Refuse to run `terraform apply` outside CI.
- Cap token usage per task to 150k tokens; ask before exceeding.

## Style
- TypeScript strict mode; prefer Zod for validation; tests with Vitest.

3) .github/copilot-instructions.md (Copilot)

Copilot now uses a centralized instruction file; keep it short and targeted at completions and inline edits. Note: Copilot moved to credit‑based billing on June 1, 2026; basic completions remain unlimited on paid plans, but heavy agent actions may consume credits—opt into small diffs first [5].

# Copilot Instructions

Focus areas
- Prefer small refactors and test scaffolds.
- Follow repo ESLint/Prettier; never reformat entire files.

Prohibitions
- Do not add new dependencies without TODO + issue link.
- Do not modify CI YAML without an approval comment tag: `# approved:devex`.

When unsure
- Suggest a 3-step plan in a code comment before applying changes.

4) .cursor/rules/repo.mdc (Cursor Composer rules)

Cursor’s agentic mode (Composer 2.5) can parallelize tasks and even farm work to cloud VMs; set boundaries to keep it from over‑editing while you’re in flow [4].

# repo.mdc
@rules
- limit_changes_per_run: 250 lines
- prefer_apply_patch: true
- test_command: "pnpm -w test"
- ask_before_background_tasks: true

@context
default_branch = "main"

Cost and performance guardrails you should encode now

Two pragmatic levers:

• Cap blast radius in config. Enforce small PRs, token caps, and “ask before changing >N files” in each tool’s native file. This aligns with both cost control and acceptance rates [3].
• Pick agents per job, not per hype. If your task is “fast in‑editor editing,” Cursor likely wins. For programmable terminal depth and hooks, Claude Code fits. For asynchronous, cloud‑run PRs, Codex is strong. Those trade‑offs, not raw IQ, drive delivered value in 2026 [2].

If you need a hard data point to calibrate expectations, the public Terminal‑Bench 2.1 leaderboard currently puts Codex CLI + GPT‑5.5 at 83.4%, Claude Code + Opus 4.8 at 78.9%, and Gemini CLI + Gemini 3.1 Pro at 70.7%—useful signals, but remember your repo and constraints matter more than the lab [5].

Verification: a pre‑commit check for “agent‑ready” repos

Ship a tiny script to fail CI when the instruction files drift or go missing.

#!/usr/bin/env bash
set -euo pipefail

missing=()
for f in AGENTS.md .github/copilot-instructions.md CLAUDE.md .cursor/rules/repo.mdc; do
  [[ -f "$f" ]] || missing+=("$f")
done

if (( ${#missing[@]} > 0 )); then
  echo "Missing agent config files:" "${missing[@]}" >&2
  exit 1
fi

# Lint basic invariants
grep -q "Definition of Done" AGENTS.md || { echo "AGENTS.md missing DoD" >&2; exit 1; }

Wire it into CI:

# .github/workflows/agent-guard.yml
name: Agent Guard
on: [pull_request]
jobs:
  guard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ./scripts/verify-agent-config.sh

When to prefer tool‑specific overrides

• Cursor deep edits or multi‑file refactors: lean on Composer’s scoped rules so your universal AGENTS.md stays philosophy‑level while Cursor gets surgical constraints [4].
• Async backlog tasks: Codex’s cloud agent can pull your repo, work in a sandbox, and open PRs without local execution—great for churny chores like docstring coverage [4].
• Terminal‑first feature work: Claude Code’s hooks and dynamic workflows make it the best fit when your developer lives in the CLI and wants the agent to drive the full PR lifecycle [2].

A 15‑minute rollout plan

• Add AGENTS.md and CLAUDE.md with the templates above; commit.
• Create .github/copilot-instructions.md; add two prohibitions and one “when unsure.”
• Drop a minimal .cursor/rules/repo.mdc if your team uses Cursor.
• Add AGENTS.override.md to .gitignore; share an example in your docs.
• Land the Agent Guard workflow; make it required in your branch protections.

Key takeaways

• Treat agent instructions as code: one universal file plus scoped overrides.
• Encode blast‑radius and budget guardrails directly in each tool’s native config.
• MCP support across agents means one set of servers can power multiple tools.
• Choose the agent per task—terminal depth (Claude), async cloud (Codex), in‑editor speed (Cursor)—not by raw model hype.
• Keep CI honest with a simple “agent‑ready” verification step.

References

• [1] CLAUDE.md, AGENTS.md & Copilot Instructions: Configure Every AI Coding Assistant
• [2] Best AI Coding Agents in 2026: Harness, Cost, and Accuracy
• [3] Claude Code alternatives: 10 AI coding tools compared – CloudZero
• [4] Claude Code vs Codex vs Cursor: The Best AI Coding Tool in 2026
• [5] Best AI Coding Agent (2026): Ranked by Terminal-Bench, Price, and …