Cross‑agent config that actually works in mid‑2026: unify CLAUDE.md, AGENTS.md, and Copilot instructions

The July 2026 agent landscape made one choice obvious: if multiple autonomous coding agents will plan, edit, and even open background pull requests for you, they all need to read the same instructions — or they’ll fight each other. The good news is every major tool now reads a project‑level config file you control, so you can declare one source of truth and let Claude Code, Codex, Cursor, Copilot, Gemini, and friends pull from it consistently.^[1] Multi‑agent orchestration and async background PRs are mainstream this summer, which raises the cost of inconsistent guidance and makes shared config non‑negotiable.^[2] And yes, the assistants list is broad — Copilot, Cursor, Claude Code, Amazon Q Developer, JetBrains AI Assistant, Gemini Code Assist, plus general‑purpose LLMs — but the pattern holds: they all benefit from a clear, codified project charter and guardrails.^[4]

Why a single source of truth matters now

When your primary agent spawns sub‑agents or runs tasks in the background, a stale or conflicting rule set can cause divergent edits, flaky tests, or recurring style churn. Today’s leading stacks lean into parallel sub‑agents and background PR generation; a single, shared contract keeps them aligned on scope, coding standards, and risk gates.^[2] The big players also optimize for different strengths — autonomy vs editor UX vs enterprise standardization — so a neutral, portable policy lets you mix and match without rewriting instructions per tool.^[5]

The cross‑agent files you actually need

Every tool has a preferred filename and location. You don’t have to use all of them; pick the ones that match your stack and keep content consistent across files.

• CLAUDE.md — Claude Code (project root; also reads ~/.claude/)
• AGENTS.md — Codex CLI (and as a common fallback in other tools); supports per‑directory scoping
• AGENTS.override.md — Codex local‑only overrides alongside AGENTS.md
• GEMINI.md — Gemini CLI (project root; also reads ~/.gemini/)
• .cursor/rules/*.mdc — Cursor’s current rules directory (replaces legacy .cursorrules)
• .github/copilot-instructions.md — Copilot global repo instructions
• .github/instructions/.instructions.md — Copilot scoped instructions with frontmatter
  ^[1]

A minimal, portable AGENTS.md you can drop anywhere

Start with a single AGENTS.md and mirror key parts into tool‑specific files as needed. Keep it terse, deterministic, and testable.

# AGENTS.md

## Project charter
- Product: Payments service and React admin.
- Non-goals: New features without tickets; infrastructure drift.

## Constraints
- Language/tooling: Python 3.12, FastAPI, React 18, pnpm.
- Security: No plaintext secrets; use env vars and .env.example.
- Performance budgets: P95 API < 200ms; SSR first content < 1.5s.

## Editing policy
- Prefer surgical diffs; preserve comments and git history.
- For large refactors, generate a plan.md first, then PR branch.
- Always add/adjust tests for changed codepaths.

## Code style
- Python: ruff + black; TS/JS: eslint + prettier.
- Enforce via pre-commit and CI.

## Risk gates
- High-risk changes (auth, payments, migrations): open a draft PR and request human review before running.
- Never auto-rotate secrets.

## Deliverables
- For tasks >15m: create a ./plans/<task>.md with steps, risks, rollbacks.
- Output: branch, PR with summary, test results, and checklist.

Tool‑specific hooks and overrides (copy/paste ready)

All of the following mirror the same policy with minor format tweaks.^[1]

Claude Code: CLAUDE.md

# CLAUDE.md

import: ./AGENTS.md

# Claude-specific notes
- Use "read", "write", and "run" conservatively; show commands before execution.
- Summarize diffs with filenames + line ranges.

Codex CLI: AGENTS.override.md (local safety net)

# AGENTS.override.md

# Local-only constraints (do not commit secrets)
- Cost limit: $2 per task.
- Do not run container builds on battery power.

Copilot: .github/copilot-instructions.md (global) and scoped instructions

# .github/copilot-instructions.md

Include ./AGENTS.md

- When opening PRs, request reviewers: @backend-oncall, @frontend-oncall.
- Use labels: ai-change, needs-review.

# .github/instructions/.instructions.md
---
scope: paths:
  - app/**
  - packages/ui/**
priority: high
---

Include ../../AGENTS.md

- For UI files, run storybook snapshot updates in CI, not locally.

Cursor: .cursor/rules/project.mdc

// .cursor/rules/project.mdc
#include ../shared.mdc

[policy]
- Mirror AGENTS.md constraints.
- Prefer "Apply" with small hunks; avoid mass rewrites.

[ci]
- Run: pnpm -w test:ci && pytest -q

Gemini CLI: GEMINI.md

# GEMINI.md

include: ./AGENTS.md

notes:
- Prefer explicit bash with set -euo pipefail in scripts.

Quick scaffold you can drop into any repo

This creates a consistent skeleton and mirrors AGENTS.md into tool files.

mkdir -p .github/instructions .cursor/rules

# AGENTS.md
cat > AGENTS.md <<'MD'
# AGENTS.md
## Project charter
- ...
MD

# CLAUDE.md
cat > CLAUDE.md <<'MD'
import: ./AGENTS.md
MD

# Codex local overrides
cat > AGENTS.override.md <<'MD'
# Local-only overrides
MD

# Copilot
cat > .github/copilot-instructions.md <<'MD'
Include ./AGENTS.md
MD

cat > .github/instructions/.instructions.md <<'MD'
---
scope: paths: ["app/**", "packages/ui/**"]
priority: high
---
Include ../../AGENTS.md
MD

# Cursor
cat > .cursor/rules/project.mdc <<'MD'
[policy]
- Mirror AGENTS.md constraints.
MD

# Gemini
cat > GEMINI.md <<'MD'
include: ./AGENTS.md
MD

Model and agent selection notes for July 2026

If you’re standardizing today, expect the following shape of the field and plan configs accordingly:

• OpenAI Codex leads overall workflows as GPT‑5.6 “Sol” reaches GA in the client; Claude Code advances on Opus 4.8 and the Claude 5 family; Grok Build (Grok 4.5) is the fastest riser; GLM 5.2 is the strongest open‑weight; Gemini CLI remains a solid free on‑ramp.^[2]
• Strengths differ: Claude Code wins on autonomy and raw code quality; Cursor on developer experience; Copilot on cost and GitHub‑native workflows; Codex and Gemini CLI are excellent for narrower, specialized use cases inside a broader stack — your config should not assume one agent will do everything.^[5]
• Choose by primary workflow: AI‑first editor (Cursor), GitHub‑centric teams (Copilot), terminal‑native development (Claude Code). Keep the same guardrails across tools to avoid behavior drift when teammates switch contexts.^[3]

Key takeaways

• Put project rules in AGENTS.md, then mirror them into CLAUDE.md, Copilot instructions, Cursor rules, and GEMINI.md.^[1]
• Consistent config prevents multi‑agent and background PR workflows from drifting off‑policy.^[2]
• Pick agents by workflow (editor, terminal, GitHub) and strengths — the config stays the same.^[5][3]
• Expect a heterogeneous stack; write instructions once, run them everywhere.^[4]

References

1. CLAUDE.md, AGENTS.md & Copilot Instructions: Configure Every AI Coding Assistant — https://www.deployhq.com/blog/ai-coding-config-files-guide
2. Best AI Coding Agents in 2026, Ranked — https://mightybot.ai/blog/coding-ai-agents-for-accelerating-engineering-workflows
3. 12 Best AI Coding Assistants I Reviewed for 2026 — https://emergent.sh/learn/best-ai-coding-assistant
4. AI Coding Assistant Statistics 2026: Adoption & Trust — https://uvik.net/blog/ai-coding-assistant-statistics
5. Claude Code vs Cursor vs Codex vs Copilot — 2026 Comparison — https://www.clarista.io/blog/claude-code-vs-cursor-vs-codex