If your agent skips instructions you put in CLAUDE.md, the file is probably too long and too specific. The fix is not louder emphasis — it is a shorter, more universal file, with everything else moved behind progressive disclosure.
Definition
CLAUDE.md — a project file (named AGENTS.md in some other tools) that Claude Code loads at the start of every session as standing instructions. It is the agent’s onboarding surface: agents start each session with no memory of your codebase.
What it costs
CLAUDE.md is not free background knowledge. It loads at session start and stays in context on every turn, so each line competes for attention with your actual task. Length is a tax, paid continuously.
A working target: HumanLayer keeps theirs under 60 lines, and ~300 lines is the common ceiling practitioners cite. Past that, expect the agent to start discounting the file.
Why it gets ignored
Two failure modes, both made worse by length:
- Relevance filtering. When much of the file reads as irrelevant to the task at hand, the agent is more likely to discount the whole thing — including the parts that did matter. Practitioners writing about Claude Code (HumanLayer, Builder.io) consistently report that non-universal, task-specific content raises the ignore rate.
- Instruction budget. Every instruction you add dilutes the others. Practitioners peg reliable adherence at roughly 150–200 instructions for frontier thinking models, and Claude Code’s own system prompt already spends about 50 before your file loads — so padding
CLAUDE.mdwith situational rules burns a finite attention budget on low-value lines.
The through-line: task-specific content in a file that loads for every task is the problem.
What to include (and exclude)
Anthropic’s best-practices guidance is to put in only what the agent can’t infer:
| Include | Exclude |
|---|---|
| Non-guessable shell commands | Anything obvious from the code or types |
| The project’s test runner | Restating existing docs |
| Code style that differs from defaults | One-off, task-specific steps |
| Repo etiquette and architecture decisions | Long examples better kept in a linked doc |
| Environment quirks and gotchas | Style rules a formatter can enforce |
A useful test: if a competent new contributor could figure it out from the repo in a minute, it doesn’t belong in CLAUDE.md. See keep CLAUDE.md to universal instructions.
A lean file that survives the relevance filter looks like this:
# CLAUDE.md
## Commands
- Test: <non-default test runner>
- Build: <non-guessable build command>
## Conventions
- <code style a formatter can't enforce>
## Architecture
- <one-line decision a newcomer can't infer>
@docs/architecture.md # pulled in only when referencedMove the rest behind progressive disclosure
Everything that isn’t universal still has a home — just not one that loads every turn:
@path/to/fileimports — pull in a doc only where referenced.- Skills — package a domain workflow the agent loads when the task calls for it.
- Child-directory
CLAUDE.md— scope instructions to the subtree they apply to, loaded on demand. - Separate reference docs — keep the big architecture map or PRD out of the always-on file.
This keeps the always-loaded surface small and high-signal, while the detail stays reachable exactly when it’s needed.
Don’t use the model as a linter
Style and formatting rules are cheaper and more reliable enforced by tooling — formatters, a Stop hook, or a slash command — than by instructions the agent has to remember every turn. Reserve CLAUDE.md for what only prose can convey.
Bottom line
A CLAUDE.md the agent actually follows is short, universal, and ruthlessly pruned. Treat it as the one always-loaded surface and push everything situational behind progressive disclosure — the same context-engineering discipline that governs the rest of the window.