# Keep CLAUDE.md to universal instructions

> Put only universally applicable instructions in CLAUDE.md; task-specific content raises the odds an agent treats the whole file as noise and ignores it.

URL: https://bartlomiejkrupa.dev/notes/claude-md-universal-only/
Category: rule | Updated: 2026-10-07
Summary: Put only universally applicable instructions in CLAUDE.md; task-specific content raises the odds an agent treats the whole file as noise and ignores it.

Put only universally applicable instructions in `CLAUDE.md`. Task-specific or situational content raises the chance the agent treats the whole file as noise and ignores it - the failure mode broken down in [why agents ignore your CLAUDE.md](/articles/why-agents-ignore-your-claude-md).

## Include

- Non-guessable shell commands and the project's test runner.
- Code style that differs from language defaults.
- Repository etiquette, architecture decisions, and environment gotchas.

## Exclude

- Anything the code, types, or existing docs already make clear.
- One-off, task-specific steps - pass those in the prompt or via progressive disclosure (skills, child-directory files) instead. `@imports` organize a file but don't save context - imported files still load at launch.

## Why

`CLAUDE.md` loads at the start of every session and consumes context on every turn. A short, universal file stays high-signal; a bloated one dilutes the instructions that matter. That's [context engineering](/notes/context-engineering) - same discipline, one file, zero exceptions.

Sources:
- Best practices for Claude Code: https://code.claude.com/docs/en/best-practices
- How Claude remembers your project: https://code.claude.com/docs/en/memory