Context engineering & agents.md

01Why context is everything

An LLM is stateless: the output is based only on the input. That input is called the context — all the information the model has to work with. Since the output is nothing but a function of the input, getting the context right is literally all there is.

We used to call this prompt engineering. It’s grown into context engineering — recognising it’s not just the prompt, but everything you surround the model with: the tools it’s given, the memory, the files. The whole toolkit for feeding the model the right information.

02Anatomy of the context

A lot goes into that single input. Roughly, in order:

• System prompt — the most general framing: what role the model plays, its job, its tone. Usually first.
• Tool descriptions — the menu of actions it can request. More tools = more space consumed. (Some people count these as part of the system prompt; it’s just a labelling choice.)
• Memory — resources you want to persist across conversations.
• The conversation so far — the big one. Every prior message, its reasoning, any code it wrote, any tools it called and their results. All squeezed in so the next token stays consistent with the whole history.

03The context window (and why less is more)

There’s a hard limit to how many tokens fit — the context window. Exceed it and the call fails.

Compacting — the feared summariser

Rather than failing when the window fills, tools like Claude Code run compacting: they summarise the conversation so far and replace it with that summary, freeing space. It’s useful — and historically feared, because you’re trusting the model to decide what matters. Sometimes it drops something you cared about, and the agent “forgets.”

04agents.md — the file that steers the agent

The agents.md file preps your agent with information about the project. It’s a markdown file (.md) — a simple, human-readable format that LLMs adore, because they’ve read and written oceans of it.

The hierarchy

An agents.md in the project root is always loaded. You can also place one in any subdirectory, at any depth — and it’s loaded only when the agent works on files there, combined with the parent files up the tree. Rules in an inner file override outer ones, so you can get more specific deeper down.

What a good agents.md contains

Write it like a prompt: concise, crisp, assertive, low-ambiguity, maximum signal per word — because it costs precious context space.

• Overall project goals and success criteria — ideally a checklist it must tick off.
• Links to other documents it can optionally load.
• Clear coding standards, tuned to correct past mistakes.

## Coding standards
- Simpler is better. Never over-engineer; always simplify.
- Comments only when necessary. Be concise.
- Keep READMEs short. IMPORTANT: no emojis, ever.
- Avoid over-defensive programming; handle exceptions only when needed.
- Use latest, idiomatic library versions as of today.

Two schools of thought

The instructor’s honest position: still leaning 2025 for serious, larger projects — the effort on context still pays off — while happily letting toy projects run free. It depends on the project, as the next page explores. Expect the balance to tip further toward “let it go” through 2026.