Managing context

The context budget is the mechanism. This chapter is the practice.

You manage context at two levels:

• Inside a session: hygiene that keeps a given run productive: what to include, what to prune, when to restart.
• Across sessions: the durable configuration that reloads on every run: AGENTS.md, CLAUDE.md, layered scopes, and Skills.

Both matter. The persistent layer sets the floor; session hygiene determines whether each run gets the best of it.

Inside a session

The model sees what’s in the window. Anything stale, conflicting, or irrelevant degrades output. A short list of rules-of-thumb:

• Start focused sessions for focused work. A long-running “scratch” session accumulates irrelevant context. When the task changes, start fresh.
• Let the harness compact when it needs to, but treat a freshly compacted session as a natural checkpoint to end or reframe.
• Watch for redundant tool calls. Reading the same file three times dumps the same tokens in three times. If you see Claude doing this, interrupt and steer.
• If the model starts “forgetting” concrete things (a path you just gave it, a constraint you stated), the context is either over-compacted or overloaded. Restart and re-state what matters.
• Summarize-and-continue. When a session has produced something useful but is getting long, close it with a summary commit or a short doc and start fresh with a link to that summary. You keep the gains; you shed the noise.

Across sessions: AGENTS.md and CLAUDE.md

AGENTS.md and CLAUDE.md are the permanent prompt. Claude Code loads them into every session in a project. They let you avoid re-explaining the same conventions, constraints, or local facts every run.

A quick note on the two names: CLAUDE.md is Claude Code’s native memory file; AGENTS.md is the cross-tool convention that Cursor, Codex, and others read. The common pattern is a one-line CLAUDE.md that imports AGENTS.md (@AGENTS.md), so every tool reads the same instructions.

The files layer:

• Project: AGENTS.md or CLAUDE.md at the repo root. Applies to sessions in that project.
• User: ~/.claude/CLAUDE.md and equivalents. Applies to every session you run, in any project.
• Enterprise / system: organization-wide policy layers, set by admins.

Most projects use the project-level file. The user-level file is useful for cross-cutting personal preferences (e.g., “I prefer concise commit messages,” “I’m on macOS”). Avoid putting project-specific content in user-level files, and vice versa.

What belongs

• Durable facts about the project: what it is, how it’s structured, the load-bearing conventions
• Hard constraints: don’t touch this directory, never commit generated files, use this database migration pattern
• Commands and paths Claude should know: where to run builds, where tests live, the deploy command
• Recurring corrections: guidance that came out of earlier sessions as a “rule” for the future

What doesn’t

• One-off task details: those belong in the prompt
• Transient state: what you’re working on today
• Full code: link out to files; don’t paste them
• Anything Claude can derive by reading the repo: Claude can grep; the file shouldn’t repeat obvious structure

Keeping them sharp

Every line in these files is taxed against the context budget on every turn. Treat them the way you’d treat a Dockerfile or a CI config: tight, deliberate, pruned.

• Split by concern. A single 5,000-line AGENTS.md is a smell. Break it into the main file plus linked topic-specific docs or Skills that Claude loads on demand.
• Prune when rules become obsolete. If a constraint no longer applies, delete it. Old rules confuse future sessions.
• Link out. When content is long-form (a full architecture doc, a style guide), link to it from AGENTS.md rather than embedding. Claude can read linked files when they’re relevant.
• Review periodically. Re-read your own AGENTS.md with fresh eyes and ask: is any of this noise?

Skills as the next layer

For more elaborate, load-on-demand context (workflows, templates, deep references), use Skills rather than stuffing everything into AGENTS.md. Skills load only when a matching task appears, which keeps the default context budget lean while still giving Claude access to the larger corpus.

The pattern: AGENTS.md for what Claude should always know. Skills for what Claude should be able to load when it’s relevant.

What good context actually gets you

A concrete example from writing this course.

I’m in a Claude Code session that’s been open for a couple of hours, iterating on /learn/ with a friend. The session already knows:

• It’s this repo, with this structure, and the /learn course is the current focus.
• I’ve given earlier feedback on which suggestions landed and which didn’t.
• Additions should update both the nav and the content, so the structure files (build-ssg.js, src/main.js) stay in sync with the chapters.
• I just said “we’re sitting down with my friend, doing the thing; I’ll be dumping freeform conversational notes into you.”

With that context loaded, I can double-tap the Wispr Flow key and just talk: rambling about terminals, Wispr, markdown viewers, the IDE of the future, whatever. Some of it is content worth keeping. Some is conversational filler. Some is throwaway. The transcript is messy.

And it works. Claude figures out what to keep, what to rephrase, and where to put it. Not because the prompt was precise (the prompt was a wall of freeform dictation) but because the context was well-primed. The model had enough scaffolding to tell signal from noise.

Resources

• Anthropic: Effective context engineering for AI agents
• Anthropic: CLAUDE.md memory docs