How Rule Conflicts Happen
Rule conflicts occur when two rules give contradictory guidance for the same context. The AI receives both rules and must choose — often inconsistently. Common conflict types: direct contradiction (Rule A: 'use async/await.' Rule B: 'use callbacks for event handlers.'), scope overlap (Rule A: 'all functions use arrow syntax.' Rule B: 'React components use function declarations.' — what about a React component that is also a function?), and implicit conflict (Rule A: 'error handling uses try-catch.' Rule B: 'use the Result pattern for error handling.' — these are two different error handling philosophies that cannot coexist for the same code).
Where conflicts come from: multi-layer rule sets (organization rules conflict with team rules), technology mixing (TypeScript rules conflict with framework-specific rules), rule evolution (a new rule contradicts an old rule that was not removed), and copy-paste rules (rules copied from another project that assume different conventions). AI rule: 'Conflicts are inevitable in growing rule sets. The solution: systematic detection and resolution, not pretending they do not exist.'
The impact: when rules conflict, the AI's behavior becomes unpredictable. Sometimes it follows Rule A. Sometimes Rule B. The developer cannot predict which pattern the AI will generate. Code reviews catch the inconsistency — but the developer wonders: why does the AI generate different patterns for the same type of code? The answer: conflicting rules.
Step 1: Detecting Conflicts (10 Minutes)
Manual detection: read through the entire rule file looking for contradictions. Search for opposing keywords: class vs function, throw vs return, sync vs async, callback vs promise, default export vs named export. For each pair: do both rules apply to the same context? If yes: conflict. If they apply to different contexts (class for NestJS, function for React): no conflict, but the scoping should be explicit.
AI-assisted detection: ask the AI itself. Prompt: 'Read my CLAUDE.md and identify any rules that contradict each other or could cause confusion about which pattern to follow.' The AI: analyzes the rules from its perspective and flags rules that it would find ambiguous. This is remarkably effective because: the AI is the consumer of the rules. If it sees a conflict: it will produce inconsistent output. Its perspective: is the one that matters. AI rule: 'Ask the AI to audit its own rules. The AI's interpretation: reveals conflicts that a human reader might not notice because humans can infer context that the AI cannot.'
Pattern-based detection: generate 5 test prompts that cover different areas of the codebase. For each prompt: run it 3 times. If the AI generates different patterns for the same prompt: a conflict likely exists for that pattern. The inconsistency: is the symptom. Trace back to the conflicting rules. AI rule: 'Inconsistent AI output for the same prompt = rule conflict. The prompt did not change. The context did not change. The rules: are giving the AI mixed signals.'
Prompt: 'Read my CLAUDE.md and identify any rules that contradict each other or could cause confusion.' The AI analyzes the rules from the consumer's perspective — the exact perspective that matters. It flags: 'Rule 3 says use async/await. Rule 14 says use callbacks for events. For an async event handler: both rules apply and they contradict.' A human might not catch this because humans infer context. The AI: follows rules literally. Its confusion: reveals the conflict.
Step 2: Resolution Strategies
Strategy 1 — Scope narrowing: the most effective resolution. Make each rule apply to a specific, non-overlapping context. Before: 'Use async/await.' and 'Use callbacks for event handlers.' After: 'Async operations (API calls, database queries, file I/O): use async/await.' and 'DOM event handlers and Node.js event emitters: use callback functions.' The scopes: do not overlap. The AI: knows exactly which rule to apply in each context. AI rule: 'Scope narrowing eliminates the conflict by making each rule apply to a different context. It is the preferred resolution because neither rule is removed — they are refined.'
Strategy 2 — Priority ordering: when two rules genuinely conflict for the same context, declare which one takes precedence. 'Error handling default: use the Result pattern. Exception: for Express middleware, use try-catch with next(error) (Express requires this pattern for error propagation).' The priority: the specific exception overrides the default. AI rule: 'Priority ordering: use when one approach is the default and another is a specific exception. State both: the default AND the exception with its condition.'
Strategy 3 — Merge: when two rules describe different aspects of the same pattern, merge them into one comprehensive rule. Before: 'Use TypeScript strict mode.' and 'Enable noImplicitAny in tsconfig.' After: 'TypeScript: strict mode enabled (includes noImplicitAny, strictNullChecks, and all strict flags). No additional tsconfig flags needed beyond strict: true.' The merged rule: complete, non-contradictory, and easier for the AI to follow. AI rule: 'Merge when rules are complementary (describing different parts of the same pattern). Merge into one clear rule instead of maintaining two partial rules.'
Run the same prompt 3 times: 'Create a user service with error handling.' If the AI generates: Result pattern (run 1), try-catch (run 2), Result pattern (run 3) — the inconsistency is a rule conflict symptom. Two rules describe different error handling approaches. The AI: picks one each time without a clear preference. The fix: resolve the error handling conflict by scoping ('Business logic: Result pattern. Express middleware: try-catch with next(error).')
Step 3: Preventing Future Conflicts
The conflict checklist: before adding a new rule, answer: does this rule contradict any existing rule? (Search for opposing keywords.) Does this rule overlap in scope with an existing rule? (If both apply to the same context: clarify scope.) Does this rule introduce a new pattern for something already covered? (If yes: update the existing rule instead of adding a new one.) This 2-minute checklist: prevents most conflicts before they are committed. AI rule: 'The checklist is 3 questions. Takes 2 minutes. Prevents hours of debugging inconsistent AI output. Run it before every rule addition.'
Scope annotations: adopt a convention where every rule includes its scope explicitly. Format: '[Scope: TypeScript API routes] Use Zod for input validation.' The explicit scope: makes the rule's applicability clear to both humans and AI. When adding a new rule with a similar scope: the conflict is immediately visible. AI rule: 'Scope annotations add ~5 words per rule. They prevent the most common conflict type: two rules that apply to overlapping contexts without the AI knowing which to prioritize.'
Regular conflict audits: include conflict detection in the quarterly rule review. The AI-assisted audit (ask the AI to find contradictions): takes 5 minutes and catches conflicts that accumulated since the last review. Run it quarterly alongside the staleness check and coverage gap analysis. AI rule: 'Quarterly: ask the AI to audit its own rules for conflicts. This catches: conflicts from rules added by different people who did not check for contradictions, and implicit conflicts that emerge as the codebase evolves.'
Without scope: 'Use functional components.' Does this apply to React components? Vue components? NestJS services (they use classes)? All JavaScript functions? The AI: guesses. With scope: '[Scope: React components] Use functional components with hooks. No class components.' Now: unambiguous. The AI generates functional React components and class NestJS services without conflict. Five extra words per rule: eliminate the most common source of AI confusion.
Rule Conflict Resolution Summary
Summary of handling conflicting AI rules.
- Conflict types: direct contradiction, scope overlap, implicit philosophy conflict
- Detection: manual keyword search, AI-assisted audit, pattern-based testing (3 runs per prompt)
- Strategy 1 — Scope narrowing: make each rule apply to a specific, non-overlapping context. Preferred
- Strategy 2 — Priority ordering: default rule + specific exception with condition
- Strategy 3 — Merge: combine complementary rules into one comprehensive rule
- Prevention: 3-question checklist before adding any new rule (2 minutes)
- Scope annotations: [Scope: context] prefix on every rule. Makes applicability explicit
- Quarterly audit: ask the AI to find its own rule contradictions. 5 minutes, catches accumulated conflicts