CLAUDE.md Template: SQL Analytics Projects

Overview

A CLAUDE.md file placed in your SQL analytics project gives build-cli persistent context about the database platform, schema structure, key tables, naming conventions, and known data quality issues. This article provides a ready-to-use CLAUDE.md template for SQL analytics projects running on Snowflake, Redshift, Databricks, or PostgreSQL.

Copy the template below, fill in the placeholders, and commit it to your project root as CLAUDE.md.

Background

SQL analytics projects often work across multiple schemas and tables with non-obvious grain and filter requirements (e.g., a specific partition column that must always be filtered to avoid full scans). Without persistent context, build-cli may generate queries that use SELECT *, miss the partition filter, or use the wrong date range convention. A well-filled CLAUDE.md ensures the AI generates SQL that fits your project’s conventions and avoids known performance pitfalls.

The template is intentionally minimal — focus on the conventions and known issues that matter most for your project, rather than documenting every table.

Main Content

Copy this template into CLAUDE.md at your project root (or in the relevant directory where you run build-cli) and replace all [PLACEHOLDER] values:

## Project

**[PROJECT NAME]** — [One sentence: what this project analyses or reports on.]

## Tech stack

- Database: [Snowflake / Redshift / Databricks / PostgreSQL / ...]
- SQL dialect: [standard SQL / Snowflake SQL / SparkSQL / T-SQL]
- Connected tools: [e.g., Tableau, Looker, Power BI, direct query]

## Schema overview

Key schemas/databases used in this project:
- `[SCHEMA_NAME]` — [what it contains]
- `[SCHEMA_NAME]` — [what it contains]

Key tables:
- `[TABLE]` — grain: [one row per what], key columns: [list]
- `[TABLE]` — grain: [one row per what], key columns: [list]

## Conventions

- Naming: snake_case for all aliases and CTEs
- Date filtering: always filter on the partition column `[COLUMN_NAME]` to avoid full scans
- No `SELECT *` in shared or production queries
- Document business logic inline with comments on non-obvious transformations
- NULL handling: explicit COALESCE or IS NOT NULL on all join keys

## Known data quality issues

- [Any known issues in the source data that affect analysis — e.g., "orders before 2022-01-01 have no country_code"]

Summary

Place CLAUDE.md in the project or working directory where you run build-cli sessions.
The “Conventions” section is critical: it prevents the AI from generating SELECT * queries, missing the partition filter, or producing dialect-incompatible SQL.
The “Known data quality issues” section is equally important: without it, the AI may propose analyses that are invalidated by known data problems.
The “Schema overview” section gives the AI enough table grain and key column knowledge to generate accurate JOIN conditions.
Commit CLAUDE.md to version control so all team members work with consistent context.
See the other CLAUDE.md example templates in this hub for data governance, dbt, and ETL pipeline projects.