Rule Drift: When Rules and Reality Diverge
Rule drift is the gradual divergence between what the AI rules describe and what the codebase actually follows. The rules say: 'Use Prisma for database access.' The codebase: migrated to Drizzle 3 months ago but nobody updated the rules. The AI: generates Prisma code (following the stale rule) in a Drizzle codebase. The drift: the rules describe one reality while the codebase lives another. The AI: follows the rules (which are wrong) instead of the codebase (which is right).
How drift happens: team conventions evolve through practice (the team adopts async/await but the rules still describe .then() chains), technology migrations occur without rule updates (the framework upgrade changes patterns but the rules reference the old version), rules are added but never maintained (the initial rules were accurate — 6 months later, half are stale), and manual edits to CLAUDE.md are lost (a developer fixes the rules locally but does not commit the change). Drift: accumulates silently. Nobody notices until the AI generates obviously wrong code.
The drift timeline: day 1 (rules written — 100% accurate). Month 1 (rules 95% accurate — minor patterns have shifted). Month 3 (rules 85% accurate — a library was replaced, naming convention evolved). Month 6 (rules 70% accurate — a framework migration changed patterns significantly). Month 12 (rules 50% accurate — half the rules describe patterns the codebase no longer follows). Without maintenance: rules become a liability — they guide the AI toward wrong patterns instead of correct ones. AI rule: 'Rules decay at roughly 5-10% per quarter without maintenance. The quarterly review: the maintenance cycle that prevents drift from accumulating.'
Why Rule Drift Matters
Impact 1 — Wrong AI output: the most visible impact. The AI generates code following stale rules. The code: uses deprecated libraries, old patterns, or incorrect conventions. The developer: must manually correct every AI-generated file. The productivity gain from AI rules: reversed (the rules make the AI worse, not better). Stale rules: actively harmful — the AI would generate better code with no rules than with wrong rules.
Impact 2 — Eroded developer trust: developers encounter AI-generated code that does not match the codebase. They think: 'The AI is broken' or 'The rules are useless.' They: start ignoring the rules, overriding every suggestion. Adoption: drops. The rules program: loses credibility. Rebuilding trust: harder than maintaining it. One bad experience from stale rules: can set back adoption by months.
Impact 3 — Onboarding confusion: a new developer reads the rules (expecting an accurate description of the codebase). The rules: describe patterns that do not match what they see in the code. The new developer: confused about which source of truth to follow (the rules or the code?). Without guidance: they may follow the stale rules (wrong) because the rules feel authoritative. AI rule: 'Stale rules are worse than no rules. No rules: the AI generates generic code (OK). Stale rules: the AI generates specifically wrong code (harmful). Drift prevention: more important than rule authoring.'
No rules: the AI generates generic code based on training data. Mostly correct, not project-specific, but not wrong. Stale rules: the AI generates code following outdated patterns. Uses a deprecated library. Follows the old error handling convention. References a file structure that was reorganized. The output: specifically wrong for the current codebase. The developer: spends more time correcting than they would without any rules. Stale rules: make the AI worse, not better.
How to Detect Rule Drift
Detection method 1 — Quarterly audit (manual): during the quarterly rule review, read each rule and ask: does this still match the codebase? Search for the referenced patterns, libraries, and conventions. If the search returns no results: the rule is stale. The quarterly audit: catches drift that accumulated over 3 months. Time: 1-2 hours per audit. The most thorough detection method.
Detection method 2 — CI freshness checks (automated): a script that checks rule file version against the expected version (from the central rules repo or RuleSync). If the version is outdated: the CI flags it. This: catches drift from unapplied rule updates (the central rules were updated but the project did not pull the update). Does not catch: drift from codebase changes that were not reflected in rule updates.
Detection method 3 — AI-assisted detection (semi-automated): prompt the AI: 'Read our CLAUDE.md and compare it against the actual code in this repository. Identify rules that do not match the current codebase patterns.' The AI: analyzes both the rules and the code, flagging mismatches. This: catches drift from both directions (rules that do not match the code AND code that does not match the rules). The most comprehensive detection method — but requires the AI to read both the rules and the codebase. AI rule: 'Three detection methods: quarterly audit (most thorough), CI checks (most automated), and AI-assisted (most comprehensive). Use all three for complete drift detection.'
The PR: migrates the database from Prisma to Drizzle. The same PR (or the next one): updates the CLAUDE.md from 'Use Prisma for database access' to 'Use Drizzle for database access.' The rule update: part of the migration's definition of done. Not 'we will update the rules later.' Later: never comes. The migration PR is merged. The developer moves on. The rules: still say Prisma. Drift: begins immediately. Update rules in the same PR: zero drift.
How to Prevent Rule Drift
Prevention 1 — Quarterly rule reviews: the standing maintenance cycle. Every quarter: review all rules for staleness. Update stale rules. Add missing rules. Remove obsolete rules. The quarterly review: the single most effective drift prevention mechanism. Without it: drift accumulates silently. With it: drift is caught and corrected every 3 months. Maximum drift: 3 months (the interval between reviews).
Prevention 2 — Rule updates as part of technology changes: when the team adopts a new library, framework, or pattern: update the rules in the same PR (or the same sprint). The rule update: part of the definition of done for the technology change. Without this: the technology changes but the rules do not — drift begins immediately. AI rule: 'Definition of done for technology changes: the code is updated AND the rules are updated. Both: in the same PR or the same sprint. Never: change the code and plan to update the rules later (later never comes).'
Prevention 3 — Automated sync and version tracking: RuleSync, CI freshness checks, and automated sync pipelines: keep rules up to date with the central rule source. These: prevent drift from missed updates (the central rules changed but the project did not sync). For drift from codebase changes: the quarterly audit and AI-assisted detection complement the automated tools. AI rule: 'Automated sync prevents: missed-update drift. Quarterly review prevents: codebase-evolution drift. Both together: comprehensive drift prevention.'
Prompt: 'Read our CLAUDE.md and compare against the code in src/. Identify rules that do not match the current patterns.' The AI: 'Rule 3 says use Prisma. The code uses Drizzle. Rule 7 says use Pages Router getServerSideProps. The code uses App Router Server Components. Rule 12 says tests use Jest. The code uses Vitest.' Three drift points: identified in 30 seconds. Manual detection of the same three points: 30+ minutes of reading rules and searching the codebase. The AI: the fastest drift detector because it can read both the rules and the code simultaneously.
Rule Drift Quick Reference
Quick reference for understanding and preventing rule drift.
- What: gradual divergence between AI rules and actual codebase practices
- Timeline: 100% accurate (day 1) → ~70% (month 6) → ~50% (month 12) without maintenance
- Impact: wrong AI output, eroded developer trust, onboarding confusion
- Stale rules: actively harmful. Worse than no rules (no rules = generic. Stale = specifically wrong)
- Detection: quarterly audit (manual), CI version checks (automated), AI comparison (comprehensive)
- Prevention 1: quarterly rule reviews. Maximum drift = 3 months
- Prevention 2: update rules alongside technology changes. Same PR or same sprint
- Prevention 3: automated sync for update drift. Quarterly audit for evolution drift