Intent, AGENTS.md and Other Instruction Files

011. Context engineering

The contractor test

Before sending a prompt, ask one question. Could a bright contractor with no knowledge of your organisation do this task well from what you have written? If they would need to ask five questions first, the model needs those five answers too. It will not ask. It will guess.

What a good brief contains

• The situation and purpose. Who this is for and why it matters. Models generalise well from reasons and poorly from bare rules.
• The task. One clear statement of what to produce.
• Constraints. What must not change, what to avoid, how long, in what style.
• Materials. The code, document or data to work from. Supplied, not described.
• Examples. Two or three samples of good output. Vary them, because models copy examples closely.
• Output format. Exactly what shape you want back, especially if code will parse it.
• What to do when unsure. Permission to say “I don’t know” or to ask, which reduces invention.

Techniques that have lasted

• Say what to do, not only what to avoid. “Write in plain paragraphs” works better than “no bullet points”.
• Separate instructions from material with clear delimiters, such as tagged sections or headings, so the model can tell a document from a directive.
• Put long documents first and the question last, as part 3 of the language models module advises.
• For a model without a thinking mode, ask for reasoning before the conclusion.
• Fix problems at the source. When output is wrong, ask what the brief failed to say, and add that. Do not pile on capital letters.

Prompts are code

A prompt that runs in production is part of the system. Keep it in version control. Review changes to it. Test it with the evals from part 9 before release. Pin the model version it was tuned for, because a prompt tuned on one model often behaves differently on the next.

Shared prompts and instruction files are team assets. A good project instruction file improves every session for every engineer who uses it. The rest of this part is about those files.

022. The layers of instruction

Who writes what

Teams control the middle of the table, and that is where their effort belongs. The layers are additive: a tool that reads several of these files puts all of them into the context at once. When two layers disagree, no rule in the software settles it. The model reads both and uses its judgement, usually favouring the more specific instruction. That is one reason contradictions between an organisation’s rules and a project’s file are worth hunting down.

Always there, or fetched when needed

The most useful way to sort the layers is by when they load. Anything loaded in every session costs context in every session, whether the task needs it or not. Part 3 of the language models module shows that a filling context costs money and quality. So each layer has a budget.

Standing instructions should be short and should hold what is always true: the commands, the conventions, the things never to do. Reference material that is needed sometimes, such as the full API style guide or the release procedure, belongs in something fetched on demand. That is the job of scoped rules and of the skills in part 4. One vendor’s documentation puts the dividing line plainly: put it in the standing file if the agent should always know it, and in a skill if it needs it sometimes.

A request, not a guarantee

Every layer in the table is text the model reads. None of them is enforced. A line saying “never edit the generated files” makes that edit much less likely. It does not make it impossible, and an agent deep in a long task can lose track of a line it read at the start.

If a rule must hold every time, it needs a mechanism that does not depend on the model: a file permission, a pre-commit check, a hook in the harness that blocks the action, a credential the agent was never given. Part 9 builds on this. The instruction file is for shaping behaviour. It is the wrong tool for preventing harm.

033. The project instruction file

One file, many names

Every coding tool invented its own file, and for a while a repository that wanted to serve them all carried five copies of the same advice. In August 2025 OpenAI and others proposed a common one: AGENTS.md, plain Markdown at the repository root, with no required structure. Its own site calls it a README for agents. It is now stewarded by the Agentic AI Foundation under the Linux Foundation, the same body that looks after the Model Context Protocol from part 7. The site says more than 60,000 open-source projects use it and lists more than thirty tools that read it.

The table was written in September 2026 and the list of readers grows monthly. The sensible arrangement is one source of truth. Write AGENTS.md, and where a tool insists on its own name, make that file a one-line import or a link to it. Do not maintain two copies. They will drift, and the agent that reads the stale one will be confidently wrong.

In a large repository, a folder can carry its own AGENTS.md. The rule in the specification is that the nearest file to the code being edited wins, so a package can state its own conventions without lengthening the file at the root.

What belongs in it

• the exact commands to build, test, lint and run
• a short map of the codebase and where things live
• conventions that differ from common defaults
• things never to do, such as editing generated files or touching a legacy module
• the definition of done: tests pass, lint is clean, no unrelated changes

# AGENTS.md

## Commands
- Install: pnpm install
- Test one package: pnpm test --filter <package>
- Full check before any commit: pnpm check

## Layout
- packages/core is the billing logic. It has no I/O and no framework code.
- packages/api is the HTTP layer. It calls core and never the database directly.

## Conventions
- Money is an integer number of pence. Never a float.
- New endpoints copy the shape of packages/api/src/invoices.ts.

## Never
- Edit anything under generated/. Change the schema and run pnpm codegen.
- Touch packages/legacy-ledger without asking.

## Done means
- pnpm check passes, and the diff contains nothing unrelated to the task.

Every line in that example tells the agent something it could not work out quickly by looking. That is the test for a line.

What the evidence says

Two studies published in early 2026 looked at whether these files help, and they appear to disagree.

The first ran coding agents on 124 pull requests across ten repositories, with and without an AGENTS.md. With the file, the median run was about 29% shorter and used about 17% fewer output tokens, and the tasks were completed about as well. The agent spent less time finding out how the project worked.

The second, from ETH Zurich, measured whether tasks succeeded. It found that context files did not generally improve success rates and raised the cost of each run by more than a fifth, for files written by developers and for files generated by a model. Its detail is the useful part. Agents followed the instructions in the files well. What did not help was the repository overview, the prose tour of the codebase that tools offer to generate for you and that vendors recommend. The authors concluded that the files are useful for stating practices that are not standard, and that anything beyond that should be tested.

Both are small studies of a fast-moving target. Read together they say something a practitioner would recognise. An agent can discover a project’s structure for itself, and it will do so whether or not you describe it. It cannot discover that your team never uses floats for money. Write down what cannot be found, keep out what can, and keep the file short.

The pair also shows the fourth of the course’s four ideas at work: measure, do not feel. A tour of the codebase feels helpful, the tools offer to write one, and the vendors recommend it. Measured, it bought no more successes and a larger bill. The first study would have looked like a plain win had no one measured success as well as speed.

Keeping it short, and keeping it true

Keep it under a couple of hundred lines. One vendor’s documentation gives 200 lines as the target and says plainly that longer files reduce how well the instructions are followed. Review changes to it like code. Whenever the agent repeats a mistake, add a line. Whenever a line stops being true, delete it, because a stale instruction is worse than none.

Do not let a tool write the file for you and leave it there. A generated file is mostly overview, which is the part the evidence says does not help. Use the generated draft to find the commands, then cut the rest.

Some harnesses now keep a second file that the agent writes itself: notes on corrections you gave and preferences it noticed, loaded at the start of later sessions. It is useful, and it is a layer like any other. Read it now and then, because it shapes every session and nobody reviewed it.

044. Intent files and working from a specification

How differs from what

The instruction file answers “how do we work here?”. It is true for months. A task brief answers “what do I want now?”. It is true for an afternoon. Between them is a gap: the purpose of the product, who uses it, what it must never do, and what done means for the feature in hand. People on a team carry this in their heads. An agent does not, and a fresh one arrives every session.

Without it, an agent fills the gap by guessing, and it guesses the most ordinary product. Ask for an export feature with no statement of intent and you will get a reasonable export feature, for a reasonable imaginary customer, which may not be yours.

What people are doing about it

Several practices go by the names intent-driven development and spec-driven development. They share a loop: state the intent, turn it into a specification, turn that into a plan, implement the plan, verify the result against the specification, and update the intent with what was learned. Each stage is a file in the repository, reviewed by a person before the next stage starts.

• An intent file. A single document at the repository root, commonly INTENT.md, saying what is being built, for whom, and what done means. It changes slowly.
• A specification per feature. Behaviour, acceptance criteria and what is out of scope, written before any code. Toolkits such as GitHub’s Spec Kit, OpenSpec and Amazon’s Kiro generate the files and walk the agent through the stages.
• A plan. The agent’s own proposal for how to meet the specification, written down so that a person can correct it while correction is cheap.

This part names those tools and does not recommend one, because the formats compete and change. At the time of writing there are at least three published layouts for an intent file alone, from different authors, none with the standing of AGENTS.md. Choosing a format matters much less than having the content.

Why it works

It works for the reasons given elsewhere in this course. A written acceptance criterion is something an agent can verify its work against, and verification is what turns compute into reliability. A reviewed plan is human attention spent at the start of a task, where a minute saves an hour. And a specification that lives in the repository survives the end of the session, which the conversation does not.

It also moves the engineer’s effort to where it is now most valuable. If an agent can write the code in ten minutes, the scarce skill is saying precisely what the code should do.

Where it goes wrong

• Ceremony. A three-line bug fix does not need four documents. Use the full loop for features, and a good brief for everything else.
• Specifications nobody reads. An agent will happily write a long, plausible specification from a one-line request. If no person reads it critically, the agent is checking its work against its own guess. The review is the point.
• Drift. A specification that is not updated when the decision changes becomes a confident source of wrong answers, like any stale document.

055. Briefing a task, and a repository that helps

Briefing a task

Apply section 1 to engineering work. State the goal and the reason. Give acceptance criteria. Point to the relevant files and to an existing example to follow. State constraints, such as “do not change the public API”. For anything non-trivial, ask for a plan first. Give one task per session.

Goal: invoices over 10,000 pounds need a second approver before they are sent.
Why: the finance audit in March found three sent on one signature.

Done when:
- an invoice over the limit cannot reach "sent" without two different approvers
- the limit is read from config, not written into the code
- the existing invoice tests still pass, and new tests cover both sides of the limit

Look at packages/core/src/approval.ts, and copy the shape of the
credit-note rule in the same file.

Do not change the public API of packages/api.
Show me a plan before you edit anything.

Nothing in that brief is clever. It is what you would tell a contractor, written down.

What makes a repository agent-friendly

This list is simply good engineering practice. AI raises the return on it. Technical debt taxes an agent as it taxes a person, and arguably more, because the agent has no colleague to ask.

The whiteboard version

Three kinds of writing sit in front of an agent. Standing instructions say how we work here, and they are short. A statement of intent says what we are building and how we will know it is done. A brief says what to do now. Most disappointing results trace back to one of the three being missing, and the fix is to write it, not to find a better model.