# The CLAUDE.md Playbook: From Data to Developer Value

**Purpose:** Practical guide to generating and deploying CLAUDE.md files  
**Prerequisite:** You've analyzed session data with qc-trace  
**Outcome:** Measurable improvement in AI session success rates

---

## Why CLAUDE.md Is the Perfect Starting Point

### It Fits the Workflow
- Developer opens AI tool (Claude Code, Cursor, etc.)
- AI automatically reads CLAUDE.md
- No action required from developer
- Value delivered invisibly

### It's Measurable
- Before: Session success rate without CLAUDE.md
- After: Session success rate with CLAUDE.md
- Clear causal relationship

### It Scales
- One file per repo
- Auto-generated from your data
- Can be updated periodically
- No ongoing maintenance burden

### It's Accepted
- Developers already use CLAUDE.md for project context
- Natural extension, not new concept
- Can be deleted if not helpful (no lock-in)

---

## Step 1: Extract Patterns from Your Data

### You Already Have This

From your analysis (`analysis-feb2026/qualitative/qualitative_analysis.py`):

```python
# Buckets with success rates
bucket_stats = {
    "error_paste_and_fix": {"success_rate": 0.95, "avg_trouble": 0.25},
    "code_review": {"success_rate": 0.87, "avg_trouble": 2.40},
    "detailed_spec": {"success_rate": 0.92, "avg_trouble": 1.80},
    "general": {"success_rate": 0.68, "avg_trouble": 4.90},
    "exploration": {"success_rate": 0.71, "avg_trouble": 4.00},
    "multi_task": {"success_rate": 0.23, "avg_trouble": 8.67},
    "vague_directive": {"success_rate": 0.19, "avg_trouble": 17.0},
}
```

### Transform to Actionable Guidelines

**Bad (data dump):**
```
Multi-task prompts have 8.67 avg trouble score
```

**Good (actionable):**
```
### ⚠️ Pattern: Multi-Task Prompts
**Success rate:** 23% (low)
**Problem:** AI tries to do too much, fails at everything
**Instead:** Break into separate prompts
❌ "Fix auth AND add tests AND update docs"
✅ "Fix auth issue in src/auth/login.ts"
✅ "Add tests for auth fix" (after first completes)
```

---

## Step 2: Generate Repo-Specific CLAUDE.md

### The Generation Script

```python
#!/usr/bin/env python3
# generate-claude-md.py

import json
from pathlib import Path
from typing import Dict, List

class ClaudeMDGenerator:
    def __init__(self, session_data_path: str):
        with open(session_data_path) as f:
            self.data = json.load(f)
    
    def generate(self, repo_name: str) -> str:
        sections = [
            self._header(repo_name),
            self._effective_patterns(),
            self._anti_patterns(),
            self._repo_specific_context(),
            self._troubleshooting(),
        ]
        return '\n\n'.join(sections)
    
    def _header(self, repo_name: str) -> str:
        return f"""# AI Collaboration Guide — {repo_name}

*Auto-generated from session analysis. This file helps AI assistants work effectively with your codebase.*

## How to Use This

This file is automatically read by Claude Code, Cursor, and other AI tools.
It contains patterns that work well (and don't work well) in this specific codebase.
"""
    
    def _effective_patterns(self) -> str:
        # Extract top 3 most successful patterns from data
        top_patterns = self._get_top_patterns(n=3)
        
        lines = ["## ✅ Patterns That Work Well\n"]
        
        for i, pattern in enumerate(top_patterns, 1):
            lines.append(f"""### {i}. {pattern['name']} — {pattern['success_rate']}% success

**When to use:** {pattern['description']}

**Example:**
```
{pattern['example']}
```

**Why it works:** {pattern['explanation']}
""")
        
        return '\n'.join(lines)
    
    def _anti_patterns(self) -> str:
        # Extract patterns with high failure rates
        bad_patterns = self._get_problematic_patterns()
        
        lines = ["## ⚠️ Patterns to Avoid\n"]
        
        for pattern in bad_patterns:
            lines.append(f"""### {pattern['name']} — {pattern['success_rate']}% success

**The problem:** {pattern['problem']}

**Common example:**
```
{pattern['bad_example']}
```

**Better approach:**
```
{pattern['good_example']}
```
""")
        
        return '\n'.join(lines)
    
    def _repo_specific_context(self) -> str:
        # Extract from your existing data
        return """## 📁 Repository Structure

### Key Entry Points
- Main app: `src/index.ts`
- API routes: `src/routes/`
- Database models: `src/models/`
- Tests: `tests/**/*.test.ts`

### Conventions
- Use TypeScript strict mode
- Prefer async/await over callbacks
- Use existing error handling patterns
- Follow naming conventions in existing files

### Testing
- Run `npm test` before committing
- Maintain >80% coverage
- Use existing test patterns
"""
    
    def _troubleshooting(self) -> str:
        # Extract from your error detection data
        return """## 🔧 Troubleshooting Common Issues

### "AI keeps getting null results"
**Symptom:** Tool calls return empty results  
**Cause:** MCP server connection issue  
**Fix:** Restart MCP server: `mcp-restart`

### "AI references files that don't exist"
**Symptom:** "No such file or directory" errors  
**Cause:** AI hallucinated file paths  
**Fix:** Always verify paths with `ls` before referencing

### "AI is stuck in error loop"
**Symptom:** 3+ consecutive shell errors  
**Fix:** Reset context with `/reset` or `/clear`

### "AI is exploring but not editing"
**Symptom:** Many file reads, no changes  
**Fix:** Provide more specific instructions with file paths
"""
    
    def _get_top_patterns(self, n: int) -> List[Dict]:
        # Use your actual analysis data
        return [
            {
                "name": "Error Paste + Fix",
                "success_rate": 95,
                "description": "When you have a stack trace or error message",
                "example": "Fix this error: \"TypeError: Cannot read property 'id' of undefined at src/auth.js:42\"",
                "explanation": "AI can diagnose and fix specific errors when given full context"
            },
            {
                "name": "Single-File Review",
                "success_rate": 87,
                "description": "When you want feedback on specific code",
                "example": "Review src/auth/login.ts for security issues",
                "explanation": "Focused scope leads to thorough, actionable feedback"
            },
            {
                "name": "Detailed Specification",
                "success_rate": 92,
                "description": "When implementing a feature",
                "example": """Add a login endpoint that:
- Accepts email and password in request body
- Validates against User model
- Returns JWT token on success
- Returns 401 on invalid credentials
- Use bcrypt for password comparison""",
                "explanation": "Clear requirements lead to correct implementation"
            }
        ]
    
    def _get_problematic_patterns(self) -> List[Dict]:
        return [
            {
                "name": "Multi-Task Prompts",
                "success_rate": 23,
                "problem": "AI tries to do too much, often fails at everything",
                "bad_example": "Fix the auth bug, add tests, update the docs, and deploy",
                "good_example": "Fix auth bug in src/auth/login.ts (tests and docs will be separate prompts)"
            },
            {
                "name": "Vague Directives",
                "success_rate": 19,
                "problem": "AI doesn't know what 'better' or 'improve' means",
                "bad_example": "Make this code better",
                "good_example": "Extract the validation logic into a separate function and add input sanitization"
            }
        ]

# Usage
generator = ClaudeMDGenerator('path/to/your/session_analysis.json')
content = generator.generate('my-project')

with open('CLAUDE.md', 'w') as f:
    f.write(content)

print("✅ Generated CLAUDE.md")
print("📋 Next steps:")
print("   1. Review the generated file")
print("   2. Add project-specific details")
print("   3. Commit to repo: git add CLAUDE.md && git commit -m 'Add AI collaboration guidelines'")
print("   4. Ask a developer to try an AI session with it")
```

---

## Step 3: The Deployment Strategy

### Option A: The Champion Approach (Recommended)

**Week 1:**
1. Identify 1-2 developers who complain about AI inefficiency
2. Generate CLAUDE.md for their primary repo
3. Send them the file with message:
   ```
   Hey [Name],
   
   I generated this based on our team's AI session analysis.
   It's like a style guide, but for AI collaboration.
   
   Mind trying it for a week? Just commit it to your repo
   and see if Claude/Cursor seems to "get" your codebase better.
   
   If it's not helpful, just delete it — no worries.
   ```

**Week 2:**
4. Ask for feedback
5. If positive: ask them to share with 1 colleague
6. If negative: iterate on content

**Week 3-4:**
7. Expand to 3-5 repos using the same pattern
8. Track adoption

---

### Option B: The PR Approach (For Faster Rollout)

**Script:**
```bash
#!/bin/bash
# deploy-claude-md.sh

REPOS=("repo-a" "repo-b" "repo-c")

for repo in "${REPOS[@]}"; do
  echo "Processing $repo..."
  
  # Generate CLAUDE.md
  python generate-claude-md.py --repo=$repo --output=/tmp/CLAUDE.md
  
  # Create branch and commit
  cd "/path/to/$repo"
  git checkout -b "add-ai-guidelines"
  cp /tmp/CLAUDE.md .
  git add CLAUDE.md
  git commit -m "docs: Add AI collaboration guidelines

This file helps AI assistants (Claude, Cursor, etc.) work
effectively with our codebase. It includes:

- Patterns that work well based on session analysis
- Common anti-patterns to avoid
- Repository-specific context

Auto-generated from team session data.
See: [link to internal docs]"
  
  # Push and create PR
  git push origin add-ai-guidelines
  
  # Create PR via CLI (gh or similar)
  gh pr create \
    --title "Add AI collaboration guidelines (CLAUDE.md)" \
    --body "This PR adds a CLAUDE.md file that helps AI assistants work better with our codebase.

**What's in it:**
- ✅ Patterns that have high success rates (based on session analysis)
- ⚠️ Common mistakes to avoid
- 📁 Repository structure and conventions

**How to test:**
1. Check out this branch
2. Start a Claude/Cursor session
3. Ask it to make a change
4. Notice it follows conventions better

No obligation to merge — just trying this out to see if it helps."

done
```

**Follow-up:**
- Monitor PR comments
- Address concerns
- Merge if no objections
- Track which repos keep it

---

## Step 4: Measure Adoption and Impact

### Tracking Script

```python
#!/usr/bin/env python3
# track-claude-md-adoption.py

import subprocess
from datetime import datetime, timedelta
import json

def get_repos():
    """Get list of repos to track."""
    # Query your repo database or GitHub org
    return ["repo-a", "repo-b", "repo-c", ...]

def has_claude_md(repo: str) -> bool:
    """Check if repo has CLAUDE.md."""
    result = subprocess.run(
        ["git", "-C", f"/path/to/{repo}", "ls-files", "CLAUDE.md"],
        capture_output=True,
        text=True
    )
    return result.returncode == 0 and "CLAUDE.md" in result.stdout

def get_session_stats(repo: str, since_days: int = 7):
    """Get AI session stats for repo."""
    # Query your qc-trace database
    from qc_trace.db.reader import get_stats
    
    return get_stats(
        repo=repo,
        since=datetime.now() - timedelta(days=since_days)
    )

def generate_report():
    repos = get_repos()
    
    report = {
        "generated_at": datetime.now().isoformat(),
        "total_repos": len(repos),
        "repos_with_claude_md": 0,
        "adoption_rate": 0.0,
        "with_vs_without": {
            "with_claude_md": {"sessions": 0, "success_rate": 0},
            "without_claude_md": {"sessions": 0, "success_rate": 0}
        }
    }
    
    for repo in repos:
        has_file = has_claude_md(repo)
        stats = get_session_stats(repo)
        
        if has_file:
            report["repos_with_claude_md"] += 1
            report["with_vs_without"]["with_claude_md"]["sessions"] += stats["session_count"]
            report["with_vs_without"]["with_claude_md"]["success_rate"] += stats["success_rate"]
        else:
            report["with_vs_without"]["without_claude_md"]["sessions"] += stats["session_count"]
            report["with_vs_without"]["without_claude_md"]["success_rate"] += stats["success_rate"]
    
    report["adoption_rate"] = report["repos_with_claude_md"] / report["total_repos"] * 100
    
    # Calculate averages
    for group in ["with_claude_md", "without_claude_md"]:
        count = report["with_vs_without"][group]["sessions"]
        if count > 0:
            report["with_vs_without"][group]["success_rate"] /= count
    
    return report

if __name__ == "__main__":
    report = generate_report()
    
    print("\n" + "="*60)
    print("CLAUDE.md Adoption Report")
    print("="*60)
    print(f"\n📊 Adoption:")
    print(f"   Repos with CLAUDE.md: {report['repos_with_claude_md']}/{report['total_repos']} ({report['adoption_rate']:.1f}%)")
    
    print(f"\n🎯 Impact (last 7 days):")
    with_data = report["with_vs_without"]["with_claude_md"]
    without_data = report["with_vs_without"]["without_claude_md"]
    
    print(f"   With CLAUDE.md:    {with_data['success_rate']:.1f}% success rate ({with_data['sessions']} sessions)")
    print(f"   Without CLAUDE.md: {without_data['success_rate']:.1f}% success rate ({without_data['sessions']} sessions)")
    
    if with_data["sessions"] > 0 and without_data["sessions"] > 0:
        improvement = with_data['success_rate'] - without_data['success_rate']
        print(f"\n📈 Improvement: +{improvement:.1f} percentage points")
    
    # Save to file
    with open(f"reports/claude-md-adoption-{datetime.now().strftime('%Y-%m-%d')}.json", 'w') as f:
        json.dump(report, f, indent=2)
    
    print(f"\n💾 Full report saved to reports/")
```

### Sample Output

```
============================================================
CLAUDE.md Adoption Report
============================================================

📊 Adoption:
   Repos with CLAUDE.md: 12/20 (60.0%)

🎯 Impact (last 7 days):
   With CLAUDE.md:    74.3% success rate (142 sessions)
   Without CLAUDE.md: 61.2% success rate (89 sessions)

📈 Improvement: +13.1 percentage points

💾 Full report saved to reports/
```

---

## Step 5: Iterate and Improve

### Update Strategy

**Monthly Refresh:**
```python
# update-claude-md.py

def update_claude_md(repo: str):
    """Update existing CLAUDE.md with new patterns."""
    
    # Get new session data
    new_data = get_recent_sessions(repo, days=30)
    
    # Check if patterns have changed
    current_patterns = extract_patterns_from_claude_md(repo)
    new_patterns = extract_patterns_from_data(new_data)
    
    if patterns_changed(current_patterns, new_patterns):
        # Generate updated file
        generator = ClaudeMDGenerator(new_data)
        new_content = generator.generate(repo)
        
        # Create PR with changes
        create_update_pr(repo, new_content)
        
        return True
    
    return False
```

### Feedback Integration

**Add to CLAUDE.md footer:**
```markdown
---

## Feedback

This file is auto-generated. To suggest improvements:
1. Edit this file directly
2. Or open an issue at: [internal-link]
3. Or DM [your-name] on Slack

Last updated: 2026-02-18
Next review: 2026-03-18
```

---

## The Complete Workflow

```
Week 1: Generate & Pilot
├── Day 1-2: Generate CLAUDE.md for 1 repo
├── Day 3: Share with 1 champion developer
├── Day 4-5: Get feedback, iterate
└── Day 6-7: Deploy to 2 more repos

Week 2: Measure
├── Track adoption (script runs daily)
├── Compare success rates
└── Survey developers

Week 3-4: Expand
├── Deploy to 5 more repos
├── Refine based on feedback
└── Calculate ROI

Month 2: Automate
├── Auto-generate for new repos
├── Monthly refresh of existing
└── Integrate with CI/CD

Month 3+: Scale
├── Expand to all active repos
├── Add IDE extensions (optional)
└── Consider real-time features (if proven valuable)
```

---

## Common Questions

### "What if developers don't want it?"

**Answer:** They can delete it. The goal is to make it so valuable they won't want to.

**Mitigation:**
- Start with volunteers only
- Make it optional
- Show value before asking for adoption
- If 50%+ delete it, iterate on content

---

### "What about repos with different tech stacks?"

**Answer:** Generate repo-specific files.

**Implementation:**
```python
def generate_for_repo(repo: str):
    # Detect tech stack
    stack = detect_stack(repo)  # Look at package.json, etc.
    
    # Get stack-specific patterns
    patterns = get_patterns_for_stack(stack)
    
    # Generate with stack context
    return generator.generate(repo, stack=stack)
```

---

### "How often should we update CLAUDE.md?"

**Answer:** Monthly for active repos, quarterly for stable ones.

**Rationale:**
- Patterns don't change that fast
- Monthly keeps it fresh without noise
- Major updates = PR (developer approval)
- Minor updates = direct commit

---

### "What if the data shows something embarrassing?"

**Answer:** Frame it as system issues, not individual problems.

**Bad:**
```
John's multi-task prompts have 20% success rate
```

**Good:**
```
Multi-task prompts in this repo have 20% success rate
→ Recommendation: Break complex tasks into separate prompts
```

---

## Success Metrics Checklist

**Week 2:**
- [ ] 1 repo has CLAUDE.md
- [ ] 1 developer says it's helpful

**Week 4:**
- [ ] 5 repos have CLAUDE.md
- [ ] Measurable improvement in success rates

**Week 8:**
- [ ] 50% of target repos have CLAUDE.md
- [ ] +10 percentage point improvement
- [ ] Developers asking for it in their repos

**Month 3:**
- [ ] Standard practice for new repos
- [ ] Auto-generation pipeline
- [ ] Proven ROI for leadership

---

## Next Steps

1. **Right now:** Generate CLAUDE.md for your most active repo
2. **Today:** Find 1 developer to test it
3. **This week:** Get feedback and iterate
4. **Next week:** Expand to 3 more repos

**Remember:** One file. One repo. One developer. Iterate.

You have the data. You have the algorithms. Now you have the delivery mechanism.

Start today.
