Harnesses · 2026-09-05 · 1,285 words · 6 min read

CLAUDE.md, AGENTS.md, and .cursor/rules: what goes in a context file

Where each coding agent looks for standing instructions, how the files load and merge, the size limits, and an audit script that finds every context file in a repo.

CLAUDE.md AGENTS.md cursor rules context files

You get the load rules for the four context-file conventions in use today, read from each vendor's documentation on the same day, the one paragraph of advice about content that all of them agree on, and a script that walks a repository and tells you which of these files you have, how big they are, and which ones are over the documented limits.

What a context file is, and what it is not

A context file is prose that the harness reads into the model's context at the start of a session. It is not configuration in the enforced sense. The Claude Code memory page says both CLAUDE.md and auto memory are "loaded at the start of every conversation" and that "Claude treats them as context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook instead." That distinction decides what belongs in the file: instructions the model should follow, not rules the harness must enforce. Enforcement is the subject of /posts/coding-agent-permission-models-compared.html.

CLAUDE.md

Claude Code reads CLAUDE.md from four scopes, listed on the memory page in load order from broadest to most specific: a managed policy file (on Windows, C:\Program Files\ClaudeCode\CLAUDE.md), the user file ~/.claude/CLAUDE.md, the project file ./CLAUDE.md or ./.claude/CLAUDE.md, and a local file ./CLAUDE.local.md meant for .gitignore. Files from the working directory and every directory above it load at launch; files in subdirectories "load on demand when Claude reads files in those directories". The page is specific about ordering: "All discovered files are concatenated into context rather than overriding each other", ordered from the filesystem root down, with CLAUDE.local.md appended after CLAUDE.md at each level.

Imports use @path syntax. "Imported files can recursively import other files, with a maximum depth of four hops", and parsing "skips Markdown code spans and fenced code blocks", so backticks are how you mention a path without importing it. Two size rules: "target under 200 lines per CLAUDE.md file", because "Longer files consume more context and reduce adherence", and a hard cutoff where Claude Code "loads a CLAUDE.md file of up to 4 MiB in full and skips a larger file".

For larger projects the page describes .claude/rules/, a directory of Markdown files discovered recursively. A rule with paths frontmatter loads only when the model works on a matching file:

---
paths:
  - "src/api/**/*.ts"
---

Rules for API handlers

- All API endpoints must include input validation
- Use the standard error response format

Rules without paths load at launch "with the same priority as .claude/CLAUDE.md". User-level rules in ~/.claude/rules/ load before project rules.

AGENTS.md

AGENTS.md is the cross-vendor convention. The agents.md site describes it as "a README for agents: a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project", says the format is "used by over 60k open-source projects", and gives the precedence rule for nested files: "Agents automatically read the nearest file in the directory tree, so the closest one takes precedence." Its list of supporting tools includes Codex, Cursor, Gemini CLI, Aider, Copilot's coding agent, and Zed, among others.

Codex documents its own reading of the file in detail. The AGENTS.md page says it looks first in the global scope (~/.codex/AGENTS.override.md or ~/.codex/AGENTS.md), then walks from the Git root down to the current directory, checking each level for AGENTS.override.md, then AGENTS.md, then fallback names, and including at most one file per directory. "Codex concatenates files from the root down, joining them with blank lines. Files closer to your current directory override earlier guidance because they appear later in the combined prompt." There is a byte limit: the configuration reference defines project_doc_max_bytes as "Maximum bytes read from AGENTS.md when building project instructions", and the AGENTS.md page gives the default as 32 KiB, adding that Codex "skips empty files and stops adding files once the combined size reaches the limit".

Claude Code does not read AGENTS.md. The memory page says so directly: "Claude Code reads CLAUDE.md, not AGENTS.md. If your repository already uses AGENTS.md for other coding agents, create a CLAUDE.md that imports it." The recommended file is three lines:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

A symlink also works, though the page notes that on Windows creating one "requires Administrator privileges or Developer Mode, so use the @AGENTS.md import instead".

Cursor rules and GEMINI.md

Cursor's rules page lists four kinds: Project Rules stored in .cursor/rules as .mdc files, "version-controlled and scoped to your codebase"; User Rules, global to the editor; Team Rules from a dashboard on paid plans; and AGENTS.md as "Simple alternative to .cursor/rules". An .mdc file has three frontmatter fields, description, globs, and alwaysApply, which map to four application modes: always, when the agent decides it is relevant, when a file matches the glob, or only when @-mentioned. The size advice is "Keep rules under 500 lines" and "Split large rules into multiple, composable rules". The older single .cursorrules file at the project root is the legacy form.

Gemini CLI's file is GEMINI.md by default. Its configuration reference says the name is set by context.fileName, which "accepts either a single string or an array of strings", that discovery walks upward and "stops at the first directory containing any of these markers" (default .git), and that /memory show prints what loaded. Setting context.fileName to AGENTS.md is how you make Gemini read the shared file.

What all four agree should go in it

The Claude Code best-practices page has the clearest statement, and nothing in the other three vendors' pages contradicts it. Its include column: "Bash commands Claude can't guess", "Code style rules that differ from defaults", "Testing instructions and preferred test runners", "Repository etiquette (branch naming, PR conventions)", "Architectural decisions specific to your project", "Developer environment quirks (required env vars)", and "Common gotchas or non-obvious behaviors". Its exclude column: "Anything Claude can figure out by reading code", "Standard language conventions Claude already knows", "Detailed API documentation (link to docs instead)", "Information that changes frequently", "Long explanations or tutorials", "File-by-file descriptions of the codebase", and "Self-evident practices like 'write clean code'".

The test the page proposes for each line is "Would removing this cause Claude to make mistakes? If not, cut it." The memory page adds the failure mode: "if two rules contradict each other, Claude may pick one arbitrarily", which is an argument for one short file over several long ones. Codex's page recommends the same categories under different names: working agreements, repository expectations, code review rules, and service-specific overrides in nested directories.

The audit script

The shipped context-files-claude-md-agents-md-cursor-rules.py walks a tree, collects every file of the eight kinds above, and prints lines, bytes, the @imports it finds outside code spans, and a flag when a file is over 200 lines or when AGENTS.md content exceeds 32 KiB. The import detector follows the Claude Code rule and strips fences and backticks first:

def imports_in(text: str) -> list[str]:
    text = re.sub(r"```.*?```", " ", text, flags=re.S)
    text = re.sub(r"`[^`]*`", " ", text)
    return IMPORT_RE.findall(text)

What ran here

I ran the script twice with Python 3.13.12 on Windows. First on this site's own source folder, which has no context files, and it said so:

C:\projects\update\vibecodetextbook.com: no agent context files found

Then on a scratch directory I seeded with nine sample files, including a CLAUDE.md that imports README.md, a .claude/CLAUDE.md that imports AGENTS.md, a nested services/payments/AGENTS.override.md, and a CLAUDE.local.md padded to 231 lines to trip the limit:

9 context file(s)
file                                   kind                  lines   bytes  notes
.claude\CLAUDE.md                      CLAUDE.md                 5      82  imports: AGENTS.md
.claude\rules\api.md                   .claude/rules/*.md        6      66
.cursor\rules\react.mdc                .cursor/rules/*.mdc       6     107
.cursorrules                           .cursorrules              1      23
AGENTS.md                              AGENTS.md                 5      63
CLAUDE.local.md                        CLAUDE.local.md         231    4504  OVER 200 LINES
CLAUDE.md                              CLAUDE.md                 4     125  imports: README.md
GEMINI.md                              GEMINI.md                 2      42
services\payments\AGENTS.override.md   AGENTS.override.md        2      46
AGENTS.md total across the tree: 109 bytes (under the 32 KiB Codex default)
flagged: 1

The exit code was 1 because one file was flagged, so the script can sit in CI as a guard against context files that quietly grow past the point where the docs say they stop working.

What I did not verify

The 200-line figure is Claude Code's guidance and the 32 KiB figure is Codex's default; neither vendor publishes a measured adherence curve, so the script flags against the documented numbers rather than any threshold I measured. I did not test how Cursor or Gemini CLI handle a file over their stated limits.