# Context engineering

> Move repeatable instructions out of the chat and into files, so the agent produces consistent work no matter who runs it.

You can get a long way by typing questions into the chat. At some point, though, you find yourself retyping the same instructions in every chat: the same definitions, the same data caveats, the same notes on how a report should read.

That repetition is the signal that you're ready for context engineering: curating what the agent sees, and in what order, so it produces the output you want without being told everything from scratch each time. This page covers which files make up context engineering, when to reach for each, and how to keep them lean.

Three questions get you started:

- *What should the agent always know?*
- *What instructions belong in a reusable plan?*
- *What mistakes should the agent avoid every time?*

For where these files live and how the agent reads them, see [Projects and standing instructions](/agent/projects-and-instructions).

## What "context" means

Context is everything the model can see before it answers: not just the sentence you typed, but the instructions, examples, reference data and earlier turns around it. You shape it by putting durable instructions into files the agent loads and refers to, rather than packing them into a single message. This page is the why; [Projects and standing instructions](/agent/projects-and-instructions) is the how.

## What this looks like in practice

Take the customer experience digest a CX lead wants every month.

**Without context engineering**, every month starts with the same long chat instruction:

> Build me the May customer experience digest. Use the standard Dimensions table and the reviews prompt's table. Compare to April. Pull three verbatim quotes for each top theme. Write it as a full analysis, not bullet points. Don't lean on the chart to do the storytelling...

**With context engineering**, the same job lives in a small set of files, a plan file and a failure-modes file, and the message is one line:

> Execute the customer experience digest plan for May.

The instructions no longer depend on whoever happens to run the chat. Same output, every month, whoever runs it. That contrast is the whole point.

## From prompt engineering to context engineering

Prompt engineering was about wording your way to the right answer. It lived in the chat box: phrasing, framing, the occasional "imagine you're an expert." Context engineering works at a different level. The goal is the right *actions* from an agent doing work on your behalf, not just the right text back.

Philipp Schmid describes the skill as giving the model the right information, in the right format, at the right time, so the task is solvable, and concludes that most agent failures are now failures of context, not of the model ([The New Skill in AI is Not Prompting, It's Context Engineering](https://www.philschmid.de/context-engineering), 2025). When an answer comes back wrong, look first at what the agent could and couldn't see.

:::note[Less is more]
You don't need to talk the agent into being good at its job, and you don't need to repeat yourself. Role-play instructions like "imagine you're an expert" mostly shape tone, not correctness, so skip them. A well-built set of files means the agent stops relearning your vocabulary and your data on every run.
:::

## When it's worth the effort

None of this is required on day one. The agent has a low floor: ask a plain question and you get something useful straight away. Context engineering is how you reach the higher ceiling, and it pays off when a process *repeats*: a monthly report, a weekly digest, an analysis you'll run again with new dates.

| Situation | What to do |
|---|---|
| **The question is one-off** | Ask in the chat. Use it for a quick answer, a first look or an exploratory chat. |
| **The process repeats** | Move durable instructions into files: for a monthly report, a weekly digest, a recurring analysis, or a handoff another person needs to run. |
| **Always** | Keep the context small. |

Why small: a model works within a finite attention budget, and as its working memory fills, recall gets worse. Anthropic calls this "context rot" ([Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents), Anthropic, 2025). Good context engineering uses the smallest set of high-signal material that does the job.

## The building blocks

Almost everything the agent works from is, structurally, a file. These files have settled into a common shape: plain Markdown rather than JSON or YAML, scoped from broad to narrow, and editable before, during and after a run.

### Start with three

You don't need all of them to start. Add these three first, in the order you'll actually need them:

1. **A plan file.** The analysis instructions for a report you'll run more than once. See [Analysis plans](/agent/analysis-plans).
2. **A failure-modes file.** Add it the first time you notice the agent defaulting to a shape you don't want.
3. **An agent file (`AGENTS.md`).** Pull it out when you realize you're typing the same business context into every plan. See [AGENTS.md](/agent/projects-and-instructions#agentsmd-standing-instructions).

The rest are supporting files you add when a specific need shows up.

### Every file type

| File | What it holds | When to reach for it | Scope |
|---|---|---|---|
| **Plan file** | The full instructions for a report: objective, fields, join keys, output structure. | You'll run the same analysis more than once. | Per report |
| **Failure-modes file** | Behaviors to block: too many bullets, charts carrying the story, a written analysis drifting into a dashboard layout. | Output keeps defaulting to a shape you don't want. | Reusable across reports |
| **Agent file (`AGENTS.md`)** | Standing business context the agent should always assume: key terms, what matters, and the orientation it would otherwise ask for every time. | You're copying the same context into every plan, or the agent keeps relearning your business. | Per project |
| **Report execution guidelines** | How a report should look: visualization choices, formatting, brand colors and fonts, output expectations. | You want consistent presentation across runs. | Per report or project |
| **Schema file** | What your data fields mean. | The agent needs help reading your tables correctly. | Per project |
| **Ontology file** | Your domain vocabulary: the specific language your organization uses. | Your terms are non-obvious or easy to misread. | Per project |
| **Skill** | A named file for one repeated task, which can carry its own reference attachments. Attach it and name it in your message when you need it. | A process is worth packaging and reusing, by you, your team or your company. | Personal, team or company |

### The agent file is a standing brief

Every chat starts cold: the agent doesn't remember yesterday's chat, but it follows written standing instructions faithfully. `AGENTS.md` is that brief. Keep it lean, with only the instructions that are true for every chat in the project. How to write it, and why it should stay short, is on [Projects and standing instructions](/agent/projects-and-instructions#agentsmd-standing-instructions).

### The ontology is quick to build

You don't need to write an ontology by hand. Have the agent read your website and past conversations and assemble the vocabulary for you, then review what it wrote.

## Failure patterns

| Pattern | What goes wrong |
|---|---|
| **Prompt stuffing** | Cramming every instruction into the chat every time, instead of moving durable instructions into files. |
| **Instruction sprawl** | Letting the agent file grow into a niche encyclopedia nobody keeps current. See [Keep it short](/agent/projects-and-instructions#keep-it-short). |
| **Cargo-cult plans** | Running a complex plan file you didn't build and can't maintain. See [the wall of text](#a-note-on-the-wall-of-text) below. |

## Working with these files

A few habits make context engineering smoother.

### Iterate the plan before you run it

Spend ten or fifteen minutes reading the draft the agent produces, and ask for a round or two of revisions. Catching a wrong join key or a missing field up front is far cheaper than finding it mid-run.

### Show, don't tell

Examples are the strongest instruction you can give. A worked "here's what good looks like" steers output far more reliably than describing it in the abstract. A failure-modes file blocks the patterns you don't want; a couple of example outputs pin down the pattern you do.

### Structure plans so updates only touch the top

Define your key terms in the first sections, then refer to them by name everywhere else. When something changes, you edit the definition once and the rest follows. It works a bit like algebra.

### Let the agent edit the files for you

You don't hand-edit a plan to change the month or pull out a section you no longer need. Tell the agent what to change, such as *"Change this plan file to be May"* or *"Remove all references to the short-file output"*, and it rewrites the file in place.

### Keep heavy output in files, not the chat

For anything that generates a lot of text, tell the agent to write long summaries to a working file and assemble the report from that file at the end. The chat stays readable, the intermediate work stays auditable, and less of the attention budget goes on material you don't need in front of you.

### Move work cleanly between chats

When a plan is ready to run, ask the agent to write the short execution preamble to paste into the new chat alongside it. When you want to hand a piece of work to a colleague, ask for a handoff file that captures what the chat has learned. They attach it in a new chat and pick up where you left off.

## What's available now

These all work today:

- plan files
- schema and ontology files
- failure-modes files and report execution guidelines
- uploading a reference file and telling the agent to consult it
- having the agent edit any of these in place
- `AGENTS.md`, a standing instructions file the agent reads in every chat of a project. See [Projects and standing instructions](/agent/projects-and-instructions).
- skills: attach the skill file and name it in your message

`AGENTS.md` follows the way coding agents use a standing instructions file (such as Claude's `CLAUDE.md`).

## A note on the "wall of text"

The first time you open a finished plan file, it can look intimidating: a long document dense with instructions. That reaction is normal, and worth naming.

A plan feels much easier when you built it yourself, because you remember the reasoning behind each section. Handed a complete one cold, anyone sees a wall of text. The fix isn't to study the system in depth before you start. Make a couple of passes through the file, pick out the few moving parts that actually matter, and let your mental map fill in.

Picture the agent as a market research agency you've hired for a serious, bespoke project. You wouldn't turn them loose without a clear plan of what they're going to deliver. Context engineering is how you write that plan down once, and then never have to write it again.

## Related

- [Projects and standing instructions](/agent/projects-and-instructions): projects, `AGENTS.md` and where files and outputs live
- [Analysis plans](/agent/analysis-plans): build a plan file step by step
- [Quick answers and analysis plans](/agent/modes): when to ask a single question and when to write a plan
- [Your first chat](/agent/first-session): if you're just opening a workspace and haven't asked anything yet