How to Manage Context Budgets Across Multi-File Projects

A context budget is the deliberate allocation of your AI tool's context window across project rules, file contents, conversation history, retrieval results, and your latest message. Modern windows hold 200K to 1M tokens, but output quality drops well before you fill them. The practical target on most tasks is 30 to 60 percent capacity; reserve the rest as headroom for the model to think in. Spending the budget intentionally is what separates AI-assisted coding that ships from AI-assisted coding that drifts.

This piece is the part of context engineering people skip because it sounds boring. It is actually where the largest performance gains hide on real projects. We are going to walk through token math for a representative Next.js plus Supabase project, the decisions that move the budget most, and the small habits that keep your context lean.

Why Token Budgets Matter Even With Huge Windows

The intuition most people start with is wrong. They reason: "Claude can take a million tokens, my project is 200K tokens, so I can just give it everything." Mechanically true. Practically, output quality has degraded long before you hit the ceiling.

Two effects are at play. The first is "lost in the middle," a well-documented attention pattern where models pay more reliably to information at the start and end of a context window than to information stuck in the middle. As the window fills, the middle gets bigger, and more of your important information disappears into a low-attention zone. The second is the cost of doing useful work inside the window. Reasoning, planning, and tool calls all consume tokens. If your context is already 80 percent full, the model has no room to think. It writes shallow answers because there is no air left.

The result is a curve, not a cliff. At 30 percent capacity, quality is at peak. At 60 percent, you are still strong. By 80 percent, drift becomes noticeable: the model contradicts earlier decisions, misses details in the file you @-mentioned, and gives flatter answers. Above 90 percent, you are flying with one wing.

This is true on every model in 2026. Long context training has improved the situation but not eliminated it. Treat the window as a budget, not a bucket.

The other reason to budget is cost, although it matters less than people think. A round-trip on Claude Opus at 200K tokens costs perceptibly more than the same round-trip at 50K tokens. If you make 50 round-trips a day, that is real money. But the quality gap is the bigger argument. You are not budgeting tokens to save dollars; you are budgeting to save attention.

A Real Example, A Next.js Plus Supabase Project

Let us walk through what this looks like on a representative project. Imagine a small SaaS, maybe 60 files, written in Next.js 16 with the App Router, Supabase for database and auth, Tailwind for styling, Drizzle for the ORM. About 8,000 lines of code total. You are debugging a bug in the checkout flow.

Here is what fills the window on a careless session, with rough token estimates:

• System prompt and tool definitions: 2,000 tokens
• CLAUDE.md, sloppy version (everything you ever thought of): 8,000 tokens
• Codebase indexer auto-pulling 30 files: 22,000 tokens
• 90 minutes of conversation history from earlier this morning: 18,000 tokens
• Three more files you @-mentioned: 6,000 tokens
• Your message: 200 tokens

Total: about 56,000 tokens before the model has done any work. On a 200K window that is 28 percent capacity, sounds fine. But of those 56K tokens, maybe 8K are actually relevant to the checkout bug. The rest is noise that competes for attention.

Now the deliberate version of the same task:

• System prompt and tool definitions: 2,000 tokens
• CLAUDE.md, lean version with imports: 3,000 tokens
• Four files I actually need (checkout component, cart utility, server action, schema): 8,000 tokens
• Fresh conversation, just opened for this bug: 5,000 tokens
• My message: 300 tokens

Total: about 18,000 tokens. The model gets the same problem, with the right context, on a much leaner stack. In practice the deliberate setup produces a better debugging answer in fewer turns, not because the model is "trying harder" but because the relevant signal is now a much larger fraction of what it is reading.

The numbers above are rough. The point is the ratio: with the same task, the careless setup eats 3x the tokens and produces worse output. Multiply that across 30 sessions a week and the difference is enormous.

Decisions That Move The Most Tokens

A few decisions account for most of the variance. If you only change three things this week, change these.

Decision one, prune CLAUDE.md aggressively. Most CLAUDE.md files in real repos are 2 to 4 times too long. Sections nobody references anymore. Style guidance that has been baked into ESLint rules. "Helpful" examples that are now stale. A tight CLAUDE.md is 200 to 500 lines and reads like a one-page brief. If yours is 3000 lines, half of it is dead weight.

Decision two, scope files explicitly, not implicitly. Tools like Cursor's codebase indexing and Claude Code's auto-file-read are convenient but expensive. They pull more files than you actually need on most tasks. Turn them off (or restrict their scope) and rely on @ mentions for the files that matter. The rule of thumb that holds up well: 3 to 5 files per task is plenty. If you find yourself referencing more than 7, the task is too big and should be broken up.

Decision three, retire conversations. A 90-minute conversation can carry 30K to 60K tokens of stale history that was never the bottleneck for the current question. Closing the conversation and opening a fresh one with the same files is one of the fastest quality boosts you can apply mid-session. The reflex to "keep this thread going so it remembers" is almost always wrong. The thread is not remembering anything useful; it is dragging.

The combined effect of these three decisions is usually a 50 to 70 percent reduction in tokens used per task with no loss of relevant information.

Keeping The Conversation Lean

A handful of micro-habits help inside an active session.

Summarize and reset. When a conversation has produced a real result (a working function, a clear plan), open a new conversation, paste a 5-line summary of what was decided, and continue from there. The new conversation starts at maybe 4K tokens instead of 40K. The model is faster, sharper, and will not contradict the old conversation because the old conversation is no longer in front of it.

Use diffs, not full files. When you want to discuss a change, paste the diff, not the whole 600-line file. The model reasons about changes well from diffs. Most of the file's 600 lines are not relevant to the change you are asking about.

Drop tool definitions you do not need. Some tools (Claude Code, Cursor) load every available MCP tool's definition into context whether you use it or not. A heavy MCP loadout can eat 10K to 20K tokens just on tool definitions. If you have 14 MCP servers configured and you are debugging a CSS issue, disable the ones that are irrelevant for the session. Most editors let you toggle servers on and off per project.

Watch the indicator. Every modern editor shows you a context usage bar somewhere. Cursor displays a percentage in the chat composer. Claude Code surfaces it in /cost. Glance at it occasionally. If you are running at 70 percent and the task is not yet done, that is a signal to summarize and reset, not to push through.

The point of these habits is not perfection. The point is to feel the budget the way a writer feels the word count, without measuring every sentence. Once you have run the math on a few real sessions, the intuition takes over and you stop having to think about it.

There is a more advanced version of this mistake worth flagging. Some teams set up sophisticated retrieval pipelines and then paste the retrieval output into context indiscriminately. The retrieval system is "smart," so they trust everything it returns. Retrieval has its own precision-recall trade-off; it returns plausibly-relevant chunks, not certainly-relevant ones. Filter your retrieval output the same way you filter manual file selection. Three carefully-chosen retrieved chunks beat fifteen plausible ones.

What This Means For You

Context budgets are the unglamorous half of context engineering. The flashy half is project rules files and MCP servers. The boring half is the discipline that keeps your context lean enough for the rules and servers to actually pay off.

• If you are a senior developer, run the math on one of your typical sessions. Pull up Claude Code's /cost or Cursor's context indicator on a real task. You will probably find your context is 2 to 3 times bigger than the task warrants. The fix is mostly subtraction, not addition.
• If you are an indie hacker, the highest-impact move is retiring conversations more aggressively. You probably have a habit of letting threads run for hours because "the AI already knows the project." It mostly knows the project from CLAUDE.md, not from chat history. Test the theory by closing a long thread and opening a fresh one; output quality will usually go up.
• If you are leading a small team, write a one-page "context budget" doc next to your CLAUDE.md. Two lines per file type ("which 3 files do you reference for a checkout bug? which for an auth bug?"), one habit per developer ("retire conversations after each merged PR"). It saves the team a quarter of avoidable AI overhead.
• If you work in a large monorepo, context budgets become the central skill. The window will not hold the whole monorepo and never should. Investing in good @-mention discipline, a tight CLAUDE.md per package, and one MCP server that exposes search across the rest is the only setup that scales.

The practitioners who feel like AI tools are getting magically better in 2026 are mostly the ones whose context budgets got tighter, not the ones whose models got smarter. Tighten yours and the same tools you have today will start producing noticeably better work.