Context engineering
A practical guide to the discipline that decides what a model sees. Retrieval, agent patterns, reliability, evaluation, and the failure modes that break long-context systems, each with a runnable example.
A field guide by James Phoenix
The models got good at following instructions. That quietly moved the bottleneck. The hard part of building with an LLM is no longer wording a clever prompt, it is deciding what information the model gets to see at all. That job is context engineering, and it is most of the work in any serious system.
A model has no memory of you and no window onto your world beyond the text in front of it. So every answer is capped by the context you assemble: the files, the examples, the history, the tool results, in a finite window where everything you add crowds out something else. Get the right things in, keep the wrong things out, and shape what remains. That is the whole game, and this guide is a map of the moves.
The map below breaks the field into its main areas, from retrieval to the ways long context breaks, each linking through to a definition with a tested example you can run. Below that are the field notes, where I work the same ideas through on real systems.
The areas it covers
The full vocabulary is organised into these areas. Skim them for the shape of the field, then open any one for its definitions.
Foundations
What context engineering is, and the raw material it works with: the window, the tokens, the prompt.
Browse the 1 term →Retrieval & RAG
Pulling the right information into the window at the right time, instead of hoping the model already knows it.
Browse the 3 terms →Agent patterns
The shapes an LLM system can take, from fixed workflows to autonomous agents that choose their own path.
Browse the 4 terms →Reliability techniques
Getting consistent, trustworthy output from a stochastic model that will not give the same answer twice.
Browse the 1 term →Evaluation
Measuring whether your system is actually any good, so you can improve it on purpose rather than by vibes.
Browse the 1 term →Failure modes
The predictable ways long-context systems break, so you can see them coming.
Browse the 1 term →Memory
Carrying the right state across turns and sessions without drowning the window in history.
Browse the 1 term →From the notes
The dictionary tells you what each term means. These are the essays behind them: longer pieces where I work the same ideas through on real systems, and note what held up and what broke. Read whichever one matches the problem in front of you, or follow them from foundations down to the ways long context falls apart.
Deciding what the model sees
The first job in any system: choosing what goes into the window and what stays out.
- Progressive Disclosure: Load Context Only When NeededHow agents load files only when a task needs them, not all at once.
- Hierarchical Context PatternsWhy directory-level CLAUDE.md files give agents local, relevant context over one big file.
- Layered Prompts: Onion Architecture for AI Coding AgentsStructuring a prompt in core, domain, application, and task layers.
- Token Budgeting Strategies: Allocating Context by Information DensitySpending a finite window on the tokens that carry the most information.
- Don’t Let the Model Read the FileKeeping oversized files on disk and letting the model drive computation instead of reading.
Retrieval without the ceremony
Getting the right material in front of the model, often without embeddings at all.
- Vectorless RAG: Hierarchical Tree Retrieval Without EmbeddingsLetting an LLM navigate a document tree instead of embedding similarity search.
- GraphRAG for Production Engineer AgentsTurning organizational knowledge into a graph that agents traverse during incident response.
- Vendor the Source, Skip the SearchVendoring real library source beside your code so agents read it, not guess.
- Frontmatter as Document Schema: Why Your Knowledge Base Needs Type SignaturesUsing frontmatter type signatures to declare what documents are and how to find them.
Memory that outlives the session
Treating what an agent remembers as a data model with a lifecycle, not a feature.
- Memory Engineering as Data ModellingTreating agent memory as a data-modelling problem with a lifecycle, not a bolt-on.
- Agent Memory Patterns: Checkpoint, Resume, and State PersistenceExternalizing state so a stateless agent can checkpoint, resume, and persist.
- Institutional Memory with Learning Files: Teaching LLMs Past DecisionsRecording past decisions and rationale so the model stops re-proposing rejected ideas.
- Skill Graphs: Networked Knowledge Beats Monolithic Skill FilesCapturing a whole domain as a linked graph rather than isolated skill files.
Prompts as contracts
Specifying intent, constraints, and examples up front so the model has less to guess.
- Prompt Contracts: Formal Specifications That Eliminate Vibe CodingWriting an eight-section spec of objective, invariants, and scope before any code.
- Declarative Constraints Over Imperative InstructionsDeclaring constraints and desired state, then letting the model choose the implementation.
- Few-Shot Prompting with Project Examples: Teaching Patterns Through Concrete CodeWhy two or three real codebase examples teach patterns better than explanations.
- Chain-of-Thought Prompting for Complex LogicAsking the model to reason step by step before implementing complex logic.
When long context breaks
The failure modes that show up once sessions run long, and how to recover.
- Lost in the Middle: Preventing Context Window Attention DegradationCountering the U-shaped attention that quietly neglects the middle of the window.
- Context Rot Prevention: Auto-Compacting for Long AI SessionsAuto-compacting the sediment that accumulates and degrades quality across long sessions.
- Context Pollution Recovery: Diagnosing and Fixing Degraded AI SessionsDiagnosing and clearing the accumulated noise that drags a session's output down.
- Session Compaction Preserves Agent TrajectoryCompacting to preserve an agent's working trajectory, not merely to save tokens.
AI Native Software Engineering
The other half of the picture: the vocabulary and workflow of building software with AI agents, from tokens and context windows to tools, subagents, and review discipline.
Go to the guide →Common questions
What is context engineering?
It is the discipline of deciding what a model sees. A model can only work from the text in front of it, so the quality of any answer is capped by the context you assemble: the files, examples, history, and tool results you fit into a finite window. Getting that right is most of the work in any serious LLM system.
Is context engineering just prompt engineering with a new name?
No. Prompt engineering is about wording a single instruction well. Context engineering is the larger job of choosing what information reaches the model at all: what to retrieve, what to leave out, how to compress history, and how to keep the window useful as a task grows. The prompt is one small part of the context.
What is the context window?
The context window is the maximum amount of text, measured in tokens, that a model can consider for a single request. It is a hard ceiling and a shared budget: the system prompt, the history, the files, and the tool results all compete for the same space, so every token you add crowds out another.
What is RAG and do I need it?
RAG, retrieval-augmented generation, means pulling the material relevant to a request into the context so the model answers from it rather than guessing from memory. You need some form of retrieval whenever the answer depends on information the model was not trained on, like your own docs or code.
Do I always need embeddings to do retrieval?
No. Embeddings and vector search are one option, good for fuzzy matching across a large corpus. But you can also let a model navigate a document tree, follow links in a knowledge graph, or read a file you point it at directly. The right retrieval is whatever puts the correct material in the window most reliably.
What is chunking and why does it matter?
Chunking is splitting a long document into smaller pieces before you embed and retrieve them. The size and overlap of the chunks decide what can be found as a single unit, so it quietly makes or breaks a retrieval system. Chunk too big and you waste the window, too small and you lose the meaning.
What is the difference between memory and the context window?
The window is what the model can see right now, and it resets every session. Memory is an external store the system keeps and reloads into the window when it is relevant. The model itself remembers nothing between requests, so anything that has to persist lives in memory, not in the model.
Why do long conversations get worse over time?
Two reasons. Context accumulates like sediment, so old and irrelevant text crowds out what matters, which is context rot. And models attend best to the start and end of a long window while missing the middle. Compaction, clearing, and careful budgeting are how you fight both.
What is the lost in the middle problem?
It is the tendency of a model to use information at the start and end of a long context well while missing what sits in the middle. It means a bigger window does not automatically mean better recall. If a fact matters, put it where the model actually looks rather than burying it halfway down.
What is compaction?
Compaction is condensing older conversation history into a summary to reclaim window space while keeping the important gist. It is lossy by design, so the art is in summarising the trajectory and the decisions, not just the last few messages, so the agent can keep going without relearning everything.
What is progressive disclosure?
Progressive disclosure is revealing detail to the model only when it is needed, through pointers and on-demand loading, instead of dumping everything into the window up front. You show what exists and its cost, then load the specific piece when the task calls for it. It saves both space and attention.
How do I stop an agent running out of context?
Treat the window as a budget. Load information only when a task needs it, point to large files instead of pasting them, compact or summarise old history, and hand off to a fresh session with a short state document when the window fills. The goal is to keep the highest-value tokens in and everything else out.
How do I tell whether my context is actually good?
You measure it. Build a set of real cases with known good answers and score your system against them, using a model as a judge for the fuzzy ones. Evaluation turns context engineering from guesswork into something you improve on purpose, one change at a time.
When should I use an agent instead of a fixed workflow?
A workflow follows a path you designed in advance; an agent decides its own path at run time by calling tools in a loop. Use a workflow when the steps are known and you want reliability, and an agent when the path genuinely depends on what it finds along the way. Choosing correctly is the first context-engineering decision.
Is context engineering only relevant for RAG chatbots?
No. Any time you work with a model, from a coding agent to a data pipeline, you are deciding what it sees. Retrieval is one part. Memory, history management, tool results, specs, and handoffs are all context engineering. It is the substrate under every serious LLM application, not a single feature.
Want this applied to your product?
The dictionary is how I think out loud. If you want that thinking turned into a working system for your team, that is what I do.
See how I can help