Skip to main content

​
RULES.md

The RULES.md file is created during project initialization and serves as the primary guide for your agent’s behavior. Since RULES.md is included with every message to the agent, keeping it concise helps optimize performance.

​
What Belongs in RULES.md

  • Tone of voice — How the agent should communicate
  • User interaction patterns — How to clarify questions and structure responses
  • Code style — SQL formatting standards and conventions
  • Repository structure — How your context is organized
  • Essential business policies — Rules that apply universally
  • Orchestration instructions — References to specialized context files

​
Specialized Context Files

Rather than cramming everything into one file, organize detailed domain knowledge into modular files such as:
  • docs/marketing.md — Campaign definitions, customer lifecycle metrics
  • docs/finance.md — Financial metrics, revenue calculations
  • docs/product.md — Product-specific context and definitions
  • semantics/business_rules.yml — structured governance guidance
  • semantics/semantic_model.yml — structured metric definitions
This approach prevents token bloat by loading detailed context only when relevant to user queries.

​
Recommended Content Areas

Your rules files should address:
  • Business definitions and glossaries — Canonical definitions for key terms
  • Metric calculations — How to compute metrics, with SQL examples
  • Data quality considerations — Known issues, timezone handling, caveats
  • Privacy and security guidelines — PII handling rules
  • Domain-specific rules and constraints — Business logic

​
Response Framework

For business analysis, structure responses as:
  1. Lead with the key finding
  2. Provide supporting data
  3. Add relevant context and comparisons
  4. Validate against known benchmarks
  5. Note any limitations or data quality issues

​
Clarifying Questions

The agent should ask clarifying questions about:
  • Time periods
  • Geographical scope
  • Customer segments
  • Metric definitions
  • Desired granularity

​
SQL Best Practices

  • Use explicit SQL JOIN syntax with meaningful aliases
  • Apply LIMIT clauses to queries
  • Prefer CTEs over nested subqueries
  • Default to 30-day windows unless specified
  • Flag queries accessing personally identifiable information
  • Never display full email addresses or phone numbers

​
Trusted Analytics files

If you enable Trusted Analytics V1/V2, add and maintain:
  • datasets/<bundle_id>/dataset.yaml (scope and join boundaries)
  • policies/policy.yml (hard enforcement rules)
  • contracts/runs/*.json (runtime audit artifacts)

​
Best Practices

Maintain one canonical definition across all your rules files to ensure consistency and reduce confusion. Organizing rules modularly keeps token costs manageable while preserving agent focus on appropriate tasks.