Drift vs Consistency: Two Ways Your Codebase Lies to You

Editor’s note (March 2026): Since this post, Coherence has shipped v1.6 with a unified /coherence command and 11 sub-commands. The standalone /check-consistency and /check-drift commands described here are now /coherence check-drift and /coherence check-principles. /check-consistency has been retired — terminology and style enforcement now runs entirely through automatic hooks. See coherence.viewyonder.com for the current command reference.

Your codebase has two kinds of rot. They look similar. They’re completely different problems. And if you only check for one, the other will quietly eat your project alive.

We built two slash commands for Claude Code — /check-drift and /check-consistency — and people keep asking which one they need. The answer is both, but for different reasons.

The Quick Version

/check-drift asks: “Does the code match what the docs say?”

/check-consistency asks: “Is the content well-written and following our rules?”

Drift is about truth. Consistency is about quality. You can have perfectly consistent content that describes a system that no longer exists. You can have zero drift but content riddled with “View Yonder” and marketing fluff.

What /check-drift Actually Does

Drift detection starts with your SPEC documents — the source of truth files that describe how your system is supposed to work. Ours live in docs/ and cover two domains:

Content Standards (SPEC-CONTENT-STANDARDS.md) documents every frontmatter field, every valid theme tag, every heading hierarchy rule. The drift checker reads this spec, then walks through src/data/ comparing reality against the documentation.

Site Architecture (SPEC-SITE-ARCHITECTURE.md) documents URL structure, content collection schemas, design tokens, and component patterns. The drift checker compares this against src/pages/, src/content.config.ts, and src/styles/design-tokens.css.

The output is binary per item — aligned or drifted:

## SPEC: SPEC-SITE-ARCHITECTURE.md

### Aligned
- URL structure matches documented routes
- Design tokens match documented values

### Drifted
- [DRIFT] caseStudies schema: SPEC documents `image` field, not found in content.config.ts
  - File: src/content.config.ts
  - Recommendation: Add image field to caseStudies schema

That’s a real example. We documented an image field in the case studies spec before we’d added it to the schema. The drift checker caught it. The code and the docs disagreed, and one of them had to change.

You can scope it:

/check-drift              # Full check against all SPECs
/check-drift content      # Just content standards
/check-drift architecture # Just site architecture

When Drift Hurts

Drift is insidious because nobody notices it happening. You add a /blog/ section but forget to update the URL structure spec. You rename a CSS variable but the architecture doc still references the old one. Six months later, a new developer reads the spec, builds something based on it, and discovers reality diverged three PRs ago.

Every team that’s tried to maintain architecture decision records (ADRs) knows this pain. The decision gets recorded. The code evolves. The ADR becomes historical fiction.

Drift checking turns a static document into a living contract.

What /check-consistency Actually Does

Consistency checking is about editorial quality. It reads your actual content and evaluates it against four categories:

Terminology — Is it “Viewyonder” or “View Yonder”? Is “GenAI” capitalised correctly? Is “AI-powered” hyphenated when used as an adjective? The checker knows 15+ specific brand and technical terms and their correct forms.

Voice & Tone — Does the content sound like Viewyonder? We write like experienced colleagues, not sales teams. The checker flags words like “revolutionary”, “synergy”, “leverage”, and “unprecedented”. It catches AI hype patterns like “AI will replace” — because our voice frames AI as augmenting people, not replacing them.

Structure — Does the frontmatter have all required fields? Do articles use H2 for main sections and H3 for subsections? Do build log entries have dates and summaries? Every content type has documented structural requirements.

Cross-references — Do internal links use relative paths? Are theme tags from the established set (ai-in-work, organizational-change, technical, security, product-development)? Does anything link to a page that doesn’t exist?

The output is per-file, per-category:

## src/data/articles/building-ai-first-teams.md
- [PASS] Terminology: "AI-first" correctly hyphenated. No brand name issues.
- [PASS] Voice: Clean, practical tone. No buzzwords.
- [PASS] Structure: All required frontmatter fields present. Proper heading hierarchy.
- [PASS] Cross-references: Themes valid. No broken internal links.

You can scope it too:

/check-consistency                      # Everything in src/data/ and src/pages/
/check-consistency src/data/articles/   # Just articles
/check-consistency staged               # Just your staged git changes

That last one is the killer feature. Run it before you commit. Catch the problems before they ship.

When Inconsistency Hurts

A reader won’t notice that your architecture spec is out of date. But they’ll notice if your homepage says “GenAI” and your article says “gen ai”. They’ll notice if one service page is punchy and specific and another reads like it was written by a corporate communications department in 2019.

Inconsistency makes you look like multiple companies occupying the same website.

The Stack Underneath

Both commands work through the same Claude Code infrastructure:

1. SPEC documents define the source of truth
2. Agents (.claude/agents/) are review personas with specific expertise — drift-detector.md and consistency-reviewer.md
3. Skills (.claude/skills/) are the slash commands that invoke those agents
4. Hooks (.claude/hooks/) run automatically on every edit — terminology checking, style guarding, and change suggestions

The hooks are the unsung heroes. Three Node.js scripts fire every time Claude edits a file:

• terminology-check.cjs — 15 regex patterns for product names, AI terms, hyphenation
• style-guard.cjs — 13 patterns for marketing fluff, AI hype, structure violations
• change-suggest.cjs — 7 file-watching rules that nudge you to update related content

These run as PreToolUse hooks, which means they fire before the edit is applied. Claude sees the warning and self-corrects in real time. The user sees a brief “Checking terminology…” status message and the output just comes out right.

The slash commands are for the comprehensive sweep. The hooks are for the continuous correction. Belt and braces.

A Worked Example

Say you’re adding a new article about LLM security. You open Claude Code and ask it to write.

As Claude writes, the hooks fire silently. It starts typing “gen AI” — the terminology hook flags it, Claude corrects to “GenAI”. It reaches for “game-changing” — the style hook flags it, Claude rephrases. You never see the mistakes because they’re caught mid-generation.

Before committing, you run /check-consistency staged. It reviews just the new file. Reports pass/warn/fail across all four categories. Maybe it catches a theme tag that isn’t in the valid set, or an internal link that should use a relative path.

Before a release, you run /check-drift. It compares your SPECs against the entire codebase. Maybe you added a new content collection but forgot to document it in the architecture spec. Maybe a CSS variable name changed. The drift checker tells you exactly what’s misaligned and where.

Three touch points. Automatic, pre-commit, pre-release. Each catching different problems at different scales.

Which One Do You Need?

If you maintain architecture documentation or SPECs: you need drift checking. Documents that nobody verifies are documents that nobody trusts. Automated drift detection is the difference between living documentation and shelf-ware.

If you publish content through AI: you need consistency checking. LLMs write confidently and often wrongly — not factually, but stylistically. They’ll spell your product name three different ways in the same article and never flinch.

If you do both: you need both.

This system is now Coherence — shipped at v1.6 with a unified /coherence command and 11 sub-commands that generate and manage the full guardrails stack for any project. The principle is the same regardless of what you’re building: encode your standards once, enforce them on every edit.

Your code should match your docs. Your content should match your standards. Now there’s a command for each.