Context engineering for AI agents

Updated Oct 10, 2026·4 min read

The short answer

Context engineering is deciding what an AI agent has in front of it when it starts a job: what the project is, what to build, what was already decided and where the code lives. Done well, you write it down once in files every agent reads, so you stop re-explaining the project at the start of every session.

Why your agents keep asking the same things

Every new session starts with an empty head. The agent knows how to code, but not your project: what it's for, how you run it, what you ruled out last week. So it asks, or worse, it guesses.

Better prompts don't fix that. A short, stable set of files that every agent reads does.

The three layers of context

The project, written once. What the product does, who it's for, how to run and test it, and the few rules that never change. One file at the root of the repo.
The job, written per task. The problem, what to build, the files it touches and Done When. This changes every job, so it lives with the job, not in the project file.
What was decided. Answers you already gave and options you ruled out, with the reason. This is the layer most setups lose, and it's why agents ask the same question twice.

Where each layer lives

The project file. AGENTS.md is the shared one. Cursor and Codex read it, and Claude Code now reads it too when a repo has no CLAUDE.md. If you already keep a CLAUDE.md, add the line @AGENTS.md to it, so Claude Code reads both and the two can't drift apart.
The job plan. A short spec per job (see spec-driven development). Paste it, link it, or keep it where every agent can read it.
Decisions. A short decisions file or log: the rule, the reason, the date. Agents read it before they ask.

What to leave out

Anything that changes weekly. It goes stale in the project file and agents trust it anyway.
Long style guides. Point to the linter instead.
Whole conversations. A handoff note beats a transcript.

Signs your context is working

A new session starts the right job without a recap from you.
Two agents make the same call on the same question.
You answer each kind of question once.

Copy this

Use this as the start of your CLAUDE.md or AGENTS.md.

A project file every agent reads

# Project
<what it does and who it's for, 2 lines>

## Run and test
<commands>

## Rules that never change
- <rule>
- <rule>

## Decided (read before asking)
- <date>: <decision>, because <reason>

Where Annsa fits

Annsa keeps the job plan and the decisions with the work: one spec per job and the answers you've given, which Claude Code, Cursor, Codex and Grok read over MCP before they ask. Your project file stays in your repo. Working with Annsa

See how it fits together in Direct your agents.

Questions people ask.

What is context engineering?

Deciding what an AI agent has in front of it for each job: the project, the task, and what was already decided, written down so every agent reads the same thing.

Is AGENTS.md the same as CLAUDE.md?

They do the same job. AGENTS.md is the shared file Cursor and Codex read, and Claude Code reads it too when a repo has no CLAUDE.md. If you keep both, add @AGENTS.md to your CLAUDE.md so Claude Code reads the shared one as well.

Why does Claude Code keep forgetting things between sessions?

Each session starts fresh, and long sessions get compacted. Anything you said only in chat can be lost. Put what must last in the project file or the job plan.

What should go in a CLAUDE.md and what should stay out?

Put in what the project is, how to run it and the rules that never change. Leave out anything that changes weekly, long style guides and pasted conversations.

Get your agents in a row.

Try Annsa