Lesson 12.412.4 Rules the agent reads

In everyday life. A good restaurant keeps a notebook by the back door for new cooks. It says where the knives go, which sauces are made fresh each morning, which supplier never to call, and the one rule that gets you fired. Nobody reads all of it each day. But every new cook reads it once, and the head chef updates it whenever someone makes the same mistake twice.

What you will learn. How to write one short AGENTS.md that every agent reads, what adding a CLAUDE.md changes, and how to back a rule that must never break with a setting.

Why it matters. The agent cannot see your company's unwritten rules. What you write down, it reads in every session, and what a setting enforces, it cannot skip.

What is a rules file?

A coding agent is a new cook every session. It starts knowing nothing about your project, and the rules file is its notebook: a plain markdown file at the top of the repository that the agent reads at the start of each session. It tells the agent what the project is, how to build and test it, and the rules your team cares about.

The usual name for this file is AGENTS.md. It is an open format, a README for coding agents.¹ Codex, OpenCode, Cursor and GitHub Copilot's coding agent are among the tools that read it,¹ and Claude Code reads it too.² No AI vendor owns it: the Agentic AI Foundation, under the Linux Foundation, looks after it.¹ So start simple, with one AGENTS.md, and every agent you use gets the same rules.

What goes in it?

Keep it short and specific. A good rules file answers five questions:

Write rules the agent can follow and you can check. "Write good code" is not a rule. "Run npm test before you say you are done" is.

You do not have to start from nothing. Most coding agents can draft the file: ask in plain words, or run the tool's setup command, often /init. Read the draft, correct what it guessed wrong, and add the rules only your team knows.

What if the project also has a CLAUDE.md?

Claude Code also has a file of its own, CLAUDE.md. When a project has one, or a personal CLAUDE.local.md, Claude Code reads that instead of AGENTS.md.² So one team can have two sets of rules without anyone choosing that, and Claude Code's /init command writes a CLAUDE.md, so it is easy to do by accident. The fix is one line. Make @AGENTS.md the top line of CLAUDE.md, which pulls the whole file in, and add lines below it only for rules that apply to Claude Code alone.² 12.7 shows the steps in each tool.

Can rules live in more than one place?

Yes, at three levels, and agents combine them.

• Personal rules in your home folder apply to every project you open. "Explain commands before running them" is a personal rule.
• Project rules at the top of the repository apply to everyone who works on it. They belong in git, so the whole team shares and reviews them.
• Folder rules inside a subfolder apply only when the agent works there. "Tests in this folder use the fixed sample file" is a folder rule.

If two levels disagree, the AGENTS.md format says the file closest to the work wins, and what you type in the chat overrides every file.¹ Products do not all keep to that: Anthropic warns that Claude may pick either of two rules that contradict each other.² So keep the levels consistent. Settings have levels too, and in many products a rule that forbids an action wins over a rule that allows it, whatever level each is at.

Figure 12.4. Rules in layers. The agent combines them, and folder rules may load only when it works there. Layers that disagree make it unpredictable, so keep them consistent. Permission settings have their own order.

Can a rules file stop a mistake?

Not on its own. The notebook can tell a cook never to call that supplier, but it cannot take away the phone. A rules file is advice the agent reads, not a lock. An agent follows it most of the time, but in a long session it gets less attention (12.5). What a long session loses first is a rule you only typed in the chat, so move those into the file.²

So anything that must never happen gets two guards: a line in the rules file, which explains the rule, and a setting, which enforces it. A permission rule that denies edits to data/, or reading a file, blocks it even when the agent forgets the line. Settings files can live in the repository too, so the whole team gets them, though some products apply a repository's settings only after you confirm you trust the folder. Git stays the third guard, because no rule covers every way a file can change.

How do I keep it useful?

Do what the head chef does. Each time the agent makes a mistake that a sentence would have prevented, add the sentence. Each time a rule stops being true, delete it. A rules file that is long, vague or out of date is worse than a short true one, because the agent does what it says.

Keep it lean too. Everything the agent reads at the start costs context, even the parts it never uses. Every few weeks, check what it loads, and remove rules that are out of date or that contradict each other. After a model change, also look for lines written for the older model.

What else can the agent read?

A few other kinds of saved instruction, each a plain file in the repository or your home folder. You do not need them yet, and later chapters build them.

You can make one in 12.7's practice. Some products save a command as a skill. Chapter 16 builds skills and commands into a plugin, and Chapter 25 builds subagents.

A plugin is a program, not advice. It runs with the same rights as you: it can do anything you can do on this computer. Install only plugins you would be happy to run yourself, from a source you trust, and read what a new one does before you turn it on.

At work. Ana asked the agent for a first draft of Brightline's rules file. It listed the folders and the test command correctly. It could not know the rule that mattered most, because no file says it: the files in data/ must never be changed, because every script and test depends on them. So she added one line, "Never write to data/.", and a setting that denies those edits.

The operating rule: keep one short, true AGENTS.md in the repository, shared by every agent you use, and add a line each time a mistake could have been prevented by one.

Practice it. Practice: the rules file, in your own tool, twenty minutes.