Context engineering basics

The context window is the fixed amount of text a model can consider in one request. Everything the agent knows in a given moment lives there: your instructions, the conversation, file contents, tool definitions, and tool results. Managing it well is most of the difference between an agent that stays useful and one that gets worse as the session goes on.

What is actually in there

On a typical request the window holds:

• The harness's own system prompt
• Your project instructions, from CLAUDE.md or AGENTS.md
• Definitions for every available tool, including every MCP server you connected
• The conversation so far
• The contents of every file that has been read
• The output of every command that has been run

That last item is the one people underestimate. A single command dumping a long log, or reading one large generated file, can consume more of the window than an entire conversation.

Why quality drops on long sessions

Two things happen.

The window fills. Once it is full, something must be dropped or summarised. Whatever gets dropped is knowledge the agent no longer has, and it does not necessarily know it is missing.

Attention spreads thin. Even below the limit, models attend less reliably to information buried in the middle of a very long context. An instruction you gave forty messages ago carries less weight than one given just now.

The practical symptom is familiar: the agent starts strong, then begins forgetting your conventions, re-reading files it already read, or repeating a mistake you corrected earlier.

What to do about it

Start fresh sessions often. The single most effective habit. When you finish a task, start a new session for the next one. Carrying an hour of unrelated history into a new task helps nothing.

Put durable knowledge in files, not in conversation. Anything you would have to repeat belongs in CLAUDE.md. It gets loaded fresh every session and never gets summarised away.

Be specific about files. "Fix the bug in src/auth/session.ts" is far cheaper than "find and fix the session bug", which may read a dozen files first.

Do not connect MCP servers you are not using. Every server's tool definitions are in the window on every request, whether used or not.

Watch what commands print. Piping a long output through head, or asking for a summary rather than a full dump, keeps a single command from eating the window.

Break large tasks into separate sessions. Three focused sessions produce better work than one long one, and cost less.

Tokens and cost

A token is roughly three quarters of a word in English. Code tokenises less efficiently, closer to two or three characters per token.

Cost follows the window. Every request bills for the whole context, not just your new message. This is why a long session gets progressively more expensive per message, and why a fresh session is cheaper as well as better.

Many providers offer prompt caching, which charges less for the unchanged prefix of your context. It rewards keeping the stable parts, such as instructions, at the front and the changing parts at the end.

Signals that you should restart

• The agent re-reads a file it read earlier in the session
• It reintroduces a bug you already had it fix
• It stops following a convention it was following at the start
• Responses get slower and vaguer

None of these mean the model is broken. They mean the window is crowded. Start a new session and give it the specific context for the next task.