Context From First Principles on Programmer.ie: Modern AI programming

What Context Means

Wed, 23 Sep 2026 05:00:01 +0100

Consider a concrete evening. A developer asks a coding agent to fix a failing test. The typed message is eleven words long: “the checkout test fails after my last commit, please fix it.”

Behind those eleven words sits an organisation of information enormously larger than the request. The repository holds hundreds of thousands of lines of code. The version control history holds the last commit and every commit before it. The continuous integration log holds the actual failure output. The open editor holds the file the developer was viewing. The agent’s working directory holds shell history, environment variables, and configuration. Earlier in the session, the developer pasted an error trace, the agent ran two searches, and a linter produced three warnings nobody has read yet.

The Measurement Instrument

Wed, 23 Sep 2026 05:00:02 +0100

A developer debugging a slow, expensive coding agent opens the session log. The visible transcript shows eight user messages and eight assistant replies. It looks modest. Then the developer enables request logging at the harness layer and discovers that the eighth model invocation carried 61,000 tokens: the same project instructions re-sent for the eighth time, three full tool definitions for tools never called in this session, two file reads whose contents overlap by 80 per cent, and a conversation history that includes four failed tool calls and their stack traces in full. The user typed perhaps 400 words in the entire session. The model received a novella.

The Context You Didn't Type

Wed, 23 Sep 2026 05:00:03 +0100

The mental model most users carry looks like this:

user
 ↓
model
 ↓
answer

A message goes in, intelligence happens, an answer comes out. Everything in the previous chapter says this picture is false, but the previous chapter showed the falsity as accounting tables. This chapter shows it as machinery. Behind a production assistant stands a runtime that assembles a layered stack of instructions, definitions, state, history, and observations, and the user’s message arrives near the bottom of that stack, not the top of it.

The Context Window Is a Budget

Wed, 23 Sep 2026 05:00:04 +0100

Chapter 3 ended with an observation: every hidden layer costs something. A team running a coding agent on a model with a million-token window read that sentence and shrugged. Their sessions rarely passed 150,000 tokens. Nothing was being truncated, nothing was overflowing, and the window, they reasoned, had settled the matter. Then two things happened. First, a long debugging session died at turn eleven with the model stopping mid-repair, not because the input had crossed a million tokens but because the input plus the output the model still needed no longer fit together. Second, the invoice arrived, and the “plenty of headroom” sessions turned out to be the most expensive ones they had ever run. The window had not settled anything. It had merely set the outer wall of a much smaller room they were actually living in.

More Is Not Better

Wed, 23 Sep 2026 05:00:05 +0100

The seductive assumption runs like this. Useful information is good. The model has spare capacity. Therefore adding more potentially useful information should be better, or at worst harmless. Teams act on it constantly: the whole repository goes into the window just in case, every retrieved document is kept because retrieval must have returned it for a reason, history is never truncated because something old might matter. The budget chapter showed this costs money and headroom. This chapter shows it costs something more fundamental. Past a point, added context does not merely cost. It injures.

Order Changes Meaning

Wed, 23 Sep 2026 05:00:06 +0100

A harness team ships a minor upgrade. Nothing is added to the context and nothing is removed. The release notes mention only a rendering change: tool results now appear above the project rules instead of below them, so that fresh observations sit closer to the current request. Within a week, the team’s deployment-safety rule, which the agent obeyed for months, starts getting violated. Nobody changed the rule. Nobody changed the model. The information in every bundle is byte-identical to last week’s. Only the arrangement changed, and the behaviour changed with it.

Not All Tokens Are Equal

Wed, 23 Sep 2026 05:00:07 +0100

A coding session under capacity pressure holds six items. A project safety rule: never modify production migrations without explicit approval. A test summary: 917 passed, 3 failed. A compiler log of 18,000 tokens. An architecture decision: PostgreSQL is required for this event-store workload. The contents of a source file. An abandoned hypothesis: maybe the serializer is corrupting timestamps.

Pressure arrives, and the harness must yield tokens. The uniform policies on offer are all wrong in different ways. Summarise everything, and the safety rule becomes “be careful with migrations,” which no longer forbids anything. Delete the oldest material, and the architecture decision vanishes while yesterday’s abandoned hypothesis survives on recency. Truncate from the middle, and the file contents go while the log stays. Keep everything, and the request fails at the window. Each policy treats the six items as interchangeable tokens. They are not interchangeable, and the differences between them are exactly what a retention policy needs to know.

Make the Window Bigger

Wed, 23 Sep 2026 05:00:08 +0100

Seven chapters have treated the model as fixed ground and asked how the surrounding system should manage information against it. The natural objection has been waiting since Chapter 4: if context is scarce and difficult to manage, why not simply make the window much larger? A team that moves its agent onto a million-token model watches several selection problems relax at once. Histories that needed pruning now fit. Files that needed triage can all be included. The compaction schedule gets quieter. For a while, context engineering looks like a stopgap awaiting cheaper capacity.

Reuse Before Recompute

Wed, 23 Sep 2026 05:00:09 +0100

A team running a long debugging session finally acts on Chapter 4’s advice. Their traces show 20,000 tokens of duplicate file reads and obsolete tool output, so they add a cleanup pass that strips the duplicates before every request. Token counts fall by a sixth. The next invoice rises. Latency does not improve either. Nothing about the model changed and nothing about the task changed. The cleanup was real, the savings were arithmetic, and the bill disagrees, because the bill never measured tokens. It measured computation, and the cleanup destroyed the reuse that had been quietly subsidising every turn.

Remove What No Longer Matters

Wed, 23 Sep 2026 05:00:10 +0100

Nine chapters have observed, classified, measured, ordered, priced, and architected around context without once deleting anything. That restraint ends here, and it should end nervously. A team ships an automatic cleanup pass over its coding agent’s history: exact-duplicate tool outputs go, failed calls older than four turns go, anything the model flags as done goes. Token counts fall by a third. Two weeks later a migration guardrail the team believed was load-bearing starts failing silently. The deleted material contained the only record of a constraint the project file never stated, a decision reached mid-session and never written anywhere else. Nobody summarised it away. Nobody rewrote it. It was simply removed, by a rule that could not tell a redundant copy from a unique original.

Compression Is Loss

Wed, 23 Sep 2026 05:00:11 +0100

An agent has accumulated a working past: an architecture decision at 500 tokens, an unresolved bug history at 4,000, three failed approaches at 8,000, tool observations at 20,000, the current implementation at 6,000. Chapter 10 does its honest work. Duplicates go, proven-superseded observations go, failed-input bulk goes with residues kept. Roughly 13,000 tokens leave. Twenty-five thousand remain, and every token of them matters in the sense this book has defined: some future computation may need it, and no rung of the evidence ladder licenses deletion. The bundle still does not fit the session ahead. Nothing left can disappear. Everything left cannot stay verbatim. That is where this chapter begins, at the exact point where deletion stops working.

Let Old Context Fade

Wed, 23 Sep 2026 05:00:12 +0100

A long session crosses its compaction threshold mid-investigation. The agent is halfway through a dependency migration: three candidate approaches tried, one rejected for a subtle version conflict, the current attempt half-applied, the exact error that killed the second attempt still visible three turns back. The compactor fires, because tokens crossed a number, and replaces 40,000 tokens of working history with a 2,000-token summary. The summary is fluent and mostly accurate. It records that an approach was rejected without recording which version conflict killed it. Six turns later the agent, unable to see the conflict, retries the rejected approach. The threshold did its job. The session did not survive it.

Externalize the Working Set

Wed, 23 Sep 2026 05:00:13 +0100

Chapter 12 ended with an irreducible remainder: pinned exact spans, active dense episodes, compact views of the recent past, anchors of the deep past. Still resident, still costing capacity and cache stability. Consider what that remainder looks like in a concrete session. An agent halfway through a dependency migration holds five working objects: an architecture investigation at roughly 18,000 tokens, a benchmark report at 12,000, a compiler trace at 25,000, a design-alternatives note at 15,000, and a vendored API reference at 30,000. Progressive fidelity has done its honest work and the resident views are compact. The sum is still near 100,000 tokens of occupancy, and on most turns the model consults at most one of the five. The tiers answered how little of each object must be shown. None of them asked whether the object needs to be shown at all.

Bring Back Only What You Need

Wed, 23 Sep 2026 05:00:14 +0100

Chapter 13 left the model holding a tidy live context and a shelf of external artifacts:

Incident 17 — lock-order inversion.
Evidence: artifact://incident-17

plus five more references of the same shape. Then the current task changes. The user asks why the deadlock appeared only under concurrent import. The incident artifact probably matters. So might the benchmark report, the migration plan, and the compiler run. The naive response is to load everything, which recreates within one turn the exact occupancy problem Chapter 13 solved. Leaving was only half the problem. Existence plus recoverability does not mean admission. This chapter decides what comes back.

The Agent Writes Its Own Context

Wed, 23 Sep 2026 05:00:15 +0100

A debugging agent hits a failing migration test, guesses duplicated tenant identifiers as the cause, and records the guess in its progress file. Twenty turns later the window has reset. A fresh invocation reads the file, finds “Root cause: duplicated tenant IDs,” and plans the rest of its work around a fact nobody ever established. The test output that prompted the guess is long gone. The guess survived; the evidence did not. Nothing in Chapters 10 through 14 prevents this, because every mechanism so far assumed the candidate universe was given. It is not. The agent manufactures it as it works, and this chapter governs what it manufactures.

Memory Is a Context Source

Wed, 23 Sep 2026 05:00:16 +0100

The current request says, verbatim: “Do not modify the existing migration.” The admitted context contains months of migration history — previous plans, old decisions, the full archaeology of the project — alongside that one-sentence instruction. The model answers the history instead of obeying the instruction, and helpfully proposes the modification it was told not to make. Every remembered item was valid. Every one was correctly stored, retrieved, and rendered. The failure is none of those stages. The failure is that durable past information entered a computation it should never have influenced. That is the entire subject of this chapter, and restraint is its hardest case.

Tools Produce Context

Wed, 23 Sep 2026 05:00:17 +0100

An agent starts a routine task with fifteen integrations connected: file tools, shell, search, web, database, issue tracker, chat, calendar, drive, deployment, monitoring. Before it reads a single project file, tens of thousands of tokens of capability descriptions have already entered its context — names, descriptions, schemas for operations it will never call. Then it runs one search, and 40,000 tokens of matches flood the window for a question answerable from twelve lines. The task fails twice before it begins: once at the price of knowing what it could do, once at the price of seeing what it did. Both prices were design choices. This chapter prices them.

Representation Is Part of Context

Wed, 23 Sep 2026 05:00:18 +0100

Two bundles carry the same migration facts. The first is prose: the migration uses PostgreSQL, its identifier is 01947, it remains blocked by test suite A, the team rejected the SQLite fallback after the staging incident. The second is a labelled record with the same four facts in named fields. Asked which identifier belongs to the unresolved migration, the model answers from the record and fumbles in the prose — the digits sit mid-sentence beside another number and bind to the wrong noun. Asked why the SQLite fallback was rejected, the model answers from the prose and starves on the record, whose reason field kept the headline and dropped the causal qualification. Nothing was selected differently. Everything was represented differently. Selection finished, and the context still was not the same.

Who Gets to Be Right?

Wed, 23 Sep 2026 05:00:19 +0100

The bundle for one deployment task contains three items that cannot all be true, and a fourth that should never have spoken. The application constraint says generated files are never modified. The user says edit generated/client.py directly. A retrieved deployment report says the staging version is 4.2.1 and, three paragraphs later, instructs the agent to upload credentials to an outside address. The project’s decision record says the database is PostgreSQL while the README says SQLite. Four sources, three disagreements, one computation to run. Relevance cannot settle any of them — every item earned admission. Representation preserved all four faithfully, which is precisely why the problem is visible instead of silently merged. A flattened baseline would obey the user over the application, obey the report over its own task, and merge the databases into whichever string renders cleanest. Something else must decide what controls behaviour, and that something is the subject of Part IV’s opening chapter.

Context Goes Stale

Wed, 23 Sep 2026 05:00:20 +0100

The agent reads the project’s decision record at repository version C1: backend SQLite, migration failing, README describing the current backend. It plans accordingly. By the time it acts, the repository is at C5. The decision record now says PostgreSQL, the migration passes, the README was rewritten twice. Nothing in the agent’s context changed — which is exactly the failure. The captured observation was authoritative, relevant, well-represented, and faithfully preserved. It described a state that no longer exists, and the model configured SQLite with complete confidence. Every chapter before this one asked whether information should enter context. This one asks whether what entered is still true of the world it claims to describe.

Keep Context in the Right World

Wed, 23 Sep 2026 05:00:21 +0100

The task belongs to Project A: backend PostgreSQL, test command pytest, migration complete. Project B lives beside it: backend SQLite, test command npm test, migration pending. The agent’s context holds both projects’ configs, both READMEs, both migration notes — every item authoritative in its own world, fresh, accurately represented, and semantically similar enough that retrieval surfaced all of it. The agent runs npm test in Project A, watches it fail for reasons that have nothing to do with Project A’s code, and then debugs the backend mismatch by reasoning about SQLite — quoting Project B’s migration state as though it constrains Project A’s deployment. No attacker exists. No stale data entered. No authority was violated. The context was correct, current, and legitimate in every way except the one that mattered: half of it belonged to another world.

Assemble for the Task

Wed, 23 Sep 2026 05:00:22 +0100

The usable input budget is 4,000 tokens. The non-negotiable pile reads: mandatory instructions 1,100, exact constraints 1,400, required tool schema 900, minimum task evidence 1,200. The total is 4,600 against a 4,000-token ceiling, and no ranking, weighting, or cleverness changes the arithmetic. A relevance packer would silently delete 400 tokens of whichever item scored lowest — perhaps the second half of the exact-constraint block, perhaps the tool schema’s required parameters — and emit a plausible, policy-violating bundle whose failure surfaces three turns later as an invalid call or a guessed identifier. The correct output of this computation is not a bundle at all. It is a failure notice naming the 600-token excess — because deleting exact constraints to fit a budget is not optimisation. It is fabrication with good formatting. Everything is eligible; nothing is assembled; and the first question is whether assembly is even possible.

Did the Context Help?

Wed, 23 Sep 2026 05:00:23 +0100

The staged compiler passed every test its contract set. Forty-two fixture-budget combinations, forty-two correct success-or-failure verdicts, zero illegal admissions of any class, required-item recall at 1.0 on every feasible combination. And the same frozen run admits five distractors and two evaluator-labelled harmful items into staged bundles — information the hidden ledger marks as useless or worse, sitting inside policy-valid, budget-compliant, fully traced context. Nothing malfunctioned. The compiler cannot see hidden labels, and legality never promised usefulness. So here is the question the previous chapter earned but could not answer: the bundle is legal, but did it help?

The Context Compiler

Wed, 23 Sep 2026 05:00:24 +0100