CLAUDE.md and AGENTS.md: rules for AI code in a team

CLAUDE.md and AGENTS.md are files in the repository that an AI agent loads with every task to learn the team's rules. Rules for AI code in a team belong there, not in a senior's head. A short file for the agent, CLAUDE.md or AGENTS.md, says how work gets verified and what the agent must not do. But the most important rules should not be text. They should be lint, tests or CI that stop a bad change on their own.

AI writes all of our code today, and a senior is accountable for the result. Since 2023 we have delivered 15+ production projects. Before that, Filip spent 7 years in the product team of a SaaS that 60,000+ people used every day. We learned the rules below on these projects, mostly from our own mistakes.

What belongs in CLAUDE.md or AGENTS.md?

What the agent cannot work out from the code, and what you do differently from everyone else. Specifically:

• How to run the project and the tests. Ideally one command the agent can copy.
• What the agent must not do. The production database, secret keys, migrations without approval, pushing straight to the main branch.
• Where things are. Where the business logic lives, where the tests are, what is generated and must not be edited by hand.
• Conventions that are not standard. How you name things, how you handle errors, where translations live.
• What finished work looks like. What has to pass before the agent opens a pull request.

What does not belong there: style the formatter already enforces. Long essays on architecture. Rules that only apply in one folder.

CLAUDE.md or AGENTS.md?

Claude Code reads CLAUDE.md. Many other tools, such as Codex, read AGENTS.md. If your team uses several tools, don't write the rules twice.

Keep them in AGENTS.md and point to it from CLAUDE.md with the line @AGENTS.md. Claude Code then loads it on its own. Two separate copies drift apart before anyone notices.

How many rules is too many?

You hit the limit sooner than you'd expect. The agent loads the rules on every run. The more text it has in context, the worse it sticks to what matters.

Splitting them into three levels works well for us. The repository root holds the minimum that applies everywhere. The rules of one module sit in a file inside its folder, and the agent loads them only when it works there. The most important rules are lint or tests: nobody has to read them, they stop a bad change on their own.

To be honest: we don't have a perfect answer. Rules pile up with every mistake. So we clean them up regularly and move everything we can into lint.

Where do you get rules when you don't have any yet?

From review. A comment that comes up in review a second time is not a developer's mistake. It is a hole in the rules. The process is simple:

We often recommend letting the agent go through old review comments and pull rules out of them. It only works when the comments exist. If review happens only out loud, on a call, nothing makes it into the pull requests. The agent then has nothing to work from.

So habit first, tool second. Write feedback into the pull request, not just out loud.

Where does each rule belong?

An agent can get around a ban written as a sentence. It won't open a file, but it writes a script that prints it. So for every rule we write down what enforces it.

The agent that works on its own for us runs in a separate virtual machine. From there it cannot reach live operation or secret keys. A hook that rejects a dangerous command is a good first step. But it is a speed bump, not a wall: a clever agent finds another way. No sentence saying "be careful" replaces either.

The template has the table and the bans with what enforces each one. Download the template: Rules for AI in your team (PDF).

How do you share rules across several repositories?

Through distribution, not discipline. We kept our rules in the main repository and the others couldn't see them. Some copied them. A few months later there were several versions and no two were the same.

Today we have one package of rules that loads in every repository. It is versioned and changes only through an approved pull request. There are no copies, so nothing can drift. Personal rules are each developer's working style. Shared rules belong to the company, and they have to live in one place. We set up the same rules package for teams we join as part of AI-native SDLC for development teams. Is your team short of hands rather than rules? See a senior developer for your team.

Review and tests: rules that aren't in the file

Some rules belong not to the agent but to the process around it. Which of these does your team already have?

A test that never failed only proves that the agent agrees with itself. And a pipeline that only reports is decoration.

How to introduce these rules across the whole team step by step is covered in How to introduce AI into a development team. Why the harness matters more than the model is explained in Agent = model + harness. If the team is still choosing a tool, see Cursor vs Claude Code.

When we don't recommend it

• You are one or two developers in one repository. A short CLAUDE.md or AGENTS.md is enough. Write it yourselves from the list above.
• You have no tests and no CI that blocks. Agent rules will not change much then. Tests and CI first, rules after.

• You expect a template to replace your reviews. It will not. Rules come from your reviews, so start with feedback in pull requests.

Want to set up the rules with someone who works with them every day?

We look at your repositories and propose a first version of the rules and the CI gates. A senior plugs into your repository and pull requests on day one.

We get back to you within two business days, and together we pick what to fix first.

If you'd rather talk first, book a 15-minute meeting with Filip.

Where do your team's rules live today?

Frequently asked questions

What is CLAUDE.md?

A file in the repository that Claude Code loads every time it runs. It holds the rules for the agent: how to run tests, what it must not do and what finished work looks like. Other tools read a similar file called AGENTS.md.

CLAUDE.md or AGENTS.md?

If the team only uses Claude Code, CLAUDE.md is enough. If it uses several tools, keep the rules in AGENTS.md and point to it from CLAUDE.md with the line @AGENTS.md. Two separate copies drift apart over time.

How many rules should CLAUDE.md have?

As few as possible. The agent loads them on every run, and too much text makes its results worse. Keep only what applies everywhere at the root. Put the rest into folders, and the most important rules into lint or tests.

Who should own the rules for AI in a team?

One named person who approves changes. Anyone can write them through a pull request. Without an owner, everyone adjusts them their own way and the shared layer falls apart.

Is it enough to tell the agent what it must not do?

No. An agent can get around a written ban. Enforce what really matters with access rights, a hook, lint or CI. For every rule, write down what enforces it.