1.3 · Context Engineering

1.3 · 30 min

Context Engineering

Two hours into a session, Claude starts violating a rule you stated plainly at the beginning. It renames things you told it not to touch. It re-reads files it already read and reaches different conclusions. You did not change anything, and neither did the model. What changed is the context window: it filled, and the instruction you typed at minute one is now a needle in two hundred thousand tokens of haystack. This lesson is about the single highest-leverage skill in agentic work: deciding what is in the window, and when.

Anatomy of the window

Everything the model sees in one call travels through one channel: the context window. There is no side channel, no persistent brain state between calls, no "it remembers you". If information is not in the window, it does not exist for this inference. Claude Code's docs enumerate what fills it: system instructions, CLAUDE.md files, auto memory, the conversation history, file contents from reads, and command outputs.

one context windowSYSTEM PROMPTthe harnessCLAUDE.mdyour rulesAUTO MEMORYits notesloads atstartCONVERSATIONprompts, repliesTOOL RESULTSfiles, outputfills asyou workheadroomcompactionsummarizes,loses detailyou controlaccumulates

The blocks at the top load at session start, before you type anything: the harness's own system prompt, your CLAUDE.md rules, and auto memory, the notes Claude keeps about your repo (its first 200 lines or 25KB load every session, per the memory docs). Everything below accumulates as the loop runs, and here is the imbalance that surprises people: the conversation you type is a sliver. Tool results dominate. One read of a large file can outweigh your entire dialogue. Run /context in any session and look at the actual proportions; the command exists precisely because operators consistently misestimate them.

Lesson 1.1 gave you the reason this is a problem and not just an inventory: attention. Every token in the window competes for a finite attention budget, and the n squared pairwise structure of the transformer means the budget stretches thinner as the window fills. Anthropic's engineering guidance names the consequence context rot, citing needle-in-a-haystack research: as token count grows, the model's ability to accurately recall information from its own context decreases. Not at a cliff. Gradually, then noticeably.

clear here/clear or /compactoutput qualitycontext fill0%50%100%instructions holdforgets rules,repeats mistakesauto-compactfires latehealthyact nowdegrading

Where exactly the curve bends varies by model and task, and the honest answer is nobody will hand you a universal number. The operational position this course takes: treat the second half of the window as suspect territory. When a session's context is past roughly half full and you are starting anything new, clear first. You lose the cost of re-establishing state; you dodge working in the degraded zone. That trade is nearly always worth it, and the operators who disagree are usually the ones whose sessions produce the mystery failures this lesson opened with.

Compaction: the safety net that eats detail

Claude Code does not let a full window kill your session. Per the docs, as you approach the limit it manages context automatically: older tool outputs get cleared first, then the conversation is summarized if needed. Your requests and key code snippets survive; detailed instructions from early in the conversation may not. That sentence is from the docs, and it should worry you exactly as much as it sounds like it should.

A summary is lossy by design. What survives compaction depends on how content got into the window in the first place, and the docs spell out the split: the system prompt is untouched, CLAUDE.md and auto memory are re-injected fresh from disk, but everything that lived only in conversation history, including your carefully worded one-off instructions and any rules that loaded mid-session, gets compressed or dropped. The rule you typed at minute one has no disk to come back from.

This asymmetry is the placement principle in disguise, and it is the most practical sentence in this lesson: durability comes from disk, not from saying it earlier. An instruction that must survive the whole session belongs in CLAUDE.md, which resurrects after every compaction. An instruction for this task only belongs in the prompt, where mortality is fine. Reference material belongs in files, fetched when needed, because a file can be re-read after compaction but a paste cannot.

You also get manual controls, and they beat the automatic pass because you know what matters and the summarizer guesses. /compact focus on the auth bug fix compacts now, keeping what you named. /clear wipes the conversation entirely: the right move between unrelated tasks, and this course's default. One task, one session, clear aggressively.

Retrieval versus stuffing, and the just-in-time principle

The last piece is strategy: given a body of knowledge the task might need, do you push it all in up front (stuffing) or let the agent pull pieces as needed (retrieval)?

Anthropic's context-engineering post describes where the field landed. Instead of pre-loading everything, effective agents maintain lightweight identifiers (file paths, queries, links) and load data just in time, using tools. Claude Code itself is the worked example: it does not index your repo into the window at startup. It keeps CLAUDE.md resident, and greps, globs, and reads its way to everything else on demand. Each retrieved piece arrives when it is relevant, spends attention only while needed, and, in the post's phrase, the approach mirrors how humans use file systems and bookmarks instead of memorizing corpuses.

Stuffing is not wrong everywhere; the post explicitly endorses hybrids, front-loading stable, always-relevant material for speed while exploring the rest just in time. That is precisely what CLAUDE.md is: your deliberate choice of what earns permanent residence. The failure mode is making that choice lazily, stuffing "everything that might help" into permanent context, and paying attention tax on all of it, every token, every iteration, all session long.

Lablab-1-3Poison a session, then run it clean

Goal: Experience context rot directly by burying an instruction under junk context, watching it fail, and comparing against a clean session.

Prereqs: the agentic-practice repo. This lab deliberately wastes tokens; that is the point.

  1. Start a fresh session. Give one clear standing instruction as your first message: "For the rest of this session: every function you write must have a JSDoc comment, and you must never modify parse-duration.ts."
  2. Now poison the window. Have Claude read large, irrelevant content: ask it to read node_modules/.package-lock.json or another large file, summarize a long README from a URL, generate a 300-line changelog for an imaginary project. Two or three big reads is enough. Run /context and note how full the window is and what is filling it.
  3. Bury the instruction further: do one unrelated small task (a helper function in a new file). Then dispatch the real work: "Refactor the duration parsing so units are defined in a lookup table. Add a formatDuration function too."
  4. Audit the result against your minute-one instruction: JSDoc on every function? Did it touch parse-duration.ts? Record what survived and what did not in context-lab.md.
  5. Run /clear. Re-issue the standing instruction and the same dispatch back to back, nothing in between. Audit again, and write the comparison: same model, same instructions, different window.

Verify

  • /context output from the poisoned session showing substantial fill from junk reads (you know what is in there because you put it there).
  • A written record of at least one instruction violation or quality drop in the poisoned run.
  • The clean run honoring the same instructions, or, if both runs behaved, a written note that your poisoning was too gentle plus a second, heavier attempt. Degradation is probabilistic; absence in one draw is not absence.
>Troubleshooting
  • The poisoned session behaved perfectly: you under-poisoned. Modern models degrade gradually; a few thousand tokens of junk is not a burial. Read genuinely large files, several of them, and put more turns between the instruction and the task.
  • Claude refused to read the junk ("this seems irrelevant"): fair, and itself a lesson in agent judgment. Insist ("read it anyway, I need it summarized"), or use several medium files instead of one absurd one.
  • You hit auto-compaction mid-lab: even better. Ask Claude what your minute-one instructions were and watch what the summary preserved. Note it in the comparison.

Where it breaks

The predictable failure is ignoring all of this until quality visibly degrades, then compacting and continuing in the same swamp. Compaction recovers space, not fidelity; the summary of a confused session is a confused summary, and Lesson 1.5 has a name for what you are doing when you keep working on top of one. When a session has gone sideways, the professional move is almost always /clear plus a better opening dispatch, not another lap on degraded context.

The subtler failure is CLAUDE.md bloat. Once operators learn that CLAUDE.md survives compaction, everything migrates there, and the file swells into a thousand-token tax paid at the top of every session, mostly for rules irrelevant to the task at hand. The memory docs push the same direction this course does: specific, concise instructions, structured for scanning. If a rule does not need to hold in every session, it does not live there. Lesson 2.2 turns that into a full discipline.

Knowledge check

Knowledge check

Q1Which placement is right for each of these three: (a) 'never commit directly to main', (b) 'use snake_case for this one migration file', (c) the 40-page API reference for a service the task might touch?
Q2Deep into a long session, auto-compaction runs. Which of your instructions is at real risk of being gone afterward?
Q3Claude just started ignoring a constraint it honored for the first hour, and /context shows the window nearly full. What is the course's recommended move?
Q4Why does Claude Code grep and read files on demand instead of loading your whole repo into context at session start?

Sources