Data Dictionary Local Documentation Claude

A local data dictionary is the cheapest way to make Claude Code dramatically better at data work. Drop a CLAUDE.md file with your table and column definitions in the repo root, and every session starts with accurate schema context instead of hallucinated guesses. This one file can cut bug rates by more than half.

This guide explains why the local dictionary matters, what it should contain, how to keep it current, and how Data Workers generates one automatically from the warehouse catalog.

Why Local Context Wins

Claude Code reads the nearest CLAUDE.md file at session start and keeps its contents in context for the entire session. This is the cheapest, most reliable way to ground the model in your specific schema. No retrieval-augmented generation, no vector store, no MCP round trip — just a file the model already sees.

What to Put in the Dictionary

• •Table names and purposes — what each table represents, in business terms
• •Column names and types — including units (cents vs dollars, UTC vs local)
• •Primary keys and joins — how tables relate to each other
• •Business rules — invariants the data always satisfies
• •Known quirks — orders.user_id is nullable for guest checkouts
• •Deprecated tables — do not use, kept for historical queries only
• •Sensitive fields — PII columns the agent must not display

How Much Detail

Aim for 2,000 to 8,000 words total. Enough to cover the top 50 tables and their relationships; not so much that context window becomes a problem. Skip columns that are self-explanatory (created_at), focus on the ones with units, conventions, or gotchas. Quality beats quantity.

Auto-Generation From Catalog

Data Workers generates a starter CLAUDE.md from your catalog automatically. Tables, columns, types, descriptions, and lineage all come from the catalog agent. You then edit the file to add business context that the catalog does not capture — tribal knowledge, naming conventions, stakeholder preferences. See autonomous data engineering.

Keeping It Current

A stale dictionary is worse than no dictionary — the agent trusts it and produces wrong output. Run a nightly job that diffs the current catalog against the dictionary and flags drift. Any schema change that is not reflected in CLAUDE.md triggers a pull request with the suggested update. Humans review the update, merge it, and the dictionary stays fresh.

Hierarchical Dictionaries

Claude Code supports nested CLAUDE.md files. A root-level file covers warehouse-wide conventions, and per-folder files cover schema-specific details. This lets you keep each file focused without duplicating content across sub-projects. Data Workers uses this pattern for multi-schema warehouses.

Measuring the Impact

Before and after: run the same 50 agent tasks against your warehouse, once with a dictionary and once without. Measure fabrication rate (columns that do not exist), SQL error rate, and human corrections per task. Teams that add a good dictionary see fabrication drop by 60 to 80 percent and SQL errors drop by 40 to 60 percent. See AI for data infrastructure for the broader context engineering story.

A local dictionary is the cheapest high-leverage move you can make for Claude Code on data work. Generate it from the catalog, edit in business context, keep it fresh, and the agent gets dramatically more accurate overnight. To see auto-generation running, book a demo.

One counterintuitive finding: shorter dictionaries often outperform longer ones. A 3,000-word dictionary focused on the 30 most-used tables gives the agent the right context without burying it in details. A 20,000-word dictionary that covers every table is harder to navigate, burns more context window, and sometimes confuses the agent with irrelevant information. Quality and selection matter more than exhaustiveness. Document the tables that matter most; let the catalog cover the rest.

The dictionary is also the best place to capture tribal knowledge that would otherwise live only in Slack. When an engineer explains a quirk ('orders.status = 5 means canceled but refunded; status = 6 means canceled and not refunded') in a Slack message, that explanation should land in CLAUDE.md within a week. Teams that treat the dictionary as the authoritative home for tribal knowledge build up a living document that survives team turnover and onboards new engineers faster. It is the one piece of documentation that actually gets read, because the AI reads it too.

A dictionary generation workflow works best when it is automated but human-reviewed. Data Workers' catalog agent produces a draft CLAUDE.md from the catalog on demand and opens a pull request for human review. The human adds business context, approves, and merges. This keeps the dictionary current without requiring humans to start from scratch, and the PR workflow captures tribal knowledge that would otherwise never land in a documented place.

One final tip: include a 'last updated' timestamp and an 'owner' field at the top of the dictionary. When someone notices stale information, they know who to ask for an update. Without an owner, stale information festers because nobody feels responsible. Data Workers' dictionary template includes both fields by default. This small convention dramatically improves the long-term maintenance of the dictionary as a living document.

CLAUDE.md in the repo root. Generate from catalog, edit in tribal knowledge, keep it fresh. Fabrication rate drops by more than half.