Comparison · vs CLAUDE.md

ClariLayer vs a hand-written CLAUDE.md

Both put your data definitions where your agent can read them. The difference is whether anything ever checked them against your warehouse.

A CLAUDE.md is where data context goes to rot. The moment a definition has money behind it, asserted text is a liability: the billing rule changes, the table moves, and the file keeps saying the old thing — and your agent keeps repeating it, confidently. Writing your definitions down is still a genuinely good first move; it just cannot tell you when it is wrong.

A ClariLayer entry is the same definition, reconciled against the result your agent actually computed: provenance and status are shown, and a declared-vs-actual mismatch surfaces as a caveat instead of a clean-looking wrong number. ClariLayer never holds your warehouse credentials and never runs SQL server-side — it checks declared against actual and shows its work.

Reconciled, not asserted

A CLAUDE.md is asserted. A ClariLayer entry is reconciled.

Hand-typing your definitions into a notes file is a real, useful start — but nothing checked it against your warehouse. A ClariLayer entry is the same definition, reconciled against your real warehouse result: provenance and status are shown, and a declared-vs-actual mismatch surfaces as a caveat instead of a confident wrong answer.

Hand-written CLAUDE.md
CLAUDE.md
## Metrics
"Active customer" = a user who logged in
in the last 90 days (raw_users.last_login).
 
# TODO: double-check this is still right
asserted · nothing checked it

Just text. Nothing reconciled it against your warehouse, so when the definition drifts the agent keeps trusting the stale line — confidently.

ClariLayer entry
"Active customer"
"Active customer" → fct_customers,
status = 'active' AND mrr > 0
source
dbt + you → reconciled
last reconciled
2 days ago
status
asserted
caveat · declared ≠ actual

The declared definition counted logged-in users; reconciling against your warehouse showed the billing rule (mrr > 0) returns a different number. Flagged for you to resolve — not hidden behind a clean-looking total.

Reconciled against the result your agent computed locally. ClariLayer never holds your warehouse credentials and never runs SQL server-side — it checks declared against actual, and shows its work.

When each one is the right tool

Keep the file. Add reconciliation where it matters.

This is not a file you have to throw away. A CLAUDE.md and a ClariLayer context layer do different jobs — the question is which one a given piece of context actually needs.

A hand-written CLAUDE.md is great for

  • Day-zero notes — jotting down the handful of definitions and join paths you keep re-typing.
  • Stable conventions that rarely change: naming, where a model lives, a house style for SQL.
  • Context that has no warehouse result to check it against in the first place.

A ClariLayer entry earns its keep when

  • A definition has a real warehouse result behind it that can drift — revenue, active customers, retention.
  • You need to know a saved definition still matches the data, not just that you wrote it down once.
  • The context should compound across sessions and carry its provenance, status, and any caveats with it.

Caveat over confident-but-wrong

The honest unit of trust here is the caveat. A hand-written file has no way to raise one — it cannot know it has drifted. ClariLayer reconciles the saved definition against your real warehouse result and, on a mismatch, records a caveat; a clean pass leaves the entry asserted, the honest baseline. Today the product emits caveat or leaves an entry asserted — a stronger verified stamp remains gated and is not a live status.

Turn your notes into reconciled context.

Connect ClariLayer to Claude Code, Cursor, Codex, or claude.ai. Bootstrap brings in your existing CLAUDE.md and SQL, then reconcile keeps the definitions that matter honest against supported evidence.

Connect your AIRead the quickstart