AI Agent Rules for Your Website: CLAUDE.md and AGENTS.md

An AI agent that edits your website will be exactly as consistent as the rules it reads before it starts. Give it none, and every session begins with a different idea of your voice. Give it a page of clear rules, and page 30 sounds like page 1, in every language, months apart.

This post is about writing that page. It comes from running beste.co through MCP for long enough to learn each rule the hard way. It is part of our MCP guide.

Why a rules document, not a good prompt

A prompt is written for one session. A rules document is read at the start of every session, by every client, by every person on the team. The difference shows up the third time you ask for a change and get a slightly different voice than the first two.

It is also the only place the agent can learn from your corrections. Anthropic's advice for Claude Code is direct about this: add to the file when the agent makes the same mistake a second time, or when you catch yourself typing the same correction you typed last session. A rules document is the record of those corrections.

Keep it short. Ours fits on one page, because an agent follows ten rules better than forty. Anthropic's memory documentation suggests keeping a CLAUDE.md under about 200 lines, notes that longer files reduce how well instructions are followed, and warns that when two instructions contradict each other the model may pick either one.

Where the document lives

The content is the same everywhere. The place differs by client:

Claude Code reads CLAUDE.md at the start of every session, from the project folder (./CLAUDE.md) and your user folder (~/.claude/CLAUDE.md). If the project has an AGENTS.md and no CLAUDE.md, recent versions read the AGENTS.md instead.
Codex reads AGENTS.md: a global file in ~/.codex/AGENTS.md, then one per directory from the project root down. OpenAI's AGENTS.md documentation gives a default combined limit of 32 KiB.
Claude and ChatGPT in the browser or on a phone: paste the same text into the project's instructions.
Cursor and others: their own rules files, with the same text.

The simplest setup we have found: keep one AGENTS.md in the project folder as the master copy. Claude Code and Codex both read it, and you paste it into your chat projects when it changes.

What goes in the document

1. Who is speaking

One paragraph on the site's voice, written as instructions, not adjectives. "Clean and clear, short sentences, no filler" beats "friendly and professional". Say who the reader is and what they already know. On beste.co, the reader is someone who builds websites or runs one, so we do not explain what a domain is.

Make each line checkable. Anthropic's own examples make the point: "use 2-space indentation" works where "format code properly" does not. For copy, "sentences under 20 words in body text" works where "keep it readable" does not.

2. The glossary

Words that always mean one thing, and words that are never used. Ours includes:

"section" is the unit of a page. Not "block", not "module".
"project" is a site in an account.
"AI agent edits" is what we call changes made over MCP.
In Turkish, "section" stays in English; in Spanish, it is "sección".
In Turkish, we prefer "yapay zeka" where the English says "agent".

Every term here was added after the agent used a different word in one place. A glossary grows one mistake at a time.

3. What it must never write

The phrases and habits that make copy read like default AI output. Ours:

No em dashes. Use a comma, a colon or a full stop.
No filler openers: "In today's world", "It's important to note", "Let's dive in".
No stacked adjectives, no "seamless", "robust", "powerful", "game-changing".
Do not describe a prompt as short or simple. Just say prompt.
No exclamation marks in body copy.

This list is the most valuable part of the document, because these habits are the ones an agent falls back on when it has nothing else to go on.

4. Facts it must not invent

An agent will write a price, an opening time or a claim with complete confidence. The rule is simple: facts come from the source material or they are left as a visible placeholder for a person to fill in. Never guessed. List the kinds of facts that count: prices, dates, hours, names, numbers, anything that reads like a promise.

For client sites, name the client's own material as the only source for these facts.

5. What it must never touch

Some parts of a site should change only when a person decides. Ours:

Legal pages. English only, never translated, never edited by the agent.
The theme, fonts and colors, unless the request is about design.
Redirects and robots.txt, unless the task is specifically about them.
Anything on the live site. All work goes to the draft.

6. Language rules, if the site has more than one

One block per language: form of address, which industry terms stay in English, what gets a local word, and any spelling choices. Ours say Turkish uses informal "sen" and never "siz", writes "zeka" without a circumflex, and keeps "grid" and "breadcrumb" in English. Spanish uses "tú", standard language with no regional dialect, and its own native tone rather than a translation of the English one. The whole story of how those rules came to be is in How We Built a Multilingual Website With MCP.

7. How to work

A few lines on method:

Read the page before changing it.
Make the change in the draft and say what changed.
Suggest options where the wording is a judgment call, and wait.
Do not add pages, sections or features that were not asked for.
Do not publish unless asked, in those words.

Rules are guidance, not locks

This is the part people get wrong. A rules file is context the model reads, not configuration it is forced to obey. Anthropic says this plainly about CLAUDE.md: the model reads it and tries to follow it, but there is no guarantee of strict compliance, especially for vague or conflicting instructions.

So split your rules into two kinds. Anything about voice, wording and judgment belongs in the document. Anything that must never happen, such as publishing without you or editing the live site, belongs in the server, where it is enforced whether the agent remembers the rule or not. The Beste server sends every change to the draft, publishes only on request, labels each tool read or write and needs a second call to delete a blog post, as described on the MCP server page. Keep the "never touch the live site" line in your document too, so the agent does not try, but do not rely on it alone.

The mistakes behind the rules

Every rule above exists because the agent did the opposite at least once. A few that stuck with me:

It translated a hero headline correctly and killed it. The meaning survived and the punch did not. The rule that came out of it: short marketing lines get a native rewrite, and the agent should suggest three versions rather than commit to one.
It added a feature to the pricing page that did not exist yet, because an internal note mentioned it. The rule: unreleased features are never on the site until a person puts them there.
It wrote "agent" in Turkish where our customers say "yapay zeka". The rule went into the glossary the same day.
It called a prompt "short and simple" in three places, which reads like a sales pitch. Now the word prompt stands alone.

None of these were the agent's fault. They were missing rules. The document is the record of what we learned.

How to test your rules

A rule you have not tested is a hope. Three checks we run:

Ask it to repeat them back. Start a new session and ask the agent to list the rules it is working under. If one is missing, the file did not load, or the rule is buried.
Run the same request twice. Ask for the same small change in two fresh sessions and compare the results. Where they differ, a rule is missing or vague.
Read it monthly. Delete rules that no longer apply and merge ones that say the same thing. Old, contradicting rules do more harm than missing ones.

Rules for client sites

If you build sites for others, keep two layers. A studio file holds the method and the "never write" list, the same for every client. A short client file holds that client's voice, glossary and facts sources. In Claude Code and Codex, a file in each client's project folder does this naturally. The agent reads both, and a new client only needs the small file.

A template to start from

Copy this, fill it in, and add to it every time you fix something.

# Rules for editing [site name]

## Voice
[Who is speaking, who is reading, sentence length, what to leave out.]

## Glossary
- [term]: always means [meaning]. Never [alternative].

## Never write
- No em dashes.
- No filler openers.
- [Your list.]

## Facts
Prices, dates, hours, names and claims come from [source]. Never guessed. Leave a visible placeholder if unknown.

## Never touch
- [Legal pages, theme, redirects, anything live.]

## Languages
- [Language]: [address form, terms that stay in English, spelling choices.]

## Method
Read before writing. Draft only. Say what changed. Suggest, then wait. Publish only when asked.

And a filled-in fragment, so you can see the level of detail that works:

## Voice
We are a small studio talking to restaurant owners. Short sentences.
No jargon a chef would not use. Never more than one exclamation mark per page.

## Facts
Menu prices come only from menu.csv in this folder. Opening hours come
only from hours.md. If either is missing, write [PRICE] or [HOURS].

How this works in Beste

The Beste MCP server works with whatever rules you give your client. In Claude Code and Codex, keep the file in the project folder. In Claude with the connector or ChatGPT with the plugin, put it in the project instructions. The server adds its own layer underneath: every change goes to the draft, tools are labeled read or write, errors name the field, and publishing happens only on request. The rules shape what the agent writes. The server limits what it can break.