diff --git a/CLAUDE.md b/CLAUDE.md
index 767e0c4..81270d8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -138,6 +138,22 @@ curl -X POST http://localhost:8000/api/sync/trigger
 docker compose up
 ```
 
+## Business Metrics
+
+Standardized metric definitions live in DuckDB (`metric_definitions` table). Import starter pack:
+
+```bash
+da metrics import docs/metrics/
+```
+
+### For AI agents analyzing data:
+Before computing any business metric, look up the canonical definition:
+1. `da metrics list` — find the relevant metric
+2. `da metrics show revenue/mrr` — read the SQL and business rules
+3. Use the SQL from the metric definition, adapt to the specific question
+
+Never invent metric calculations — always use the canonical definitions.
+
 ## Extensibility
 
 ### Data Sources (extract.duckdb contract)