Context Engineering
The practice of giving AI the surrounding context it cannot sense on its own.
You ask the AI to write a login endpoint (the function that logs users in). It delivers generic boilerplate — wrong framework, wrong folder, wrong error format. The AI is not stupid. It simply does not know your project.
Context Engineering is the discipline of giving the AI exactly the right information so it produces code that fits your codebase — not just any code that runs without errors. By the end of this article, you will understand how Context Engineering differs from Prompt Engineering, what belongs in a rule file, and how to decide which information the agent needs and when.
From Prompt to Context
Definition
Context Engineering — Shaping the AI's Working Environment
Analogy
Definition
The onboarding analogy has a limit: a new hire learns and remembers permanently. An AI agent has a finite context window and may lose information when it overflows. The analogy does not capture the forgetting problem.
You optimise the individual question. "Write a login endpoint" becomes "Write a login endpoint with NestJS in src/modules/auth/ using absolute imports." Quality depends on how detailed you are each time.
You optimise the working environment. Through a rule file, the AI already knows your project uses NestJS, where services belong, and which error conventions apply. "Write a login endpoint" is enough — the context provides the rest.
Caution
Common Misconception
"A better prompt fixes everything." — Even a perfect prompt cannot compensate for missing project context. You could write "use NestJS, absolute imports, put it in src/modules/auth/" every single time — but that means repeating your entire project setup in every conversation. Context Engineering externalises this into a persistent file so the agent starts informed without you repeating yourself.
The Rule File — Persistent Project Context
A rule file is a project-level configuration that your AI coding tool usually reads automatically. The content is natural language: architecture overview, coding standards, build commands, anti-patterns, workflows. Anthropic recommends keeping it concise and well-structured — not a dump of everything, but a curated set of what the agent needs and cannot work out from the code itself. Each tool has its own file for this. Alongside them there is AGENTS.md, an open format for exactly this purpose: GitHub Copilot and Cursor read it, and since September 2026 so does Claude Code when the project has no CLAUDE.md. If you use several tools, one file is enough.
Like a cockpit checklist for pilots: the rule file does not teach the AI to fly — it helps it run the same checks consistently and make fewer careless errors.
Good content: a short architecture overview (framework, folder structure, only what the code doesn't show by itself), coding conventions (import style, error handling, naming conventions), build and test commands (npm run dev, npm test), anti-patterns (things the agent should never do), git workflow (commit format, branch strategy). A 2026 study from ETH Zurich measured this: rule files barely improve coding agents' success rates on average but make the work about a fifth more expensive, and general project overviews don't help at all. The files are most useful for requirements that deviate from the usual and that the agent cannot read from the code itself.
Bad content: Passwords, API keys, or credentials (security risk), the entire codebase (floods the context), information that changes constantly (belongs in task-specific files).
Example: Excerpt from a CLAUDE.md
## Architecture
- Framework: NestJS
- All imports: absolute (never relative)
- Folder: src/modules/[domain]/
## Coding Standards
- Error responses: always use AppException class
- Tests: Jest, one spec file per service
- Never use console.log — use LoggerService
## Build & Run
- npm run dev (port 3000)
- npm test (all specs)Caution
Common Misconception
"Write it once and forget about it." — Anthropic explicitly describes CLAUDE.md as an ongoing practice. When the AI repeatedly makes the same mistake — placing services in the wrong directory, using the wrong test command, leaving unwanted comments — that mistake becomes a new rule. The file improves over time through real friction, not upfront planning alone.
Context Hierarchy — Less Is More
LLMs have a finite attention budget. As context grows, precision when retrieving and connecting information tends to decrease. Information in the middle of a long context is especially easy to lose; at the beginning and the end the model finds it more reliably ("Lost in the Middle", Liu et al. 2023). Newer measurements do not find this middle effect in every model or at every fill level, but they do find the decline with growing length. The central question is therefore not "How do I fit everything in?" but "How do I load the right information at the right time?"
- 1. Permanent Project RulesCLAUDE.md, copilot-instructions.md — Architecture, standards, workflows. Always loaded.
- 2. Task-Specific FilesRelevant source files, examples, documentation for the current task.
- 3. Conversation HistoryThe conversation so far with the agent — decisions, results, feedback.
- 4. Tool ResultsSearch results, file contents, test outputs — loaded on demand, just in time.
Think of a surgeon's instrument tray. The operating room has thousands of instruments available, but only a small tray with the instruments needed for the current step is within reach. More instruments on the tray means more clutter, slower decisions, higher error risk. The surgeon asks for specific instruments when needed — just in time.
The analogy has a limit: a surgeon knows exactly which instrument they need. An AI agent must often discover what it needs during execution, using search and reading tools.
An example: a codebase with 50,000 lines. Bad approach: paste everything into the prompt. Good approach: CLAUDE.md provides the key project rules, the agent uses search tools to find the specific files for the current task. Result: the agent works with 200 highly relevant lines instead of drowning in 50,000 lines of mixed relevance. Between the rule file and tool results there are now skills: folders with instructions (SKILL.md) of which the agent initially knows only the name and a short description. It loads the rest only when a task fits. Claude Code, GitHub Copilot and Cursor all read this open format.
A good rule file is not written in one go but grows iteratively. The process: you start a task. You observe where the agent makes mistakes. You add a rule that corrects the error. Next time, the agent works closer to your project style. Example: the AI keeps placing services in src/services/ instead of src/modules/[domain]/. You add "Folder: src/modules/[domain]/" to the rule file. From now on, the agent uses the correct structure.
Caution
Common Misconception
"The AI reads everything automatically." — It does not. Even models with large context windows lose focus when overloaded. Anthropic emphasises that the model's attention degrades with growing context. The discipline of Context Engineering is therefore about selection — choosing what goes in and what stays out — not about maximising input size.
Interactive: Why More Context Does Not Always Help
Try it yourself: set how full the context window is and where the one important piece of information sits. The box starts with the bad approach from the example above: everything copied in, the important part somewhere in the middle. The fuller the window, the less often the model finds the information, and in the middle it gets lost most easily. Researchers call the middle effect “Lost in the Middle” (Liu et al., 2023); newer measurements do not find it in every model. The curves show only the direction, not measured values.
Note
Key Takeaways
- Context Engineering shifts the bottleneck from prompt phrasing to information curation. Not just how you ask, but above all what the agent already knows determines the quality.
- A rule file (CLAUDE.md, copilot-instructions.md, .cursor/rules) is the agent's onboarding package — architecture, conventions, commands — so it starts informed rather than from scratch.
- More context is not better context. The agent needs the smallest relevant set at the right time — permanent rules as the foundation, task-specific files per task, tool results only when needed.
Check
Knowledge Check: Context Engineering
What is the main difference between Prompt Engineering and Context Engineering?
Select one answer
1. What is the main difference between Prompt Engineering and Context Engineering?
2. A developer notices their AI assistant always creates files in the wrong directory. What is the Context Engineering solution?
3. You have a 30,000-line codebase and want the AI to refactor a single service. Which approach follows the context hierarchy principle?
4. A team's CLAUDE.md file contains the database password, the full API key, and a list of all 200 microservice endpoints. Which statement best evaluates this setup?
Check
Checkpoint: Context Engineering
Can you explain this in your own words? Tick what you've got.
0 of 3 done