> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getnao.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Rules

> Define how your agent should behave and respond

Rules guide your agent's behavior, ensuring it responds appropriately and follows your organization's standards.

## RULES.md File

When you initialize a nao project with `nao init`, a `RULES.md` file is automatically created in your project root. It is loaded with **every** message to the agent, so keep it lean.

`RULES.md` has two jobs:

1. **Orchestrator**: point the agent to the right context fast - which metric maps to which definition, which topic maps to which file, which question type maps to which table or skill.
2. **Broad rules**: how to query and how to answer (tone, SQL conventions, data access).

Everything else - per-table schemas, full metric semantics, domain-specific rules - belongs in a referenced file. **`RULES.md` should never duplicate context that already lives elsewhere in your repo.** It points to it.

<Tip>
  Since `RULES.md` is included with every message, keeping it concise optimizes performance and cost. When `nao sync` has already populated per-table docs, a semantic layer, or `docs/`, point to those instead of restating them.
</Tip>

## Recommended structure

`nao init` scaffolds `RULES.md` with the sections below. Keep the ones that fit your project and drop any already covered by synced context.

| Section                               | Purpose                                                                                                                                                            |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `## Business overview`                | What the company does and how it makes money.                                                                                                                      |
| `## Data architecture`                | Warehouse, data stack, layers, and data sources.                                                                                                                   |
| `## Context map`                      | The index of where context lives: per-table files, key repo files, `docs/`, and the semantic layer. The orchestrator's routing table.                              |
| `## Core data models`                 | `Most Used Tables` (one-line pointers, always) plus `Tables detail` (only when no richer table docs exist elsewhere).                                              |
| `## Key Metrics Reference`            | Canonical metric definitions, **only if** no semantic layer or metric docs already define them. Otherwise a one-line pointer to where they live.                   |
| `## Date filtering`                   | A few example SQL formulas (last X weeks, last X days, current month) the agent extrapolates from.                                                                 |
| `## Analysis Process`                 | The steps the agent follows: resolve the metric definition, read relevant docs, select tables, check column values before filtering, query, validate, add context. |
| `## Chart & Visualization Guidelines` | How the agent's charts should look, so the whole project stays on-brand: the brand color palette for chart series and the semantic colors for good vs bad values.  |

### Point to context, don't copy it

The `## Context map` section is what keeps `RULES.md` lean. Instead of restating column lists or metric formulas, route the agent to where they already live:

```markdown theme={null}
## Context map

**Per-table context** - each `databases/.../table=<name>/` folder contains:
- `columns.md` - column names, types, descriptions
- `profiling.md` - distinct counts, min/max, and `top_values`. Read before filtering on any column value.

**Repos:**
- `repos/dbt/` - dbt project. Column docs: `models/silver.yml`. Domain decisions: `models/silver/*_ANALYTICS_DECISIONS.md`. Semantic layer (metrics): `models/silver_semantic_layer.yml`.

**Docs:**
- `docs/crm.md` - CRM funnel statuses and opportunity stages. Read before any sales question.

**Semantic layer:** metrics are defined in `repos/dbt/models/silver_semantic_layer.yml`. Query through it, don't recompute from raw tables.
```

### Conditional sections

Two sections are conditional. Include them only when that context does not already exist elsewhere:

* **`Tables detail`**: skip it when per-table docs (`query_history.md`, `ai_summary.md`) or dbt `schema.yml` column docs already describe your tables - the `Most Used Tables` pointers and the Context map route there already. Reserve it for cross-table pitfalls documented nowhere else.
* **`Key Metrics Reference`**: skip it when a semantic layer or metric docs define your metrics. Replace it with a one-line pointer so each metric keeps a single canonical definition.

<Tip>
  Each metric should have exactly one canonical definition across all your context. Duplicating it in `RULES.md` and a semantic layer is the most common cause of inconsistent answers.
</Tip>

### Chart and visualization guidelines

`RULES.md` can also tell the agent how charts should look, so every visualization stays on-brand and consistent. Add a `## Chart & Visualization Guidelines` section with two parts:

* **Brand color palette**: the colors to use for chart series. Single-series charts use the primary brand color; multi-series charts spread across the palette, then use tints and shades of those colors beyond about six series rather than introducing off-brand hues. Tell the agent to never fall back to the charting library's default palette.
* **Semantic colors**: fixed colors for when a chart encodes good vs bad values (deltas, variances, positive or negative KPIs). Keep these separate from the brand palette, which stays reserved for purely categorical series.

Fill the palette from your company's design system or brand guidelines. `nao init` scaffolds this section with placeholder colors for you to replace.

```markdown theme={null}
## Chart & Visualization Guidelines

### Color palette (brand)
Always use these colors for every chart. Never use the charting library's defaults.

| Color | Use |
| --- | --- |
| `#2B2BFF` | Primary - default single-series color |
| `#12B981` | Second series |
| `#F59E0B` | Third series |

- Single-series charts: use the primary brand color.
- Multi-series charts: assign colors across the palette; beyond ~6 series, use tints and shades rather than off-brand hues.

### Semantic colors (good vs bad)
When a chart encodes good or bad values, use fixed semantic colors, not the brand palette:
- Good: `#12B981`
- Bad: `#EF4444`
```

## Broad rules example

Beyond routing, `RULES.md` holds the broad rules for how the agent queries and answers. Here's an example of that portion:

```markdown theme={null}
# Agent Rules

## Tone of Voice
- Be professional, concise, and friendly
- Always explain your reasoning
- If you make assumptions, state them clearly
- Suggest follow-up questions when relevant

## Interacting with Business Users

### Clarify Before Analyzing
Before running analysis, ask clarifying questions if any of these are unclear:

- **Time scope**: "What time period?" (last 7 days, MTD, YTD, specific dates)
- **Geographical scope**: "Which regions/countries?" (all, specific markets)
- **Segmentation**: "Which customer segments?" (all, B2B, B2C, enterprise)
- **Metric definition**: "Which definition of [metric]?" (if multiple exist)
- **Granularity**: "Daily, weekly, or monthly view?"

### Response Structure
For every analysis, follow this structure:

1. **Answer first**: State the key finding upfront
2. **Supporting data**: Show the numbers/visualization
3. **Context**: Add relevant comparisons (vs last period, vs target)
4. **Sanity checks**: Validate against known benchmarks
5. **Caveats**: Mention any data quality issues or limitations

### Sanity Check Guidelines
Before presenting results, verify:

- Numbers align with order-of-magnitude expectations
- Totals match when aggregated different ways
- Check against reference tables (e.g., monthly_kpi_summary)
- Flag if results differ significantly from historical trends

### Follow-Up Suggestions
After answering, suggest relevant next questions:

- Drill-downs (e.g., "Want to see this by region?")
- Related metrics (e.g., "Should we look at retention too?")
- Trend analysis (e.g., "Want to see how this changed over time?")

## SQL Code Style
- Use explicit JOIN syntax
- Add meaningful table aliases (e.g., u for users, o for orders)
- Format SQL for readability (indentation, line breaks)
- Always use LIMIT clauses for queries
- Prefer CTEs over nested subqueries

## Data Access
- Only query production tables (exclude *_test, *_staging)
- Default to last 30 days of data unless specified
- Maximum 10,000 rows per query

## Privacy & Security
- Never display full email addresses or phone numbers
- Flag queries accessing PII
- Aggregate personal data when possible

## Orchestration - Domain-Specific Context

For detailed information on specific topics, read the appropriate file:

- **Marketing questions**: Read `agent/semantics/marketing.md`
- **Finance questions**: Read `agent/semantics/finance.md`
- **Product questions**: Read `agent/semantics/product.md`

These files contain:
- Detailed business definitions
- Metric calculations
- Data quality considerations
- Domain-specific rules
```

## Sub Rules Files

For detailed, domain-specific information, create additional `.md` files in your context. The agent will read these files only when needed.

**File Structure Example**

```
context/
├── RULES.md                    # Core rules (always sent)
└── agent/
    └── semantics/
        ├── marketing.md        # Marketing-specific context
        ├── finance.md          # Finance-specific context
        └── product.md          # Product-specific context
```

You can use sub-rules files for this kind of context:

* **Business Context**: Context on your company and products.
* **Business Glossary**: Glossary on your business key concepts and terms.
* **Domain-Specific Context**: Specific knowledge on a domain (Business definitions, key metrics, key tables)
* **Data Quality Information**: Context on specific data issues or specificity to add explainability to the agent.
* **Events Information**: Context on specific events that happened and can help explain data.

<Tip>
  Organize your rules modularly to keep token costs low and maintain agent focus. Each metric should have only one canonical definition across all your rules files.
</Tip>

<Card title="Context Engineering Principles" icon="lightbulb" href="/nao-agent/context-engineering/principles">
  Learn how to organize rules effectively using MECE principles and modular structure
</Card>

**Example: Specialized File (marketing.md)**

Here's an example of a specialized context file:

````markdown theme={null}
# Marketing Context

## Business Definitions

### Customer Lifecycle
- **Lead**: Contact with valid email, no account created
- **Prospect**: Account created, no purchase
- **Customer**: At least one purchase completed
- **Active Customer**: Purchase within last 90 days
- **Churned Customer**: No activity for 180+ days AND no active subscription

### Campaign Types
- **Acquisition**: Targeting new leads/prospects
- **Retention**: Targeting existing customers
- **Winback**: Targeting churned customers
- **Upsell**: Targeting customers with expansion opportunities

## SQL Metrics Definitions

### Customer Acquisition Cost (CAC)
```sql
-- Definition
SELECT 
  SUM(marketing_spend) / COUNT(DISTINCT customer_id) AS cac
FROM campaigns c
LEFT JOIN customers cu ON c.campaign_id = cu.acquisition_campaign_id
WHERE c.campaign_type = 'acquisition'
  AND cu.created_at BETWEEN c.start_date AND c.end_date + INTERVAL '30 days'
````