AI-Ready Workspace
The AI context files ship with Premium installations (v2.2.9+).
Your GA4Dataform workspace is built to be understood by AI agents, not just humans. Every installation ships a set of context files at the repository root, and the tables themselves are self-describing: each output table's BigQuery description states its grain ("1 row per ..."), every column carries a description, and the SQL transformations are commented CTE by CTE.
The practical effect: you can point an AI assistant - Gemini in BigQuery, Claude, Cursor, or any coding agent - at your Dataform workspace or your BigQuery datasets, and it can answer questions about your data, write correct queries, and extend the project safely without a long explanation from you.
The context files​
| File | What it contains | On update |
|---|---|---|
AGENTS.md | The agent guide: what the project is, which folders are safe to edit, how configuration works, how the data updates, querying rules and known pitfalls | Overwritten |
CLAUDE.md | Identical copy of AGENTS.md - the filename Claude-based agents load automatically | Overwritten |
GEMINI.md | Identical copy of AGENTS.md - the filename Gemini-based agents load automatically | Overwritten |
LINEAGE.md | Every table: its grain, type and partitioning, upstream sources, downstream consumers, and purpose - the full data flow in plain text | Overwritten |
MY-COMPANY.md | A template for your business context: vertical, conversion events, revenue definition, channel conventions, KPIs, known data quirks | Preserved once you edit it |
AGENTS.md, CLAUDE.md and GEMINI.md carry the same content under the three filenames different agent tools discover automatically - whichever assistant you use, it finds its native context file.
Fill in MY-COMPANY.md​
MY-COMPANY.md is the one file that needs you. It ships as a template of placeholders - company vertical, GA4 setup, what counts as a conversion, how revenue is defined, campaign naming conventions, known tracking gaps. Agents are instructed to read it before answering business questions, so ten minutes of filling it in turns generic answers ("your purchase event...") into specific ones ("your generate_lead conversions from the DE market...").
It is created on install (and on update if missing), but never overwritten once it exists - your edits survive every package update, like everything in definitions/custom/ and includes/custom/.
What agents get told​
The agent guide encodes the rules that keep AI help safe in a managed workspace:
- Boundaries -
definitions/core/andincludes/core/are replaced on every update; custom work belongs in thecustom/folders. Agents are told to never edit core and how to extend properly instead. - Data semantics - tables are incremental, the most recent
DATA_IS_FINAL_DAYSdays are provisional (is_final), and identity stitching can revise past rows. Agents learn why numbers move before a date is final. - Query discipline - always filter the partition column, check the grain before joining, mind bytes scanned.
- Confirmation - for ambiguous requests or anything that changes configuration or data, agents are instructed to check with you first.
Using it​
Some starting points once your workspace is installed:
- Gemini in BigQuery / Dataform: the context is picked up from
GEMINI.mdin the workspace; table and column descriptions are also visible directly in BigQuery metadata, so grain and column meaning travel with the tables themselves. - Claude Code, Cursor or another coding agent: open the workspace repository (connect it to GitHub to work locally) and just ask - "which table should I use for revenue by channel?", "add a custom table with daily conversion rates per landing page". The agent reads
AGENTS.md/LINEAGE.mdon its own. - Keep
MY-COMPANY.mdcurrent - it is the highest-leverage file: business definitions change more often than the data model does.
LINEAGE.md is also a great human reference: it answers "where does this table come from and what feeds on it" faster than clicking through the Dataform DAG.