A CLAUDE.md template for data teams
October 2026 · copy-paste template
If your team uses Claude Code, Cursor or Codex to answer questions from your warehouse, the single highest-leverage thing you can do is write down the business rules the agent can't infer from the schema. Here's the template we recommend. It works as CLAUDE.md, AGENTS.md or a Cursor rule file.
Fill in the brackets. Keep it short: agents follow 40 precise lines better than 400 vague ones.
# Data rules for AI agents
## Before writing SQL
- Restate the question as: metric + grain + time window + filters. If any of these is ambiguous, ASK before querying.
- Use the definitions below. They override anything you infer from column names.
- Say which definition you used in your answer (e.g. "Net revenue (excl. refunds, internal accounts)").
## Warehouse
- Engine: [Postgres 16 / BigQuery / Snowflake / DuckDB]
- Use schema [analytics] (modelled, clean). Do NOT use [raw_*] or [staging_*] unless asked.
- Timestamps are stored in [UTC]. Report dates in [America/New_York].
- Money is stored in [cents] in [orders.amount_cents]. Divide by 100. Currency: [USD only / convert with fx_rates].
## Always-on filters
- Exclude test data: [accounts.is_test = false]
- Exclude internal users: [users.email not like '%@ourco.com']
- Exclude soft-deleted rows: [deleted_at is null]
## Metrics
- **Net revenue**: [sum(amount_cents)/100 where status = 'paid' and refunded_at is null], excl. internal accounts.
- **MRR**: [sum of active subscription monthly price at month end; annual / 12; excl. trials].
- **Active user**: [user with >= 2 sessions in trailing 28 days].
- **Customer**: [account with at least one paid invoice]. Trials are NOT customers.
- **Churn**: [customers who cancelled in month / customers at start of month]. Downgrades are not churn.
## Calendar
- Fiscal year starts [Feb 1]. "This year" in finance questions = fiscal year.
- Weeks start on [Monday].
## Known traps
- [events_raw] has bot traffic and duplicates; use [events_clean].
- Joining [orders] to [order_items] before summing order totals double-counts. Aggregate first.
- [users.created_at] before [2023-04] is unreliable (migration).
## When I correct you
- Propose an edit to this file with the corrected rule, in the same style, so the next person gets it right.
Why each section is there
- "Restate the question" catches most ambiguity before it becomes a wrong number. Agents are good at this when told to.
- Always-on filters are the #1 source of silently wrong totals: test accounts, employees, deleted rows.
- Known traps is where your team's tribal knowledge goes. Every analyst has three of these in their head.
- "When I correct you" turns corrections into durable rules instead of one-off chat fixes.
Where this breaks down
A file in one repo works for one person. It gets harder when:
- several people (and several agents) ask questions, and corrections land in different chats and different laptops;
- the file grows past what fits comfortably in context, and you want only the relevant rules served per question;
- you want to know whether the agent is actually getting more accurate over time.
That's what Contextloop does: the same definitions, served over MCP to every agent on the team, with corrections captured into a review queue and a weekly accuracy chart. It imports dbt YAML, exports back to Markdown / MetricFlow / Cube, and never needs warehouse access. Free to start, and you can try the demo workspace with one command:
claude mcp add --transport http contextloop-demo "https://getcontextloop.com/mcp?key=demo"