Skip to main content
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. This is where you define agent behavior rules.
Since RULES.md is included with every message to the agent, keeping it concise helps optimize performance. Use orchestration to point the agent to specialized files for detailed context when needed.
What to Include in RULES.md Since RULES.md is sent with every message, it should only contain:
  • Tone of voice — How the agent should communicate
  • User interaction patterns — How to clarify questions and structure responses
  • Code style — SQL formatting and query standards
  • Context repository structure — Where to find specialized information
  • Key business rules — Critical policies that apply universally
  • Orchestration — Instructions to read specific files for detailed topics
Example: RULES.md Here’s a well-structured RULES.md file: 
# 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.
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.

Context Engineering Principles

Learn how to organize rules effectively using MECE principles and modular structure
 Example: Specialized File (marketing.md) Here’s an example of a specialized context file: 
# 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'