Two files, one rule, two answers

CLAUDE.md files are "instructions you write to give Claude persistent context," and Claude reads them "at the start of every session."1

"CLAUDE.md and CLAUDE.local.md files in the directory hierarchy above the working directory are loaded at launch. Files in subdirectories load on demand when Claude reads files in those directories."1 Every file found is kept. "All discovered files are concatenated into context rather than overriding each other," ordered "from the filesystem root down to your working directory."1

AGENTS.md is read by Claude Code under one condition: "By default, Claude reads AGENTS.md only when you have no CLAUDE.md in your working directory or above it."1 A CLAUDE.md can import an AGENTS.md with @ syntax instead, and imports can nest to "a maximum depth of four hops."1

The two files do the same kind of job for different readers. In a repository that has both, a Claude Code session reads CLAUDE.md and not AGENTS.md, unless AGENTS.md is imported.

The documentation places both files on the advisory side of the line. "Claude treats them as context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook instead."1

A written rule in either file is read. It is not enforced.

My setup has four layers:

• a personal file that applies to every project (154 lines)
• the repository's file (404 lines)
• a file for each seat, meaning the folder a session is started in for one job, such as this article desk (92 lines)
• the task in front of the session

The personal file says which one wins: "The more specific layer wins," except that "a later layer may narrow a rule, never relax a safety or authority rule." It also says: "File recency does not establish precedence." A rule edited yesterday in a general file does not beat a specific one written last week.

Where a method needs more room than a summary, it gets one home. The troubleshooting method lives in a single document. The repository's CLAUDE.md carries a short summary of it and a tiebreak: "if the two ever disagree, TROUBLESHOOT wins."

The one rule that has to hold whatever a session decides, that frozen files are not written, is also enforced by a hook. On 24 September 2026 a session started in a subfolder turned out to have loaded every instruction file above it and none of the hooks. That is its own article: The rules loaded. The guard didn't.

The repository also has an AGENTS.md, for Codex sessions. Both files tell a new session how to work out which project it is on. A shared one-line pointer file records the last project launched.

The CLAUDE.md says to read that pointer: "If present, that's the active project for this session."

The AGENTS.md says: "Do not act on .active-project alone."

A Claude session in this repository reads the CLAUDE.md and never the AGENTS.md, because a CLAUDE.md exists.1 So on 24 September 2026 the two agents had opposite answers to the same question, and each was correct by its own file.

The personal file names this exact defect: "Two live statements of one rule is the defect that produced every drift in this estate." The documentation describes the single-agent version: "if two rules contradict each other, Claude may pick one arbitrarily."1 Here the two statements sit in files that different agents read, so neither agent ever sees the contradiction.

On 23 September 2026 I retired a rule for develop-ed.com: never name the tools or models in visitor-facing text. The rule lived in ten files:

• three instruction files at the root of the repository
• three of the site's own documents: the voice spec, the SEO checklist and the SEO plan
• two automated checks
• the profile schema
• the site's profile

The check's test fixtures changed with them. Every copy that was missed would have kept the old rule alive in the place it was missed.

The repository's CLAUDE.md is 404 lines. The documentation's guidance is to "target under 200 lines per CLAUDE.md file," because "longer files consume more context and reduce adherence."1 That is the vendor's statement. Nothing here has measured whether this file's length changes how reliably its rules are followed.

• Whether the four layers, or the 404 lines, change how reliably the rules are followed. There is no comparison and no measurement.
• How often the pointer contradiction changed what a session actually did. Unknown.
• Anything about how other teams arrange these files. Nobody has measured it here.