Context Management for AI Coding Agents

Context is the single biggest lever for agent performance. The same agent with better context produces dramatically better output. This guide covers the context hierarchy — what the agent knows and in what order — how to manage a finite context window, and the mistakes that waste it.

If you are new to agentic workflows start with Getting Started with Agentic Coding. The top of the hierarchy — project rules — is its own topic; CLAUDE.md Patterns covers how to write them, and Prompt Patterns covers what you ask in the moment.

The Context Hierarchy

From most to least impactful:

The key insight: level 1 is the highest-leverage investment. Ten minutes spent writing good project rules saves hours of correcting agent mistakes across sessions.

Level 1: Project Rules

Project rules are the highest-leverage context because they load on every session. But writing them well — the four-section structure (stack, key paths, build commands, boundaries), the NOT X pattern, and boundary rules that each trace to a real incident — is its own topic. CLAUDE.md Patterns is the full treatment; this guide assumes you have a CLAUDE.md and focuses on the levels below it: what to pull into a given session, and what to keep out.

One project-rules mechanism is worth calling out here, because it’s about context rather than conventions: workflow files. For complex recurring tasks, a dedicated step-by-step file gives the agent a procedure to follow instead of re-deriving it each session:

## Workflows
- .agent/workflows/deploy.md — deployment checklist
- .agent/workflows/upstream-sync.md — upstream sync procedure

Unlike a prompt typed into chat — which evaporates when the session ends — a workflow file is versioned, reviewable, and reusable. It’s persistent context for a task, the same way CLAUDE.md is persistent context for the project.

Context Window Management

The context window is finite. Strategies for staying within it:

Do:

• Read specific files, not entire directories
• Ask the agent to summarize large files before working with them
• Use prerequisites and related frontmatter to give the agent a navigation graph
• Break large tasks into phases (see Prompt Patterns)

Don’t:

• Paste entire file contents into the prompt when the agent can read them directly
• Keep old conversation branches alive — start fresh for new tasks
• Ask the agent to “remember everything” — it can’t, and trying wastes tokens

Anti-Patterns

Context Dumping

Pasting your entire codebase or large files into the prompt.

What happens: The agent gets overwhelmed, starts hallucinating file paths, and produces generic solutions that don’t match your actual code.

Fix: Let the agent read files selectively. “Read src/layouts/KBEntry.astro and then add a breadcrumb component” is better than pasting the 200-line file into your prompt.

Assuming Memory

Treating the agent like a colleague who remembers yesterday’s conversation.

What happens: “Continue where we left off” produces confused output because the agent has no memory of previous sessions.

Fix: Use CLAUDE.md for persistent context. Start each session with “Read the memory files and CLAUDE.md” to restore project context. The agent’s memory system (if available) bridges sessions, but only for things explicitly saved.

Vague References

“Fix that bug” or “update the thing we discussed.”

What happens: The agent guesses what you mean, often wrongly, and produces changes to the wrong file or the wrong bug.

Fix: Be specific. “Fix the null check in src/lib/kb.ts:42 that causes undefined when series is missing from frontmatter” gives the agent exact coordinates. File paths and line numbers are free precision.

Sources

• Anthropic, Claude Code: Memory
• Anthropic, CLAUDE.md best practices
• OpenAI, Custom instructions with AGENTS.md