Context and Instruction Hierarchy

The context window is the agent's entire working memory. Not "like" working memory — it literally is the only thing the model sees. If a fact isn't in context right now, the agent doesn't know it, no matter how many times you said it last week. Managing what's in context, and where instructions live, is the operational core of running agents well.

What actually enters context in Claude Code

At session start and during work, the context window fills from these sources:

Source	When it loads	Notes
Enterprise/user CLAUDE.md (~/.claude/CLAUDE.md)	Session start	Your personal cross-project rules
Project CLAUDE.md (repo root, plus per-directory ones)	Session start; nested files as their directories are touched	The repo's standing orders — see CLAUDE.md and AGENTS.md
The conversation	Continuously	Every prompt, answer, and correction
Files the agent reads	On demand	Only what it chose to read — not the whole repo
Tool output	On demand	Test runs, build logs, grep results, command output
@file references and pasted content	When you provide them	Your manual context injection

Two consequences most people miss. First, the agent has not read your codebase — it has read the ten or thirty files it decided were relevant. If the critical invariant lives in a file it never opened, the invariant doesn't exist for this session. Repo navigability directly determines whether the agent finds the right files. Second, tool output is context too: a 3,000-line failing test log dumped into the window crowds out everything else, including your instructions from an hour ago.

Context rot

Long sessions degrade predictably. As the window fills, three things happen:

• Dilution — your original task statement is now a small fraction of the tokens; recent noise (logs, diffs, tangents) dominates the model's attention.
• Stale-state confusion — the window contains four versions of the same file from different edit stages; the agent occasionally reasons from an old one.
• Instruction decay — corrections made 200 messages ago effectively stop existing, and the agent regresses to the behavior you already fixed twice.

When the window nears its limit, Claude Code compacts: it summarizes the conversation and continues from the summary. Compaction preserves the gist and loses precision — the exact constraint you phrased carefully at message 30 may survive only as "user cares about error handling". Anything that must survive compaction must live in a file, because CLAUDE.md is reloaded, not summarized.

The instruction hierarchy

What wins on conflict: more specific and more recent wins in the moment — a direct conversational instruction ("in this task, ignore the deprecation warnings") overrides a general CLAUDE.md rule for this session. But the durable layers win over time: the conversation resets to zero, and CLAUDE.md is still there tomorrow. File contents sit at the bottom deliberately — they are evidence about what the code does, not instructions about what to do; a comment in some legacy file saying "always use callbacks here" should not outrank your spec, and usually the agent treats it accordingly (but not always — stale in-code guidance is a real contamination source worth deleting).

Why repeated corrections belong in CLAUDE.md, not chat: a correction in conversation is scoped to one session of one agent operated by you. The same sentence in the project CLAUDE.md is scoped to every session, every teammate, and every CI run, forever. Same typing effort, roughly 100× the leverage. This is the escalation rule of Prompts vs Specs applied to instructions: said it twice in chat → move it to a file.

Practical rules

Use /clear when the task changes and the accumulated context is noise for the new task — you finished the refactor, now you're writing docs. /clear wipes the conversation but re-reads CLAUDE.md, which is exactly the reset you want. Cheap, use it liberally.

Start a fresh session when the current one has gone bad in a way /clear won't fix: the agent is looping on a wrong approach (see Stuck Loops and Thrash), or context has rotted to the point where it's confidently misremembering the codebase. A fresh session with a good spec beats a long session with a corrected-fifteen-times conversation, every time.

What to persist where:

Knowledge	Home
Coding conventions, banned patterns, build/test commands, invariants	Project CLAUDE.md
Your personal style preferences across all projects	User CLAUDE.md
Feature requirements and acceptance criteria	Spec file, committed — see Writing Effective Specs
Architecture rationale and rejected alternatives	ADRs — see Decision Records
System behavior and module boundaries	Repo docs — see Docs as Memory
One-off task instructions	The prompt — and nowhere else

One sizing caveat: CLAUDE.md competes for the same window as everything else. Every line you add is a line of working memory spent on every task, relevant or not. Keep it to standing orders — rules that apply to most sessions — and push feature-specific detail into specs the agent reads only when needed.

Session hygiene checklist

• [ ] Task switch? /clear before starting the new one.
• [ ] Same correction twice this week? It goes in CLAUDE.md today.
• [ ] Long session getting weird? Don't argue with it — extract decisions to a file, start fresh.
• [ ] About to paste a huge log? Trim to the relevant failure first; the window is shared.
• [ ] Critical constraint for a multi-hour task? In a spec file, not at message 1 of a conversation that will compact.

Related

• Mental Models — the zero-memory model and the layered control stack this page mechanizes.
• CLAUDE.md and AGENTS.md — what belongs in the project instruction file and how to keep it lean.
• Prompts vs Specs — the escalation rule: chat is for pointers, files are for truth.
• Scope and Context Failures — what going wrong looks like when context management fails.
• Large Tasks — decomposing work so no single session outlives its context window.