Coding agent instruction files compared: what each agent actually reads

Claude Code with a CLAUDE.md

The default setting reads AGENTS.md only when no CLAUDE.md exists. Keep an @AGENTS.md import in CLAUDE.md, or set "Project instructions" in /config to read both. Claude Code also ignores AGENTS.override.md.

Gemini CLI out of the box

It reads GEMINI.md. Add AGENTS.md to context.fileName in settings.json, and check with /memory show.

Nested files in VS Code

A root AGENTS.md works; per-package files in a monorepo do nothing until chat.useNestedAgentsMdFiles is on.

Big files in Codex

Codex caps project instructions at 32 KiB by default (project_doc_max_bytes). In a monorepo with several long AGENTS.md files on the path, check the limit before assuming the nearest file made it in.

Rules that are really specs

An instruction file that grows a feature's acceptance criteria is loaded on every task, for every change. Per-change rules belong in the spec for that change.

We measured the cost of missing rules

In our recorded agent runs, deleting a 13-line contract doc turned a safe API cleanup into one that broke the shipped mobile app in 2 of 3 runs.

Files

AGENTS.md                  # stack, commands, boundaries, readers
packages/billing/AGENTS.md # rules only true inside billing
CLAUDE.md                  # "@AGENTS.md" + Claude-only notes
GEMINI.md                  # or set context.fileName instead
.github/copilot-instructions.md   # optional, Copilot-only
specs/2026-09-coupon/spec.md      # goal, non-goals, ACs, evidence

What goes where

• AGENTS.md: facts that are true for every task. Who reads which table or field outside the repo, which files are generated, which migrations are frozen.
• Tool files: only what that tool alone needs, plus a pointer to AGENTS.md. Never a second copy of the rules.
• The spec: the rules for this change. The AGENTS.md guide covers the split in detail.

Kiro specs

The only agent here with a spec workflow built in: requirements.md or bugfix.md, design.md, tasks.md. Requirements use EARS ("WHEN [condition/event] THE SYSTEM SHALL [expected behavior]"). Variants: Requirements-First, Design-First, and Quick Spec without approval gates. "Run all tasks" runs independent tasks in parallel waves.

Plan modes

Claude Code, Codex, Cursor, Gemini CLI and Copilot in VS Code all have a read-only planning mode. Cursor can save the plan into the repo; VS Code keeps local plans in session memory, outside the project. A plan is not a spec: it describes steps, not the behaviour that must be true when the steps are done.

Frameworks on top

GitHub Spec Kit reached v1.0 on August 21, 2026 (v1.0.12 on September 25). OpenSpec is at v1.13.2 (September 23). BMAD-METHOD is at v6.12.0 (September 4) after cutting its core skills from 14 to 8. Our OpenSpec vs Spec Kit vs Superpowers comparison covers how to combine them.

Runs got much longer

Anthropic reports a tester's Opus 5.5 task running "for over 18 hours" unattended; Meta describes Muse Code sessions of "1,000+ tool calls (up to 24 hours)"; Alibaba describes a 10+ day autonomous build with Qwen3.8-Max. The longer an agent runs without you, the more of its decisions happen where nobody reviews them.

Plan, fan out, verify

Claude Code dynamic workflows plan and "run hundreds of parallel subagents", with "the existing test suite as its bar"; Grok Build ships a plan mode with parallel subagents, and Muse Code bundles /plan and /goal skills. When tests are the bar, acceptance criteria written as tests are what the agent actually checks against.

Smaller models closed the gap, with a spec

Anthropic reports Sonnet 5.5 above Opus 5.5 on Terminal-Bench 4.0. In our own runs, a spec lifted Haiku 4.5 from 2–5 of 8 checks to 8 of 8 on the API task. See the cross-model runs.