Context Engineering
Updated
AdvancedWhat you'll learn
~20 min- Explain context rot and budget a session by window fill
- Structure CLAUDE.md / AGENTS.md memory files that actually constrain behavior
- Use compaction, just-in-time retrieval, and note-taking to keep week-long projects coherent
It is Tuesday afternoon. You open a new session and ask the agent to extend the feature you built Monday. It generates something that contradicts the architecture decision you made two days ago — the one you spent 40 minutes deliberating over in last Friday’s planning session.
The agent is not stupid. It never saw that decision. Your context window expired.
That is context rot. And fixing it is not about writing better prompts — it is about engineering the information that reaches the model.
What context engineering actually is
Anthropic defines context engineering as curating the smallest possible set of high-signal tokens for each agent call. Not the most complete record of everything that ever happened. Not a wall of documentation preloaded at session start. The minimum set needed to do the next unit of work correctly.
This matters because every frontier model degrades as the window fills. Chroma’s research confirmed it across models: quality drops measurably as context grows, well before you hit the token ceiling. More tokens do not mean better answers — past a certain point they mean worse ones.
The practical corollary: a focused session can outperform a longer one when the extra context adds irrelevant information.
The Vibe Coding Reference already covers the effective-context rule of thumb and the /clear vs /compact decision table — bookmark that cheat-sheet and come back to it. This lesson explains why degradation happens and goes deeper on the four levers that prevent it.
The four levers
1. Compaction
When a session accumulates dead weight — failed approaches, long error traces, exploratory tangents — compaction distills the thread into a summary the model can reason from efficiently.
/compactClaude Code and Codex CLI both document /compact, and Claude Code takes a focus after it (/compact keep the schema decisions and the open TODOs). Antigravity CLI added it in v1.3.5; for Copilot CLI it is not verified, so check /help there. Run it at natural boundaries: after a feature lands and is committed, before shifting to a different area of the codebase, when you notice the model starting to contradict itself. The goal is to compact after work is safe in git: compaction is lossy by design, and the commits are your real record.
Claude Code also compacts on its own, and Anthropic’s current best-practices page lists context-window anxiety under advice you can stop following. Compacting by hand at a boundary is hygiene, not a rescue: it lets you say what the summary keeps.
2. Just-in-time retrieval
Preloading every file that might be relevant at session start is a tax you pay in tokens up front, on things the agent may never use.
Instead, reference files only when the agent actually needs them:
@src/services/billing.ts -- add a refund method following the existing patterns in this fileThe @-reference pulls the file into context precisely when the agent needs it, then it can be compacted or cleared on the next boundary. This is especially valuable in large repos: let the agent navigate to what it needs rather than flooding it with your entire src/ tree.
3. Structured note-taking
For work that spans multiple sessions, the agent’s in-memory state is useless the moment you close the terminal. What persists is what you wrote down.
Before you compact or end a session, tell the agent to record what it learned:
Before we compact: summarize the three decisions we made today aboutthe data model, and append them to CLAUDE.md under ## Session Notes.This is the depth behind Think Before You Prompt’s last step: write what worked down. It gives you a persistent, human-readable audit trail that the agent re-reads on the next open. Plan files work the same way: a spec the agent references at the start of each session beats re-explaining your architecture from scratch every morning. (More on spec-driven workflows in Lesson 7: Spec-Driven Development.)
Three of the four tools also keep an automatic memory across sessions: Claude Code’s is on by default in local sessions (toggle it in /memory), Codex CLI has /memories, and Copilot CLI has /memory (turned on with --enable-memory). Antigravity CLI keeps none by design; its /learn proposes a rule for you to review instead. OpenAI’s Codex docs put the rule plainly: treat memories as “a helpful recall layer, not as the only source for rules that must always apply.” Rules you rely on belong in the memory file.
In Claude Code, run /memory to add or edit rules in CLAUDE.md mid-session: the moment you notice a constraint or correct a mistake, record it and it persists into every future session without leaving the conversation.
4. Isolation via subagents
Sometimes the cleanest way to run a subtask is to keep it out of your main conversation entirely. Anthropic’s current guidance no longer recommends subagents “to protect your context window”; use them for parallel work, keeping noisy output out of your way, and independent review.
Delegate exploratory research, dependency audits, or large-file analysis to a subagent. Its dead-ends, verbose output, and half-formed conclusions stay in its own window — your main session only sees the distilled result. This is covered in depth in Lesson 5: Subagents and Orchestration.
Memory files that actually work
The four levers above assume the agent has a baseline to work from. That baseline is your memory file. Here is what separates one that constrains behavior from one that evaporates.
The good: constraints the model can act on
REFERENCE FILE CLAUDE.md / AGENTS.md project memory file with actionable constraints open reference hide reference Reference example of a concise, high-signal project memory file. Open to inspect how build commands, conventions, and frozen files are structured.
# Project: payment-service
## Build & verifynpm run build # must succeed, zero errorsnpm run test:unit # run after every schema change
## Conventions- All monetary values in cents (integer), never floats- API responses: { data, error, meta } envelope — no exceptions- New endpoints: add to openapi.yaml before implementation- TypeScript strict mode; no `any`
## Never touch- src/legacy/v1-compat.ts — frozen, customer dependency- db/migrations/ — append only, never edit existing migrations
## Verification stepAfter any auth change: npm run test:auth && check /health endpointFifteen lines. Every line is actionable. The model can check itself against each one.
The bad: aspirational prose
# Guidelines
This project values clean, readable, maintainable code that followsbest practices and industry standards. We aim for high test coverageand prefer well-documented solutions. The team uses a collaborativeapproach and code quality is important to us. We follow the principleof least surprise and try to write code that will be easy for futuredevelopers to understand and modify...The model reads this, finds nothing to constrain a specific decision, and falls back on its priors. Wall-of-prose memory files do not fail loudly — they just silently do nothing.
The test: For each line in your memory file, ask “could the agent make a concrete decision based only on this line?” If the answer is no, cut or rewrite it.
Run /doctor prompt-audit in Claude Code to list the lines in CLAUDE.md, skills and agents written for older models. Remove what it flags by Staying Current’s rule: prune one line, rerun the checks.
The memory file hierarchy
| Tool | Memory file | Scope | How to create/edit |
|---|---|---|---|
| Claude Code | ~/.claude/CLAUDE.md | User-level, all projects | /memory or manually |
| Claude Code | ./CLAUDE.md | Project — committed, team-shared | /init or manually |
| Codex CLI | ./AGENTS.md (global ~/.codex/AGENTS.md; the file closest to your directory wins) | Project | /init or manually |
| Antigravity CLI | ./AGENTS.md or ./GEMINI.md | Project (both are read; no documented precedence) | Manually (no /init; /learn proposes a rule from the session and writes it only after you review it) |
| GitHub Copilot | .github/copilot-instructions.md; also reads AGENTS.md, CLAUDE.md and GEMINI.md | Repo-wide (no documented precedence among them) | /init or manually |
AGENTS.md is the cross-tool standard. If you work across Claude Code, Codex CLI, Antigravity and Copilot CLI, a single AGENTS.md at the repo root travels with the codebase regardless of which tool your teammates use. Codex CLI, Antigravity and Copilot CLI read it natively. Claude Code reads AGENTS.md directly when the repo has no CLAUDE.md (v2.1.277 and later); if you keep a CLAUDE.md, add a single line, @AGENTS.md, to import it. Layer tool-specific overrides (like Claude’s ./CLAUDE.md) on top for anything that only applies to one tool.
Starting from nothing? /init drafts the file in Claude Code, Codex CLI and Copilot CLI; Antigravity CLI has no /init in its documented commands, so write that one by hand. Treat the draft the way Module 9’s project-memory step does: keep the build, test and lint commands and the rules the repo cannot tell the agent, and cut anything a reader could learn from the code. Do not cut to a fixed number of rules; hold each line to the test above.
Nested files are discovered automatically. In a monorepo or large project, drop a CLAUDE.md into a subdirectory — say packages/api/CLAUDE.md — and Claude pulls it in only when it works in that part of the tree. That scopes context to the area you’re actually editing instead of bloating one giant root file. The same layering idea extends upward: organizations can manage an enterprise policy tier that sits above project and user configuration. It’s the one level individuals can’t override, which makes it the right place for org-wide guardrails a whole team or agency should inherit by default. (Exact precedence and file locations are tool- and version-specific — confirm against current docs before you rely on them.)
~/.claude/CLAUDE.md holds preferences that apply everywhere — your preferred commit style, general conventions, how you like errors explained. The project ./CLAUDE.md holds project-specific constraints — build commands, frozen files, naming rules. Keep them distinct. Mixing project constraints into your user file means they apply everywhere; mixing personal preferences into the project file means they get committed and applied to everyone on the team.
Budgeting a session
Use /context (Claude Code, Antigravity CLI and Copilot CLI; Codex CLI’s documented command list has no /context) to get a current breakdown of window usage: how many tokens are consumed, what is contributing, and how much headroom remains. In Claude Code you can also press Ctrl+O to toggle the verbose transcript, useful when you want to see exactly what the agent is working from, not just the token count.
A practical session budget:
- Start clean.
/clearbetween unrelated tasks. Yesterday’s e-commerce session is dead weight when you open a new billing task today. - Watch the fill %. There is no universal threshold where quality drops; compact at useful boundaries or when irrelevant context piles up. Current tools also compact on their own, so this is hygiene, not a rescue.
- Compact at natural boundaries. Finish the feature, commit the work, then
/compact. The summary that compaction produces is higher-signal than the raw conversation it replaced. - Clear when you switch domains. Starting a completely different area of the codebase?
/clearand let the agent re-read what it needs via@-references and memory files.
The Vibe Coding Reference decision table has the full clear-vs-compact-vs-keep-going matrix — use it as your quick reference.
/btw lets you ask a throwaway question that sees current context without adding the exchange to your main history. Claude Code, Codex CLI and Antigravity CLI all have it as of 2026-11-07 (Codex also has /side, a side chat that is discarded afterwards); it is not in Copilot CLI’s command list. Good for quick clarifications mid-task without polluting the thread.
Notes and artifacts as durable memory
The mental shift: stop thinking of the conversation as your project memory. The conversation is ephemeral. These are durable:
CLAUDE.md/AGENTS.md— behavioral constraints, always present- Plan files (ask the agent to save the plan it proposed in plan mode to a file such as
plan.md): the spec the agent re-reads each session - Session notes — decisions appended to memory files before compaction
- Git history — the permanent record of what was built and why (commit messages matter)
A practical end-of-session prompt before you compact:
We're about to compact. Before we do:1. What three decisions did we make today that the next session needs to know?2. Are there any constraints we discovered that should be added to CLAUDE.md?Write both to CLAUDE.md under ## Session Notes with today's date, then summarize so I can verify.This 30-second habit is the difference between a week-long project that stays coherent and one that re-litigates the same architecture decisions every other day.
When Things Go Wrong
Use the Symptom → Evidence → Request pattern: describe what you see, paste the error, then ask for a fix.
You are 90 minutes into a session building a new auth module. The agent starts generating code that forgets the JWT expiry rules you established at the start. What is the most likely cause?
You finish implementing a complex caching layer. The session has been running for two hours. You want to start work on a completely separate rate-limiting module. What is the right sequence?
Which of the following belongs in a project CLAUDE.md?
Key takeaways
- Context rot is real and structural. Quality degrades as the window fills. The fix is engineering, not better prompts.
- Four levers: compaction (distill after committing), just-in-time retrieval (pull files when needed, not all upfront), note-taking (write decisions to memory files before compacting), and subagent isolation (keep exploratory work out of your main window).
- Memory files constrain; prose files evaporate. Every line should pass the “can the agent make a specific decision from this alone?” test.
AGENTS.mdtravels. Codex CLI, Antigravity CLI and Copilot CLI read it natively. Claude Code reads it directly when the repo has noCLAUDE.md(v2.1.277 and later), and otherwise imports it with one@AGENTS.mdline inCLAUDE.md: one file, four tools.- Session budget: watch
/contextfill %, compact at natural boundaries after committing, clear when switching tasks.
Next up: Lesson 3: MCP Servers — how the Model Context Protocol extends what the agent can see and do beyond the conversation window.