Agent Rule Compliance Auditor

The Problem

You spent three hours crafting a 400-line CLAUDE.md. You documented every convention, every pitfall, every "do not" and "always." You fire up Claude Code, and by turn 3, it's ignoring your TypeScript rule and generating .jsx files. Your security rules — on lines 351-487 of the CLAUDE.md — never got processed because the agent's attention faded after line 200. Your skill file (react-component-generator) injects a conflicting rule about file formats that overrides your project-level TypeScript directive. And buried in the CLAUDE.md at line 187 is "be careful with database operations" — a rule so vague it's meaningless to the agent.

This isn't a model capability problem. It's an information architecture problem. Agents don't "decide" to ignore rules. They fail to apply them because the rules are ambiguous, contradictory, buried in noise, competing for limited attention, or stated once without reinforcement.

What You Get

• Seven-point compliance audit — Ambiguity Check (vague language → specific directive), Contradiction Detection (cross-file conflict scanning), Position Decay Analysis (line 1-50 = 90% compliance, 200+ = 40%, 400+ = 15%), Density Scoring (>8 directives per 100 lines = overload), Reinforcement Gap Analysis (critical rules with no reinforcement points), Scope Overlap Detection (rules that overlap without declaring precedence), Kill-Switch Absence (absolute prohibitions without escape hatches)
• Three-tier priority hierarchy — Tier 1: Critical (security, data loss, build-breaking — 5-8 rules max, 100% compliance target), Tier 2: Important (code quality, standards — 8-15 rules, 80%+ target), Tier 3: Nice-to-Have (style preferences — unlimited, best effort)
• CONFIG_AUDIT.md output — executive summary with compliance health score (A-F), before/after for every ambiguous directive, contradiction resolutions with both sides shown, priority reordering map, density reduction suggestions, and a proposed restructured CLAUDE.md v2
• Cross-file conflict scanning — compares directives across CLAUDE.md, .cursorrules, AGENTS.md, SOUL.md, and every SKILL.md in the project to find rules that contradict each other
• Reinforcement plan — identifies critical rules that have no reinforcement (no skill reference, no hook, no session-init mention) and suggests where to add reinforcement points
• Smoke test — after applying fixes, ask the agent to list its top 5 rules; it should return Tier 1 directives verbatim

Why This Beats Prompting It Yourself

"You keep adding 'MUST' and 'NEVER' to rules that are too vague" is a known failure mode — volume doesn't fix specificity. The auditor diagnoses why each rule is being ignored (ambiguity vs. contradiction vs. position decay vs. overload) and prescribes a specific structural fix. Adding "MUST be careful" to a vague rule is still "be careful." The auditor catches this pattern and rewrites it as a specific, testable instruction with trigger conditions and verification steps.

Example Session

You: "My agent keeps ignoring rules after a few turns. Here's my CLAUDE.md (487 lines)."

Agent:

# CONFIG_AUDIT.md — Agent Rule Compliance Report

## Executive Summary
**Compliance Health Score: D (43/100)**
Top 3 Issues:
1. 4 critical security rules buried on lines 351-487 (~15% compliance)
2. 12 contradictions between CLAUDE.md and 3 active skill files
3. 67% of directives are ambiguous ("be careful", "try to", "when appropriate")

## Ambiguity Fixes (Before → After)
**Line 187 (Before):**
  "Be careful with database operations and make sure everything is backed up."
**Audit:** AMBIGUITY (Score: 9/10) — "be careful" is a feeling, not an instruction.
**After:**
  "Database Operations (CRITICAL): Before any mutation (INSERT/UPDATE/DELETE/ALTER/DROP):
   1. Run in a transaction
   2. Verify affected row count
   3. If >1000 rows: ABORT and ask for confirmation
   4. NEVER run DROP/TRUNCATE without user approval containing 'CONFIRM_DROP'"

## Contradiction Resolution
**CLAUDE.md line

Use Cases

• Config debugging — diagnose why your agent ignores specific rules despite clear instructions in CLAUDE.md
• New project setup — audit the initial config before the team starts relying on it
• Skill conflict resolution — find and fix contradictions between project rules and newly installed skills
• Config restructuring — reorganize a bloated CLAUDE.md into a focused, attention-aware format
• Team standardization — ensure agent configs across multiple projects have consistent compliance

Known Limitations

The auditor diagnoses structural issues in config files but cannot fix model capability limitations — if the model genuinely cannot do something, no config will change that. It analyzes text-based config files (CLAUDE.md, .cursorrules, AGENTS.md, SKILL.md); behavioral rules injected by MCP servers, environment variables, or runtime configurations are outside scope. The audit produces findings and proposed fixes; applying changes requires explicit user approval per finding.