# Rules

Long-lived markdown instructions that shape how an agent behaves across every task.





A rule is a piece of markdown the agent should follow when it's relevant to the task. Style guides, escalation procedures, project conventions, "always do X before Y", "never touch this directory". Rules are the standing orders that don't change between conversations.

Rules live at the org level and attach per-agent, the same way [skills](/help/skills) and [MCP configs](/help/mcp) do.

## Mental model [#mental-model]

* A **rule** has a title, a description, and a markdown body.
* The **description** is what the agent reads to decide whether the rule applies to a given task. Write it like a trigger: *"Apply this when reviewing pull requests"*, not *"PR review style"*.
* The **body** is the rule itself — markdown, as long or short as it needs to be.
* Rules live at the **org level**. Attach the ones you want to a specific agent from the Configuration tab.

## When to reach for a rule [#when-to-reach-for-a-rule]

| Use a...                                                                          | When...                                                                                                                   |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Rule**                                                                          | The agent needs to always follow a policy or convention when it's relevant. *"How we write commit messages."*        |
| **[Skill](/help/skills)**                                                         | The agent needs to *do* a thing with specific steps or a script. *"Open a Linear ticket from a Slack message."* |
| **System prompt**                                                                 | The instruction is identity-level and applies to every task. *"You are the on-call SRE bot."*                        |
| **[CLAUDE.md / AGENTS.md](https://code.claude.com/docs/en/settings) in the repo** | The convention is repo-specific and should travel with the code.                                                          |

If you're not sure whether something is a rule or a system prompt: if it's long, has multiple sections, or you'd want to attach it to some agents but not others, it's a rule.

## Creating a rule [#creating-a-rule]

1. Open [Settings → Artifacts → Rules](https://app.nairi.ai/settings/artifacts?tab=rules).
2. Click **New Rule**. The form has three fields.

| Field                  | Required | Purpose                                                                                                                                                                           |
| ---------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Title**              | yes      | Short name. Shown in the agent editor's rules list, e.g. *"Code Style Guide"*.                                                                                               |
| **Description**        | yes      | One sentence the agent reads to decide whether to load the rule. The dashboard tells you: *"This description is shown to the AI agent to determine when to load this rule."* |
| **Content (Markdown)** | yes      | The body of the rule. Free-form markdown.                                                                                                                                         |

Click **Create Rule**. The rule is saved at org level and immediately available to attach to any agent.

### Writing a description the agent will actually use [#writing-a-description-the-agent-will-actually-use]

Like with [skills](/help/skills#writing-a-description-the-agent-will-actually-use), the description carries the load. The agent doesn't read the body until it has decided the rule is relevant, and that decision comes from the description.

Good descriptions are concrete and trigger-shaped:

* ✅ *"Apply when reviewing pull requests, writing code review comments, or commenting on a diff."*
* ❌ *"Code review style."*

If the rule only matters in a specific context, name that context. If it should always apply to any task that touches the codebase, say that too.

### Writing the body [#writing-the-body]

Plain markdown. No frontmatter needed — the dashboard handles title and description separately.

```markdown
When reviewing a pull request:

- Focus on correctness and edge cases first.
- Flag missing tests.
- Don't suggest stylistic changes the linter would catch.
- Keep comments short. Link to the line if you need to elaborate.

If the PR is from a junior engineer, lead with what's good before what's wrong.
```

Keep each rule **focused on one topic**. A rule that tries to cover code style, security policy, and PR review at once becomes a rule the agent can't tell when to load. Three small rules with three sharp descriptions beat one big rule.

## Attaching to an agent [#attaching-to-an-agent]

Open the agent in [Fleet](https://app.nairi.ai/agents/fleet), scroll to **Agent Rules** on the Configuration tab, tick the checkboxes for the rules you want, click **Save & Redeploy**.

Each agent's set of rules is rebuilt on every deploy from the boxes that are ticked. Unticking a rule and redeploying cleanly removes it.

## How rules reach the agent at runtime [#how-rules-reach-the-agent-at-runtime]

The wiring differs slightly per CLI. The behaviour you can rely on:

* **Claude Code (default):** each rule is written as an individual file under `~/.claude/rules/`. Claude Code reads the description from each file's frontmatter and loads the body only when it judges the rule relevant to the current task.
* **OpenCode** and **Codex:** all attached rules are concatenated into a single `AGENTS.md` (under `~/.config/opencode/` and `~/.codex/` respectively). The agent has the full content in scope on every task, with a header instruction to follow each rule when relevant.

Either way, the description matters: it's how the model decides which rule fires when.

<Callout type="info">
  On a self-hosted runtime, the same files are written to your machine's filesystem. You can verify what's been deployed by inspecting `~/.claude/rules/` or `~/.codex/AGENTS.md` directly.
</Callout>

## Examples [#examples]

### A code-style rule [#a-code-style-rule]

**Title:** Python style for this repo
&#x2A;*Description:** Apply when writing, editing, or reviewing Python code in this repository.
&#x2A;*Body:**

```markdown
- 4-space indentation, no tabs.
- Type hints required on every public function. `Any` is allowed only with a comment explaining why.
- Use `pathlib.Path`, never `os.path.join`.
- Tests go in `tests/` and use `pytest`. No `unittest`.
- Avoid bare `except:` — catch the specific exception or re-raise.
```

### A security policy rule [#a-security-policy-rule]

**Title:** Never log secrets
&#x2A;*Description:** Apply whenever you're adding logging, writing tests, or generating example output.
&#x2A;*Body:**

```markdown
Never include API keys, tokens, passwords, or PII in:
- Log statements (including DEBUG/INFO).
- Test fixtures or assertions.
- Example output in comments or docstrings.
- Error messages returned to the user.

Use placeholders like `<REDACTED>` or env var names (`$STRIPE_API_KEY`) instead. If you're not sure whether something is sensitive, treat it as sensitive.
```

### A communication rule [#a-communication-rule]

**Title:** Slack tone
&#x2A;*Description:** Apply to every message you post in Slack or Discord.
&#x2A;*Body:**

```markdown
- Be brief. One paragraph max unless explicitly asked for detail.
- Lead with the answer. Save context for follow-up questions.
- No emoji decoration. Plain text reads better in threads.
- If something is uncertain, say "I don't know" rather than guessing.
```

## Editing and deleting [#editing-and-deleting]

* **Edit:** Open [Settings → Artifacts → Rules](https://app.nairi.ai/settings/artifacts?tab=rules), click the rule's title. Changes apply on the next agent redeploy.
* **Delete:** Same page, trash icon on the row. The rule disappears from every agent it was attached to on next deploy.

There is no version history. Keep important rules in your own git if you want a paper trail.

## Related [#related]

* [Adding rules to an agent](/help/building-agents/how-to-deploy#agent-rules) — where to tick the boxes in the agent editor
* [Skills](/help/skills) — for capabilities the agent *does* rather than principles it follows
* [Vaults](/help/vaults) — for credentials, not policies
* [API: Rules](/api/rules/overview)

***

*Can't find what you're looking for? Email [support@nairi.ai](mailto:support@nairi.ai).*