Rules Files

By the Syncfusion DevTutorials team · Last updated October 22, 2026

Why the agent only knows what is written in the repo, how one rules line fixes the wrong test command, and why a 600-line AGENTS.md gets half-ignored. You turn it into a short map that points into docs/.

What Rules Files Do

A rules file is a short file in your repo that tells the agent how to work there. Examples are AGENTS.md and CLAUDE.md.

The agent reads it at the start of every run.

It is also the only place where your team's habits can reach the agent.

For example:

• "We use pnpm, not npm."
• "Never touch the production settings."
• "New components go in src/components."

If none of these are written down, the agent does not know them.

In this lesson, you will fix a wrong test command with one line. Then you will turn a long rules file into a short map.

A Real-World Example

Think about a new hire on their first day.

Option one: you hand them a 600-page binder. "Everything is in there."

They read the first 50 pages. They miss the one page that says "never touch the live database".

Option two: you hand them one page with the three rules that matter most. It also says where to find the rest.

A rules file works the same way:

1. The root file is the one-page sheet. The agent reads it every time.
2. The docs/ folder holds the guides. They load through pointers in the sheet.

Click the button and watch the agent in the Harness Lab.

• The rules file: it says "run the tests", but not how.
• The command it types: the one most projects use.
• The terminal: it says no.

Simple lesson: the agent is not careless. It cannot see a fact that lives only in someone's head.

What You Will Learn

In this lesson, you will learn:

1. Why the repo must hold every fact that the agent needs.
2. How to fix the wrong test command with one rules line.
3. Which rules lines the agent can use, and which it ignores.
4. What the context budget is.
5. Why a long rules file gets half-ignored.
6. How to turn a long file into a short map into docs/.
7. How to start a rules file in your own repo.

The Repo Is the System of Record

What the Agent Cannot See Does Not Exist

System of record = the one place where the true answer is kept.

For an agent, that place is the repo.

A person learns team habits over coffee. An agent starts each session with only the files in the repo.

Facts in chats, wikis or heads do not exist for the agent.

One Line Fixes the Guess

The agent made a mistake. Do not correct it in the chat.

Add one line to the harness instead.

Step through all five frames.

• Frame 1: the test line names a moment, but no command. The note says the agent ignores it.
• Frames 2 and 3: the agent guesses on both projects. Both guesses fail.
• Frame 4: one line now names pnpm test in backticks.
• Frame 5: the same agent fixes the bug and checks its work.

A good rules line names the exact command:

- Run `pnpm test` after every change, and before you say you are done.

- Run `dotnet test` from the repo root, so the test project runs too.

Exact Lines Become Facts

Fact = something exact that the agent can act on. A command, a file it must never edit, or a pointer to a doc.

The agent turns each rules line into facts. A vague line gives no fact.

Lab Exercise: Fix the Command

Now fix it yourself.

Click the button to open the rules file in the lab.

1. Add the real test command to the test line.
2. Press Check my harness.
3. The agent must use it on all 3 versions of the bug.

Simple lesson: name the exact command, in backticks. One line fixes the mistake for every future session.

Why Long Rules Files Fail

The Context Budget

The rules file sits in the context window (see Coding Agents). It shares that space with the files the agent reads and its command results.

Context budget = how much of that space the rules file should use.

Real tools usually load the whole rules file. Codex caps its size, by default at 32 KiB.

But a long file still hurts. The agent gives each rule less attention, so important rules get lost.

See the Budget Fill Up

This rules file has everything anyone ever said. The three critical rules are at the very bottom.

Step through all five frames.

• Frame 1: almost every line is vague advice. It gives no fact.
• Frames 2 and 3: the meter fills from the top. Most of the file is past the lab's budget.
• Frame 4: the three rules that matter are at the bottom, past the budget.
• Frame 5: the agent guesses the test command again.

Run It in the Lab

Click the button, then open the Inspector tab.

• Dropped lines: hundreds of lines fall past the lab's budget.
• The command: the agent guesses again.
• The facts: none of the critical rules made it in.

Simple lesson: more rules does not mean safer. Fewer, exact rules do.

A Short Rules File as a Map

The Shape of a Good Root File

A good root rules file is short. OpenAI's Codex team reports keeping theirs at about 100 lines.

It works as a table of contents over a docs/ folder.

Map = a short root file with two parts:

1. Always: the few rules that apply to every task. Put them at the top.
2. Where things are: pointers into docs/ for everything else.

Pointer = a line that names a docs file, such as docs/testing.md. The agent loads that file through it.

Here is a short map for the React project:

# Rules for agents (map)

## Always
- Read the failing test and the file you plan to change before you edit anything.
- Run `pnpm test` after every change, and before you say you are done.
- Never edit `.env.production`. Only the release team changes it.

## Where things are
- Conventions: docs/conventions.md
- Ticket statuses: docs/statuses.md

See the Map Work

Step through all five frames.

• Frame 1: every line in the map gives a fact.
• Frame 2: the meter is almost empty. Nothing is dropped.
• Frame 3: each pointer loads one docs file, with its own budget.
• Frame 4: the agent passes all 3 versions of the bug.
• Frame 5: take out the "never edit" line, and the agent changes the production file.

Lab Exercise: Trim It to a Map

Now fix the 600-line file.

Click the button to open the long file in the lab.

1. Replace it with a short map. Keep the critical rules at the top.
2. Add pointers into docs/ for the rest. You can create docs files with the box under the file list.
3. Press Check my harness.

To pass, the root file must be 200 lines or fewer. The agent must follow every critical rule on all 3 versions.

Simple lesson: trim to a map, then check that the agent still follows every rule.

The Rules File in Each Tool

All three tools can read AGENTS.md.

Claude Code reads CLAUDE.md. One line, @AGENTS.md, pulls in the shared file.

This course writes one AGENTS.md and exports the right files for each tool.

Simple lesson: one shared file, with a small shim per tool.

Try It in Your Own Repo

Day 1 takes about ten minutes. Pick one real project.

1. Create the rules file. Claude Code and Codex both have an /init command that drafts one. In Cursor, create the rules file yourself, or ask the agent to draft it.
2. Trim it to a short map. A generated file is a first draft, full of guesses. Delete every vague line.
3. Add the exact test command, in backticks.
4. Add one "never edit" line for a file that matters, such as the production settings.
5. Give the agent one small, real bug. Watch two things: does it read first, and does it run the tests?

If it skips one, a line is probably missing or vague. Fix that line, not the chat.

Simple lesson: start small, then watch the agent and fix the rules file it actually needed.

TL;DR

1. System of record = the repo. If a fact is not in it, the agent does not know it.
2. Rules file = a short file, such as AGENTS.md, that the agent reads every run.
3. Fact = an exact thing the agent can act on: a command, a protected file, a pointer.
4. Context budget = how much of the context window the rules file should use. Past it, rules get lost.
5. Map = a short root file. Critical rules at the top, pointers into docs/ for the rest.
6. Pointer = a line that names a docs file, so the agent can load it.

Common mistakes

Check Your Understanding

Exercises

Press Check when you are ready. Use Show Hint if you get stuck.

What to Remember

• The repo is the system of record. If it is not written down, the agent does not know it.
• Name exact commands in backticks.
• Only exact lines become facts. Vague lines are ignored.
• A long rules file buries its important rules. Keep it short.
• Keep the root file a short map: critical rules at the top, and pointers into docs/.
• Read and edit every line of a generated rules file.

Further Reading

• Harness engineering: leveraging Codex in an agent-first world, by OpenAI: AGENTS.md as a short table of contents over a structured docs/ folder.
• Harness engineering for coding agent users, on martinfowler.com: why the agent needs the knowledge in the repo.
• awesome-harness-engineering, by walkinglabs: more on rules files and context.
• The Context Engineering course on this site goes deeper into context budgets.

Next: Agent Skills. You will teach the agent to do a job with several steps the same way every time.