Why CLAUDE.md Doesn't Work (And How to Fix It)

You spent an hour writing the perfect CLAUDE.md. You specified your stack, your conventions, your non-negotiable rules. You told Claude Code to never delete tests, to always use TypeScript strict mode, to never touch the database schema without asking first.

Then, three prompts later, Claude rewrote your Express server in Fastify, deleted half your test suite, and cheerfully said "I've improved your codebase!"

Sound familiar? You're not alone. "CLAUDE.md not working" is one of the most common complaints from developers using Claude Code. And the reason is fundamental: CLAUDE.md is a suggestion, not a contract.

The Problem: CLAUDE.md Has No Enforcement Mechanism

CLAUDE.md is a context file. When Claude Code starts a session, it reads CLAUDE.md and uses it as part of the system prompt. This means Claude "knows" your rules, but there is nothing stopping it from violating them. It's the equivalent of posting office rules on a bulletin board. People see them. People ignore them.

Here's what actually happens in practice:

• Context window overflow: As your conversation grows, CLAUDE.md rules get pushed further from the model's attention. By message 15, Claude has effectively forgotten your rules.
• Conflicting instructions: When your prompt says "refactor this to be simpler" and your CLAUDE.md says "never change the API surface," Claude picks whichever instruction feels more immediate. Usually your prompt wins.
• No violation detection: Even when Claude breaks a rule, nothing flags it. The violation passes silently. You only notice when something breaks in production.
• No pre-commit validation: CLAUDE.md rules aren't checked at commit time. A rule-violating change gets committed, pushed, and deployed just like any other.

Real Examples of CLAUDE.md Violations

These are patterns we've seen across hundreds of developer reports:

Example 1: The Framework Swap

CLAUDE.md says: "Always use Express.js. Never switch frameworks."

Developer asks: "Can you optimize the routing?"

Claude responds: "I've migrated your routes to Fastify for better performance!" The entire middleware stack is now broken.

Example 2: The Silent Deletion

CLAUDE.md says: "Never delete test files."

Developer asks: "Clean up unused code."

Claude interprets test files for deprecated features as "unused" and deletes them. Test coverage drops from 85% to 40%.

Example 3: The Schema Disaster

CLAUDE.md says: "Database migrations require manual approval."

Developer asks: "Add a user preferences table."

Claude generates and runs a migration that alters existing tables, adding columns with default values that trigger a full table rewrite on a 50-million-row table. Production database locks for 20 minutes.

Why More Documentation Doesn't Help

The instinct is to write better CLAUDE.md rules. Make them more specific. Add more examples. Bold the important parts. But this is treating the symptom, not the disease.

The disease is that CLAUDE.md has no enforcement layer. It doesn't matter how well-written your rules are if there's no mechanism to detect and block violations before they happen.

You need something between "write rules in a markdown file and hope for the best" and "review every single line of AI-generated code manually." You need automated, semantic enforcement.

The Fix: SpecLock Turns CLAUDE.md Into Enforceable Constraints

SpecLock is an open-source AI constraint engine that reads your CLAUDE.md (and .cursorrules, and AGENTS.md) and converts those rules into semantically-enforced constraints. It works as an MCP server with 51 tools that integrate directly into your AI coding workflow.

Here's what changes when you add SpecLock:

• Rules become locks: SpecLock converts your CLAUDE.md rules into typed constraints with confidence levels. "Never switch frameworks" becomes a hard lock that triggers on any framework-related import changes.
• Semantic conflict detection: Before any change is applied, SpecLock checks it against all active constraints. It doesn't just do string matching; it understands what the change means and whether it conflicts with your rules.
• Drift scoring: SpecLock continuously monitors how far your codebase has drifted from your declared constraints, giving you a quantitative measure of compliance.
• Pre-commit hooks: Add SpecLock to your git hooks and rule-violating commits get blocked automatically, with a clear explanation of which constraint was violated.

Getting Started Is One Command

npx speclock protect

That's it. SpecLock reads your existing CLAUDE.md, discovers the rules in it, converts them to constraints, and starts enforcing. No config files to write. No dashboards to set up. It works with what you already have.

How SpecLock Enforcement Works in Practice

Let's revisit Example 1. You have a lock: "Always use Express.js." Claude generates code that imports Fastify. Here's what happens:

1. SpecLock's review_patch tool detects the new import.
2. Semantic analysis identifies this as a framework change.
3. The change is matched against the "Always use Express.js" constraint.
4. Conflict confidence: HIGH.
5. The change is flagged with a clear warning: "This change conflicts with constraint: Always use Express.js. The patch introduces a Fastify import, which would replace the locked framework."

The developer sees the warning and can either reject the change or explicitly override the constraint. Either way, the violation is visible and intentional rather than silent and accidental.

Beyond CLAUDE.md: A Universal Enforcement Layer

SpecLock doesn't just work with Claude Code. It enforces rules from .cursorrules (Cursor), AGENTS.md (Copilot), and any other rule file format. It works as an MCP server, meaning any AI tool that supports the Model Context Protocol can use it.

Your rules travel with your repo. Every AI tool that touches your code is bound by the same constraints. One source of truth, universally enforced.