Rules in an agent setup

Rules are the instructions every agent in a setup follows. An agent setup is a named bundle of what your AI coding tools work with: skills, agents, rules, MCP servers and setup files. A setup has one rules text, written in Markdown and up to 50,000 characters long. It is the place for what holds across the whole repository: coding conventions, the commands that build and test the project, and the boundaries an AI agent must keep to.

The web app titles the rules AGENTS.md, after the file that many AI tools read them from. Installing the setup writes the rules into the rules file of each AI tool you selected, which is AGENTS.md for some tools, CLAUDE.md for Claude Code and another file for others.

You need the owner or editor role to change the rules. A viewer can read them. The roles and permissions page has the full list.

Write or edit the rules

Edit the rules when a convention should apply to every agent and every skill, for example that the web shop's prices are stored in minor units and never as floating-point numbers.

1. On the Setups page, select the setup's card. Its blueprint appears below the cards.
2. On the blueprint, select the AGENTS.md part. The rules open in the inspector, under the title Rules.
3. Select the text and write the rules in Markdown. An empty setup shows No rules yet.
4. Save the text.

The inspector shows the number of words and the number of characters used out of 50,000. Text beyond 50,000 characters cannot be entered, so move long reference material into setup files and mention the file in the rules.

The rules of the standard Athenode setup have the sections "MCP", "Settings", "Questions", "ToDo cards" and "Language". The built-in skills and agents rely on them, so keep those sections when you add rules of your own to your project's copy of the standard setup. Athenode updates the rules of that copy only while you have not changed them.

Find the rules in your repository

The rules reach your repository when you install the setup with init, and again each time you run init after changing them in the web app.

npx @athenode/cli init

Which files are written depends on the AI tools you selected. Several tools read the same file, and it is written once.

Rules file	AI tools that read it
AGENTS.md	Codex, OpenCode, Google Antigravity, Devin, Kiro, Kilo Code, Qoder, Mistral Vibe, Factory Droid, Codewhale, Grok CLI, Command Code, Rovo Dev, MiMo Code, ZCode, Zoo Code, IBM Bob, Pool
CLAUDE.md	Claude Code
.github/copilot-instructions.md	GitHub Copilot
.junie/AGENTS.md	JetBrains Junie
.goosehints	Goose
QWEN.md	Qwen Code
.omp/AGENTS.md	oh-my-pi
.kimi-code/AGENTS.md	Kimi Code
CODEBUDDY.md	CodeBuddy Code
REASONIX.md	Reasonix
.rovodev/AGENTS.md	Rovo Dev, in addition to AGENTS.md
.deepagents/AGENTS.md	deepagents-cli
.cursor/rules/athenode.mdc	Cursor, when no other selected tool has AGENTS.md written. Otherwise Cursor reads AGENTS.md.
.augment/rules/athenode.md	Augment Code

With Claude Code as the only selected tool, the rules are in CLAUDE.md and no AGENTS.md is written. With Claude Code and Codex selected, both files hold the same rules. The files installed per tool page lists everything else that is written for each of the 30 supported AI tools.

Keep your own content beside the Athenode rules block

In every file of the table except the last two, the rules sit in the Athenode rules block, between two marker comments. Everything outside the block is yours and is kept.

<!-- athenode:rules:start -->
(the rules of the installed setup)
<!-- athenode:rules:end -->

Your own notes and instructions for this repository,
kept as you wrote them.

init treats the block as follows:

• If the file does not exist, init creates it with the block.
• If the file exists and has no block, the block is added at the top and your content follows it.
• If the file has a block, the block is replaced where it stands and the rest of the file keeps its position.
• If you install a different setup, the previous setup's block is replaced by the block of the setup you chose.

Changes you make between the markers are overwritten by the next install. Change the rules in the web app, and write your own notes outside the block. .goosehints is a plain text file, so Goose reads the two marker lines as text along with the rules.

.cursor/rules/athenode.mdc and .augment/rules/athenode.md have no block. Each of the two files holds the setup's rules and nothing else, and the next install overwrites the whole file. Keep your own Cursor or Augment Code rules in other files of the same folders.

The troubleshooting page has the steps for repairing a rules block.

Change the rules from your AI tool or the terminal

From your AI tool, ask /atn-manage to show or change the rules. It warns you before a change that drops one of the sections the standard setup relies on, and it updates the installed files itself when the rules belong to the installed setup.

From the terminal, athenode rules get prints the rules and athenode rules update replaces the whole text. A value that starts with @ is read from a local file. The Athenode CLI reference has every option.

npx @athenode/cli rules update --content @./rules.md

Rules can also be copied from another setup. When you pull from another setup or merge an entry of the setup library, you choose whether to keep your rules, append the other rules to them or replace yours.