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.

Writing your definitions into a CLAUDE.md is the obvious first move, and a genuinely good one. You stop re-explaining which table is canonical and which join is the right one; your agent reads the file and carries that context into the task. For conventions that rarely change, that is often all you need.

The limit shows up the moment a definition has a live warehouse result behind it. A line that says “active customer = logged in within 90 days” is just asserted text — nothing reconciled it against the data, so when the billing rule changes or the table moves, the file keeps saying the old thing and your agent keeps trusting it, confidently. 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 is the documented trajectory, not a badge we apply present-tense.

Turn your notes into reconciled context.

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

Connect your AIRead the quickstart