Artificial intelligence/Standing instructions for an AI coding agent

This learning resource is a sub-page of Artificial intelligence. It is about a small text file that changes how an AI coding agent behaves more than most prompts do: the file of standing instructions that the agent's host software loads before the first message of every session.

Several tools read such a file automatically. Common names are AGENTS.md, CLAUDE.md and .github/copilot-instructions.md. The names differ; the idea is the same, and so are the mistakes people make with it. Nothing here depends on one product.

After working through this resource a learner should be able to:

• explain why an agent forgets a correction from yesterday, and what part of that the instruction file fixes;
• decide, for a given sentence, whether it belongs in the file, in the code, in a one-off request or nowhere;
• rewrite a vague rule into one an agent can check itself against;
• estimate what a long file costs over a working day, and keep it short for that reason;
• say which rules an instruction file cannot guarantee, and where those rules should live instead.

A language model keeps nothing between conversations. Whatever a person explained on Monday (where the data lives, which folder is off limits, how to run the tests) is gone on Tuesday unless something puts it back into the context.

People notice this as repetition. The same three sentences open every session. Sooner or later one of them gets forgotten, and the agent does exactly the thing it was told not to do last week. It has not disobeyed anyone. It was never told.

An instruction file is the cheapest fix. The host software reads it at the start of each session and places its text in front of the conversation. The agent "knows" the rules for the same reason it knows the user's first message: the text is there.

Most tools look for the file in more than one place and combine what they find. A typical arrangement:

The project layer is the one worth effort, because it travels with the code and every collaborator, human or not, gets the same rules. The personal layer should stay small. A rule there follows the person into projects where it may be wrong.

Exercise 1. Take three instructions you have typed to an agent more than once. Put each into one layer and write one line on why it does not belong in the other two.

A practical test: if you have said it twice, write it down; if you have said it once, wait. The file records patterns, not moods.

Things that pass the test usually fall into four groups.

1. How to check the work. The command that runs the tests, the page to open, the output that means success. An agent that can check itself makes fewer confident mistakes.
2. Boundaries. Folders, files and services that are not to be changed, plus the reason in a few words. The reason helps the agent recognise cases the rule did not name.
3. Conventions the code does not show. "New records go to the database, never to the JSON export." Nothing in the source says which of the two is canonical.
4. Corrections. Anything the agent got wrong twice in the same way.

Some things should stay out:

• secrets: passwords and keys never go into a file that is read into a model's context, and a project file is often committed to version control;
• facts the code already states clearly, such as the list of dependencies;
• one-off wishes ("make the button blue"), which belong in the request for that task;
• long explanations of why the project exists.

Agents follow concrete rules far more reliably than general ones. A rule is concrete when a third person could look at the result and say whether it was obeyed.

A useful habit is to end each rule with what "done" looks like. "Run the tests" leaves the agent free to skip them when it feels sure. "Run the tests and quote the summary line" gives it something to show.

Exercise 2. Find two vague rules in an instruction file you use, or invent two. Rewrite each so that a stranger could check compliance in under a minute.

The file is not read once. It sits in the context for the whole session, and with most current tools the model receives the full context again on every turn. A file of a few hundred lines is therefore paid for many times a day, in money and in attention.

Attention is the less obvious cost. A long file mixes ten rules that matter with forty that once seemed sensible, and the important ones are followed less well among the noise. The same happens with people handed a long induction manual.

Two practical consequences:

• keep the file short enough to read aloud in a few minutes, and move detail into separate documents that are opened only when the task needs them;
• when a rule is added, look for one that can go.

The mechanics of why repeated context dominates the cost of agent sessions are covered in Large language models/Context economy of agent runs.

An instruction file ages like any document. Commands change, folders move, and a rule that fixed a problem in March now blocks a legitimate change in October.

• Read the file from start to end every few weeks. Delete rules nobody can explain.
• Look for contradictions, especially between layers. When two rules clash, the agent picks one, and it will not always pick the one you meant.
• Some tools also let the agent write its own notes between sessions. Keep the two apart in your head: the instruction file holds what people decided; the agent's notes hold what it inferred. An inference can be wrong and should be easy to delete.
• If a rule seems ignored, first confirm the file was loaded at all. Many tools have a command or a log line that lists the instruction files in use. A misnamed file or a file in the wrong folder fails silently.

An instruction file is text that the agent is asked to follow. It is not a lock.

The agent may misread a rule, weigh it against the user's request and decide the request wins, or lose track of it late in a long session. For most rules this is acceptable: a wrong date format is easy to fix. For a rule that must never be broken (do not delete the backups, do not push to production) an instruction is the wrong tool. Such limits belong in a boundary enforced below the agent, for example file permissions or a separate account, as discussed in Artificial intelligence/Giving an AI agent access safely.

There is a second limit that is easy to miss. A repository someone else wrote may contain its own instruction file, and an agent started in that folder will load it. That file is text written by a stranger and placed where the agent treats it as guidance. Before running an agent inside unfamiliar code, open the instruction files yourself and read them.

Exercise 3. Take an instruction file and sort its rules into two columns: "annoying if broken" and "harmful if broken". For every rule in the second column, name the mechanism outside the file that would stop the harm.

• Start an agent in a small project without any instruction file and keep a log of every correction you make for one working session. At the end, turn the corrections you made twice into a file of no more than fifteen lines. Repeat the same task the next day and compare.
• Write the same five rules twice, once vague and once concrete (section 4). Give each version to an agent on the same task and count how many rules were followed.
• Open the instruction file of a public repository that has one. Mark each line as a check, a boundary, a convention or a correction. What is missing?

• Artificial intelligence/Giving an AI agent access safely
• Artificial intelligence/Checking AI output with a second agent
• Large language models/Context economy of agent runs