> ## Documentation Index
> Fetch the complete documentation index at: https://cubed3-pavel-claude-modest-planck-ceg4c0.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Rules

> Define instructions in your data model repository that guide the agent's behavior.

Rules are instructions that guide the agent's behavior — encoding business definitions, calculation methods, domain terminology, and analytical approaches the agent should follow when answering questions.

Rules are configured as code in your [data model repository](/admin/ai#agent-configuration), alongside your cubes and views. This enables version control, code review, and consistent behavior across environments.

## Rule types

| Type | When applied | Best for |
| - | - | - |
| `always` | Injected into every agent interaction. | Fundamental business definitions, default calculations, domain terms. |
| `agent_requested` | Conditionally applied when the agent determines the rule is relevant to the current request. | Scenario-specific guidance, specialized analysis methods. |

For `agent_requested` rules, the `description` field is what the agent matches against the user's request to decide whether the rule is relevant — write it as a short summary of when this rule applies. `always` rules don't need a `description` since they're injected into every interaction regardless.

## Defining rules

Rules are defined as Markdown files under `agents/rules/`. Each rule lives in its own file: the YAML frontmatter holds metadata, and the Markdown body is the rule prompt.

```markdown theme={null}
<!-- agents/rules/fiscal-year.md -->
---
type: always
---
Always use fiscal year starting April 1st when analyzing dates.
Q1 is April–June, Q2 is July–September, Q3 is October–December, Q4 is January–March.
```

For `agent_requested` rules, add a `description` so the agent can decide when the rule applies:

```markdown theme={null}
<!-- agents/rules/cart-abandonment.md -->
---
description: "Apply when the user asks about cart abandonment"
type: agent_requested
---
For cart abandonment analysis, segment by device type and traffic source.
```

Files placed under a `rules/` directory are treated as rules automatically — no `kind` property is required. The `name` is inferred from the file name (e.g., `fiscal-year.md` → `fiscal-year`).

### Frontmatter properties

| Property | Type | Required | Description |
| - | - | :-: | - |
| `name` | string | No | Unique identifier. Inferred from the file name if omitted. |
| `description` | string | No | Required for `agent_requested` rules — used by the agent to decide when the rule applies. Optional and unused for `always` rules. |
| `type` | string | Yes | Either `always` or `agent_requested`. |
| `prompt` | string | No | Rule prompt. Falls back to the Markdown body if omitted. |
| `conditions` | list | No | Applies the rule only to users who meet all of them. See [Limiting a rule to some users](#limiting-a-rule-to-some-users). |

### Inlining rules in YAML

You can also inline rules directly in `agents/config.yml` under a `rules` key:

```yaml theme={null}
# agents/config.yml
rules:
  - name: fiscal-year
    prompt: "Always use fiscal year starting April 1st when analyzing dates."
    type: always

  - name: efficiency-analysis
    description: "Apply when the user asks about sales efficiency"
    prompt: "When analyzing sales efficiency, calculate as deal size divided by sales cycle length."
    type: agent_requested
```

Inline rules accept the same properties as Markdown rules — `name`, `description`, `prompt` (required), `type` (required), and `conditions`.

<Note>
  Rules inlined at the root of `agents/config.yml` are attached to the implicit `auto` space and applied to the default agent in a [single-agent setup](/admin/ai). In a [multi-agent setup](/admin/ai/multi-agent), attach rules to a specific space by inlining them under that space's `rules` key (or by placing Markdown files under `agents/rules/<space-name>/`).
</Note>

## Limiting a rule to some users

By default, a rule applies to every user of the agent. Add `conditions` to apply it only to users who meet all of them — for example, one client's naming conventions in a deployment that serves several clients through [signed embedding](/embedding/iframe/auth/signed).

```markdown theme={null}
<!-- agents/rules/acme-campaigns.md -->
---
type: always
conditions:
  - user_attribute: marketplace_id
    values: ["acme", "acme-eu"]
  - groups: [analysts, managers]
---
Campaigns named `us#...` are US campaigns.
```

| Condition | Holds when |
| - | - |
| `user_attribute` + `values` | The user's [attribute](/admin/users-and-permissions/user-attributes) equals one of `values`. |
| `group` | The user is in this [group](/admin/users-and-permissions/user-groups). |
| `groups` | The user is in any of these groups. |

* Conditions see the same user attributes and groups as [access policies](/docs/data-modeling/data-access-policies). A user without the attribute or group doesn't get the rule.
* `values` are strings. Quote numbers and booleans (`"00123"`, `"true"`) — YAML would read an unquoted `00123` as `123`.
* Only `conditions` limits a rule. Any other key on a rule without `conditions`, such as `marketplace_id: acme`, is ignored, and the rule applies to everyone.

<Warning>
  Conditions decide which instructions the agent receives; they don't restrict data. Use [access policies](/docs/data-modeling/data-access-policies) to control what each user can query.
</Warning>

## Writing effective rules

Good rules are specific, actionable, and encode context the agent wouldn't otherwise know about your business.

**Do:**

* "Customer churn rate is customers lost ÷ total customers at the start of the period."
* "When analyzing quarterly performance, always compare against the same quarter of the previous year."
* "Our fiscal year starts in October."

**Don't:**

* "Be helpful." (too vague)
* "Always be accurate." (redundant)
* "Consider all factors." (too broad)

### Domain examples

**E-commerce:**

```markdown theme={null}
<!-- agents/rules/customer-lifetime-value.md -->
---
type: always
---
Customer lifetime value equals average order value × purchase frequency × customer lifespan.
```

```markdown theme={null}
<!-- agents/rules/cart-abandonment.md -->
---
description: "Apply when the user asks about cart abandonment"
type: agent_requested
---
For cart abandonment analysis, segment by device type and traffic source.
```

**SaaS:**

```markdown theme={null}
<!-- agents/rules/mrr-growth.md -->
---
type: always
---
MRR growth rate excludes one-time charges and setup fees.
```

```markdown theme={null}
<!-- agents/rules/churn-segmentation.md -->
---
description: "Apply when the user asks about churn analysis"
type: agent_requested
---
When analyzing churn, distinguish between voluntary and involuntary churn.
```

## Resolving conflicts

When multiple rules could apply, follow these guidelines:

1. **Review existing rules** before adding new ones to avoid contradictions.
2. **Use specific triggers** in `agent_requested` rules so the agent knows when each rule applies.
3. **Prefer specificity over breadth** — narrowly scoped rules override broader defaults more cleanly.
4. **Test rule combinations** with sample queries before relying on them.

If two `always` rules directly contradict each other, the agent will surface the conflict in its response. Resolve such conflicts by editing the rules in your repository and redeploying.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.