# Which AI Coding Tools Read Which Instruction File? 9 Tools

> Source: <https://www.digitalapplied.com/blog/coding-agent-instruction-files-which-tool-reads-what>
> Published: 2026-09-20 00:00:00+00:00

A coding agent reads a Markdown file at the root of your repository before it does anything, and the filenames have multiplied: CLAUDE.md, AGENTS.md, GEMINI.md, a rules folder, a Copilot instructions file. On September 18, 2026 Claude Code version 2.1.277 began reading AGENTS.md in any project that has no CLAUDE.md. That makes the practical question sharper for every team using more than one tool: which file does each tool read, what wins when several exist, and do you need to keep two?

This matrix answers those questions for nine tools from each vendor's own documentation, read on September 22, 2026: Claude Code, OpenAI Codex, Cursor, GitHub Copilot, Gemini CLI, Google Antigravity, Cline, Continue and the AGENTS.md convention's own site. Where a vendor does not state a behaviour, the cell says "not documented" rather than guessing. This blog runs on Anthropic's models; Claude Code is one row on the same terms as the rest.

1. 01Six of nine tools read AGENTS.md; none of them read it the same way.Codex, Cursor, Copilot, Antigravity and Cline read it by name. Claude Code now reads it only when no CLAUDE.md exists. Gemini CLI reads it only if you rename its context file. Continue's documentation does not mention it.
2. 02Only two tools publish a size cap a real instruction file would hit.Codex stops adding files at 32 KiB combined. Antigravity limits a rules file to 12,000 characters. Claude Code gives line-count guidance and skips any file over 4 MiB; Cursor gives line-count guidance only. Copilot, Gemini CLI, Cline and Continue document no number.
3. 03Three tools say the file reaches the model on every request.Copilot and Gemini CLI state it outright, and Cline says every rule loads for every request unless scoped by path. Codex builds its instruction chain once per run. The others describe loading at session start or during prompt expansion and do not say whether it is re-sent.
4. 04In Claude Code, CLAUDE.md wins outright unless you change one setting.The default reads AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md at or above the working directory. A second setting reads both, CLAUDE.md first in each directory.

## 01 — The hookWhat changed on September 18

Claude Code's repository [changelog](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md) carries version headings but no dates, so the date comes from the npm registry: version 2.1.277 was published at 16:22 UTC on September 18, 2026. The changelog entry is one line, quoted in full below. Anthropic's [memory documentation](https://code.claude.com/docs/en/memory) adds the detail: reading AGENTS.md directly needs 2.1.277 or later, it does not yet work in sessions that cannot fetch feature flags (Amazon Bedrock and other third-party providers, or telemetry switched off), and in those sessions the workaround is to import AGENTS.md from a CLAUDE.md.

The change matters beyond one product because AGENTS.md has become the closest thing to a shared filename. Its own site, which is stewarded by the Agentic AI Foundation under the Linux Foundation, claims adoption in over 60,000 open-source projects; that figure is the site's own and we have not audited it. Our [post on the ETH Zurich study](https://www.digitalapplied.com/blog/agents-md-eth-zurich-study-inference-costs-guide) covers what such a file costs in tokens; this post covers only who reads it.

Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under "Project instructions" in /config (not yet on Bedrock, Vertex or Foundry)Claude Code CHANGELOG.md, entry for 2.1.277, published to npm September 18, 2026

## 02 — The matrixTable 1: which files, where

"Project files" are the filenames the tool looks for inside a repository. "User-level" is a file outside the repository that applies to everything you open. "Nested" asks whether a second file deeper in the tree is read as well. The Gemini CLI row is kept because its documentation still describes the behaviour and the open-source project is still receiving commits; Google's [May 19, 2026 announcement](https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/) retired the hosted free, Pro and Ultra tiers on June 18, 2026, while Code Assist Standard and Enterprise licences kept access.

| Vendor documentation read September 22, 2026. Documentation pages carry no per-page date, so each cell describes the page as it stood at the time of writing. |  |  |  | 
|---|---|---|---|
| Tool | Project files read | User-level file | Nested files | 
|---|---|---|---|
| Claude Code (2.1.277+) | CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md, .claude/rules/*.md; AGENTS.md only when no CLAUDE.md-family file exists at or above the working directory | ~/.claude/CLAUDE.md, ~/.claude/rules/, plus a managed policy file per OS | Yes: parents load at launch, subdirectory files load when Claude reads a file there | 
| OpenAI Codex | Per directory, first match of AGENTS.override.md, then AGENTS.md, then configured fallback names; at most one file per directory | $CODEX_HOME/AGENTS.override.md, else $CODEX_HOME/AGENTS.md | Yes: walks from the project root down to the working directory | 
| Cursor | .cursor/rules/**/*.mdc (a plain .md there is ignored); AGENTS.md in the root and subdirectories | User Rules set in the app, not a documented file path; Team Rules from the dashboard | Yes for AGENTS.md; project rules scope by glob patterns instead of directory | 
| GitHub Copilot | .github/copilot-instructions.md; .github/instructions/**/*.instructions.md; agent instructions in AGENTS.md, CLAUDE.md or GEMINI.md | Copilot CLI: ~/.copilot/copilot-instructions.md; personal instructions in the web UI | AGENTS.md may sit anywhere in the repository and the nearest one wins; CLAUDE.md and GEMINI.md are documented as a single root file | 
| Gemini CLI (hosted tiers retired June 18, 2026) | GEMINI.md by default; other names only if context.fileName is set in settings | ~/.gemini/GEMINI.md | Yes: workspace directories and parents at launch, plus just-in-time reads when a tool touches a file | 
| Google Antigravity | GEMINI.md and AGENTS.md in the active workspace; .agents/rules/*.md | ~/.gemini/GEMINI.md; the CLI also reads ~/.gemini/antigravity-cli/rules/ | Not documented | 
| Cline | .clinerules/, .cline/rules/, .cursorrules, .windsurfrules, AGENTS.md | A Documents/Cline/Rules folder; also ~/.agents/AGENTS.md | Not documented as a directory walk; rules scope by path globs | 
| Continue | .continue/rules/*.md, plus YAML rules in config.yaml | Not documented | Not documented | 
| The AGENTS.md convention (agents.md) | AGENTS.md at the repository root, one per package in a monorepo | Not specified: the convention defines a repository file only | Yes: the nearest file in the directory tree takes precedence | 

## 03 — The rulesTable 2: precedence, limits, every turn

The same nine tools on the three questions that decide whether a long file is a cost or a liability: what wins when files conflict, whether a size limit is enforced, and whether the file is sent on every request or only once.

| Same sources as Table 1, read September 22, 2026. "Not documented" means the vendor's page states nothing, not that the behaviour is absent. |  |  |  | 
|---|---|---|---|
| Tool | Precedence when several exist | Documented limit | Sent every turn? | 
|---|---|---|---|
| Claude Code | CLAUDE.md family wins outright by default; files concatenate root to working directory, nearest read last; a setting can read both | No cap a real file reaches; guidance to target under 200 lines per file, and any file over 4 MiB is skipped | Loaded at the start of every session; per-turn re-send not documented | 
| OpenAI Codex | Global first, then root down to the working directory; closer files override because they appear later in the prompt | Hard cap: 32 KiB combined by default, configurable | Built once per run, once per session in the terminal UI | 
| Cursor | Team Rules, then Project Rules, then User Rules; merged, earlier source wins on conflict; nested AGENTS.md combine with more specific winning | No hard cap; guidance to keep rules under 500 lines | Included at the start of the model context when applied | 
| GitHub Copilot | Personal, then repository (path-specific, repo-wide, agent files), then organization; all relevant sets are still provided | Not documented | Yes: sent with every chat message | 
| Gemini CLI | Global, then workspace and parents, then just-in-time files; concatenated, no conflict rule documented | Not documented | Yes: sent to the model with every prompt | 
| Google Antigravity | Not documented | Hard cap: 12,000 characters per rules file | Injected during prompt expansion; every-turn behaviour not documented | 
| Cline | Workspace rules take precedence over global rules on conflict | Not documented as a number; a warning that rules consume context tokens | Every rule loads for every request unless scoped by paths | 
| Continue | Lexicographical file order; joined with new lines; no conflict rule documented | Not documented | Applies to agent, chat and edit requests; not to autocomplete | 
| AGENTS.md convention | The closest file to the edited file wins; explicit chat prompts override everything | Not documented: no required fields, plain Markdown | Not documented | 

Claude Code's documentation says to target under 200 lines per CLAUDE.md file. That is guidance, not an enforced cap, and it is a different mechanism from auto memory, which loads the first 200 lines or 25 KB. Cursor's 500-line figure is guidance in the same way. The enforced numbers in the table are Codex's 32 KiB and Antigravity's 12,000 characters, plus a 4 MiB ceiling above which Claude Code skips a file entirely, a threshold no hand-written instruction file reaches.

## 04 — Precedence in practiceWhen a repo carries *both* files

Precedence is where teams get surprised, because three different designs hide behind the same word. In [Codex](https://learn.chatgpt.com/docs/agent-configuration/agents-md), precedence is position: every file from the global scope down to the working directory is concatenated, and a closer file overrides an earlier one only because the model sees it later in the prompt. In Cursor and Copilot, precedence is a merge order with every relevant set still supplied. In Claude Code, the default is an either-or: if any CLAUDE.md-family file exists at or above the working directory, AGENTS.md is not read at all.

That either-or has edges worth knowing. The user-level ~/.claude/CLAUDE.md, a managed policy file and the .claude/rules/ folder do not count for the check, so they keep loading alongside AGENTS.md. And an AGENTS.md read through the setting behaves differently from a CLAUDE.md: it is not listed by the memory and context commands, and it does not fire the hooks that a loaded CLAUDE.md fires. Claude Code exposes four settings, shown below.

##### CLAUDE.md, or AGENTS.md

Reads CLAUDE.md files; reads AGENTS.md only when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md exists at or above the working directory.

##### CLAUDE.md and AGENTS.md

Reads both, each directory's CLAUDE.md first and then its AGENTS.md; an AGENTS.md already pulled in by import or symlink is not read twice.

##### CLAUDE.md only

Ignores AGENTS.md entirely. The pre-2.1.277 behaviour, for teams that want the two files to stay independent.

##### Managed file only

Only the organisation's managed CLAUDE.md and auto memory load at launch; project files of either name are ignored.

## 05 — The decisionWhat to write where

Three lines cover most teams. Keep the instructions that every tool needs in AGENTS.md, because it is the file most tools read by name. Put anything specific to one tool in that tool's own file or rules folder. And if you use Claude Code alongside anything else, decide the either-or deliberately rather than by accident.

What goes inside the file is a separate question. We cut ours and measured what broke in [our instruction-file audit](https://www.digitalapplied.com/blog/ai-agent-instruction-file-audit-what-we-cut); the plugin layer that sits beside these files is in [our post on what still does not port between agents](https://www.digitalapplied.com/blog/agent-plugins-1-0-ga-what-still-does-not-port). If you are standardising coding agents across a team, our [AI transformation service](https://www.digitalapplied.com/services/ai-transformation) starts with this matrix for your toolset.

## 06 — The gapsWhat we could not verify

Cursor's current rules page does not mention the legacy .cursorrules file, so we make no claim that Cursor still reads it; Cline's page lists it as a format Cline reads, which is not evidence about Cursor. Continue's rules page never mentions AGENTS.md, a user-level path, a size limit or nested files; a closed GitHub issue asking for AGENTS.md support is not documentation, so all four cells say not documented. Antigravity documents its surfaces but no precedence rule between GEMINI.md, AGENTS.md and its rules folder.

Two dating caveats apply to the whole table. The npm publish time is the best public timestamp for a Claude Code release, not an Anthropic-stated date. And every documentation page was read two days after this post's editorial date and prints no last-updated date of its own, so no cell can be proven to have been on the page on September 20. The only hard-dated sources are the npm registry, Google's May 19 announcement and the GitHub repository metadata.

## 07 — How we built itMethodology

A census of what vendors document about their own tools, not a test of any of them and not a ranking.

- Population
- Nine rows: Claude Code, OpenAI Codex, Cursor, GitHub Copilot, Gemini CLI, Google Antigravity, Cline, Continue, and the AGENTS.md convention as described on its own site. Windsurf, Aider, Devin and Amazon Q are not tabulated because no first-party page was read for them in this pass.
- Inclusion rule
- A cell needs a sentence on the vendor's own documentation or registry metadata. Community rule collections, comparison blogs and GitHub issues were not used for any cell; one issue was checked only for its open or closed state.
- Classification rule
- "Not documented" means the page states nothing on the question. A line-count recommendation is recorded as guidance, a byte or character figure that stops loading is recorded as a hard cap. "Sent every turn" is marked yes only where the vendor says so in those terms.
- Dates
- The Claude Code release is dated by its npm publish time because the repository changelog carries none. Google's retirement announcement is dated by its own byline. Every other source is an undated documentation page.
- What was excluded
- A secondary claim that a March 2026 Antigravity release added AGENTS.md support (not found on the changelog). Any Claude Code release after 2.1.278. Token-cost measurements, which the instruction-file audit owns.
- As-of date
- This page belongs to the September 20, 2026 batch; its sources were collected on September 22, 2026. No document dated after September 20, 2026 is used.
- Known limitations
- Undated documentation pages can change without notice. This blog runs on Anthropic's models; the Claude Code row is classified by the same rule as the rest.
- Refresh
- Extended when a vendor documents a new filename, a precedence change or a size limit, and re-read at each Claude Code change to the project-instructions setting.

## 08 — Next stepOne shared filename, nine different readers

### Pick the file each tool reads, then delete the one nothing reads

List the coding tools your team actually runs, look up each one in Table 1, and write down which file it reads and whether it walks nested directories. If AGENTS.md covers every tool but Claude Code, either drop CLAUDE.md or make it a one-line import. Then check the file against the two hard caps and the every-turn column before it grows.