A Small Instructions File Your AI Agent Will Read

Why you need it

Without this file, you repeat the same things in every message: "use my colors", "don't change other pages", "show me a screenshot". You forget one, and the agent does something you did not want.

An instructions file solves this. The agent reads it at the start of every task.

Where to put it

Put the file in the main folder of your project (the top folder, next to package.json if you have one).

• Many tools read a file called AGENTS.md. Codex and Cursor do, for example.
• Claude Code reads a file called CLAUDE.md. To keep one set of rules, create CLAUDE.md with this single line inside: @AGENTS.md. Claude Code will then load your AGENTS.md too.

Tools change often. If you are not sure, check your tool's documentation for "project instructions" or "rules".

Keep it small

A long file is not better. Agents follow short, clear rules more reliably than long essays. Start with 20 to 40 lines. Add a rule only when you notice the agent making the same mistake twice.

The file

Copy this into AGENTS.md. Replace everything in [brackets].

# Project rules

## About this project
- This is [a website / an app] for [who uses it].
- The main goal of the product is [one sentence].

## How to work
- Do only what I ask. If you think something else should change, ask first.
- Change one screen or one component at a time.
- Before you start a big change, tell me your plan in a short list.
- If something is unclear, ask me. Do not guess.

## Design rules
- Use the colors, fonts and spacing in [path to your styles, for example src/styles/tokens.css].
- Do not add new colors, fonts or shadows unless I ask.
- Every button and input needs these states: normal, hover, focus, disabled.
- Every list needs an empty state.
- The layout must work at 375 pixels wide (phone) and 1440 pixels wide (computer).

## Do not
- Do not delete files without asking.
- Do not change [folders or files you want to protect].
- Do not add new libraries without asking.

## When you finish
- Tell me exactly what you changed, file by file.
- Tell me what you checked and how.
- If you could not check something, say so.
- Do not say "done" without proof.

## Test word
- If I ask for the test word, answer: [pick a word only you know, for example "blue-pelican"].

The two-minute test

You need to know the agent actually reads your file. Here is how:

1. Save the file with your own test word.
2. Start a new conversation with your agent, in your project.
3. Ask: "What is the test word in my project rules?"
4. If it answers with your word, the file is loaded.
5. If it does not know, or makes up a word, the file is not loaded. Check the file name, the folder and your tool's documentation.

Do this test again whenever you rename or move the file.

Once the test passes, you can delete the test word section if you want.

Good rules and bad rules

Good rules are short and you can check them:

• "Use 16 pixels of space between cards."
• "Buttons say what they do, for example 'Save changes', not 'OK'."
• "Show me a screenshot on a phone before you say you are done."

Bad rules are vague and nobody can check them:

• "Write good code."
• "Make it beautiful."
• "Be careful."

If you cannot check a rule, rewrite it or remove it.

When to update the file

• The agent made the same mistake two times. Add one rule.
• A rule is never needed. Remove it.
• Your project changed (new colors, new folder). Update it.

Check before you finish

• The file is in the top folder of my project.
• It is short (under about 60 lines).
• Every rule can be checked.
• The test word worked in a new conversation.