Part of Mechanisms of Vibe Coding

Mechanism: Context Budget

One-sentence definition

A context budget is a deliberate limit on what you load into the model’s window — files, history, rules, and tool output — so attention stays on the job instead of drowning in noise.

The problem

You @ the whole repo, paste three docs, attach the last hour of chat, and enable every rule file. The agent answers confidently but misses the one line in bootstrap.ts that actually matters. More context felt responsible; it was attention dilution.

Models have finite context. Irrelevant files compete with the goal. Old chat turns steer the model toward abandoned tangents. Huge diffs and log dumps push out the constraints you wrote at the start.

Symptoms:

• Agent “read everything” but fixes the wrong layer
• Responses reference files outside the task
• Slow replies and truncated middle sections of long threads
• Rules and goals from message one are ignored by message fifteen

How it works

Treat context like money: allocate before you spend.

1. Must-have — goal block, files directly edited, one anchor (README or types), failing test output.
2. Nice-if-stuck — related module, API spec — add only when the agent asks or fails twice.
3. Never by default — full repo search results, entire lockfiles, unrelated feature folders, long chat history from other tasks.

  Start minimal (goal + 1–3 files + verify output)
       │
       ▼
  Agent stuck or wrong layer?
       │
      yes ──► add ONE targeted file or doc ([progressive disclosure](/mechanism-progressive-disclosure/))
       │
      no ──► keep budget; do not @ more "just in case"

Budget pairs with scope fence: the fence says which job; the budget says how much the model sees for that job.

When to use it

• Every session, especially large repos
• After the agent cites irrelevant files or hallucinates structure
• Before @codebase or “index the whole project” prompts
• Long loops — re-send goal + constraints each pass instead of relying on ancient history

When not to use it

• Small single-file scripts where the whole project fits in one screen
• Architecture reviews where breadth is the task — but still cap logs and binary blobs
• When you have not written a goal yet — budget without direction just saves tokens, not quality

Failure modes

Kitchen-sink context — @ everything preemptively. Fix: Start with must-have only; add on evidence.

Starved context — One file when the bug is cross-module. Fix: Add the missing interface or caller, not the whole tree.

Zombie history — Old chat about Docker steers a health fix. Fix: New session or explicit “ignore prior topic; goal is X.”

Log flood — Pasting 500-line stack traces every pass. Fix: Trim to relevant frames; link to full log if needed.

Rule bloat — Ten rule files always on. Fix: Project-wide rules + task-specific constraints in the prompt, not every skill at once.

Minimal example

Context: Health endpoint fix — avoid loading the whole API.

Steps:

1. Must-have for pass 1:

– Goal + constraints block

– @src/health.ts @src/bootstrap.ts

– @health.test.ts

– Last test failure output (trimmed)

1. Do not @src/ root, Dockerfile, or @codebase on pass 1.

1. If the agent says it needs how startup runs, add only @src/server.ts on pass 2 — one file.

Done when: The fix lands without ever attaching more than five files in one session unless you can name why each was added.

Tool instances (optional deep-dive)

Portable idea above; this section is tool-specific. Date: June 2026.

Cursor

• Prefer specific @file over @codebase for bounded tasks.
• .cursorignore — keeps noise out of indexing (budget at rest).
• Rules / skills — keep always-on rules short; link to longer docs instead of inlining.
• New chat per task — cheapest way to reset history budget.
• Agent transcripts — long runs: re-paste goal block each loop pass instead of assuming the model remembers message three.

Other tools

Claude Code /compact, Aider file lists, RAG with top-k limits — all implement a budget; the mechanism is the same decision: what earns a slot in the window.

Related mechanisms

• Progressive disclosure — when to add files after minimal start
• Anchor files — what to almost always include
• Scope fence — which job the budget serves

Try it yourself

Exercise: Take your last agent session (or plan one). List must-have, nice-if-stuck, and excluded context items before sending message one. Cap must-have at five items.

You need: One real task; three minutes

Done when: You can justify each must-have in one sentence; excluded list is non-empty.