Comparison · vs CLAUDE.md
ClariLayer vs a hand-written CLAUDE.md
A CLAUDE.md keeps project-local instructions close to the code. ClariLayer carries selected durable work across projects and sessions, with source, applicability, correction and scoped forget. In Analytics, the difference can also be whether a definition was checked them against your warehouse.
A CLAUDE.md is a practical home for stable project instructions. It becomes less useful when a decision needs to apply across projects, retain its source, or be corrected without rewriting a file in every checkout. In Analytics, 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.
Just text. Nothing reconciled it against your warehouse, so when the definition drifts the agent keeps trusting the stale line — confidently.
- source
- dbt + you → reconciled
- last reconciled
- 2 days ago
- status
- asserted
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.
- A confirmed fact, preference, decision, rule or lesson should cross projects and sessions with source and applicability attached.
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.
Keep the file. Add continuity where the work crosses sessions.
Connect a compatible client, select the authorized space and save one confirmed rule. Import selected supported history only after reviewing the exact proposal; use reconcile separately for Analytics evidence.