Optimize CLAUDE.md

Analyze, audit, and optimize CLAUDE.md files based on Anthropic's official best practices for effective Claude Code configuration.

Degrees of Freedom

This is a medium-freedom task. Follow the structured workflow but adapt recommendations based on the specific project's needs, tech stack, and team conventions.

Workflow

Copy this checklist and track your progress:

Optimization Progress:
- [ ] Step 1: Analyze current CLAUDE.md state
- [ ] Step 2: Audit against best practices checklist
- [ ] Step 3: Identify and prioritize issues
- [ ] Step 4: Generate recommendations
- [ ] Step 5: Apply or present changes

1. Analyze Current State

Read the existing CLAUDE.md (if present) and assess:

• Current structure and organization
• Content categories present
• Length and verbosity
• Presence of anti-patterns

2. Audit Against Best Practices

Compare against the checklist in references/best-practices.md.

Score each category:

• Present & Good - Follows best practices
• Present but Needs Work - Exists but could be improved
• Missing - Should be added
• Anti-pattern - Should be removed/fixed

3. Generate Recommendations

Prioritize changes by impact:

High Priority:

• Remove sensitive information (API keys, credentials)
• Fix anti-patterns (generic advice, excessive length)
• Add missing critical sections (project structure, commands)

Medium Priority:

• Improve organization and scannability
• Add missing helpful sections
• Condense verbose explanations

Low Priority:

• Formatting improvements
• Minor restructuring
• Optional enhancements

4. Apply Changes

Either:

• Suggest mode: Present recommendations for user approval
• Apply mode: Directly edit CLAUDE.md with improvements

Optimization Principles

Keep It Concise

CLAUDE.md is loaded into context every time. Total limit: 40k tokens (CLAUDE.md + all @referenced files combined).

# BAD: Verbose explanation
## Testing Guidelines
When running tests in this project, you should use the npm test command.
This will execute all test files and provide output. Make sure tests pass.

# GOOD: Concise and actionable
## Testing
npm test                    # Run all tests
npm run test:coverage       # With coverage report

Be Specific, Not Generic

Include YOUR project's actual patterns, not theoretical best practices.

# BAD: Generic advice
Follow clean code principles and write maintainable code.

# GOOD: Project-specific guidance
Use `logger` from @/utils, never console.log (tree-shaken in production).
Query keys must use queryKeys factory from @/lib/queryKeys.

Use Progressive Disclosure

For large documentation, split into separate files and reference them:

# In CLAUDE.md
See @.claude/rules/testing.md for testing standards.
See @docs/ARCHITECTURE.md for system design.

# NOT: 500 lines of testing docs inline

Include Actual Commands

Show the commands your team uses:

## Development
npm run dev     # Start dev server (localhost:3000)
npm test        # Run tests in watch mode
npm run build   # Production build

Use Emphasis for Critical Rules

For must-follow instructions, use emphasis markers:

IMPORTANT: Never commit directly to main.
YOU MUST run tests before pushing.
ALWAYS use logger utility, never console.log.

Output Format

When optimizing, provide:

1. Summary - Brief assessment (1-2 sentences)
2. Score - X/10 rating with breakdown
3. Critical Issues - Must-fix problems
4. Recommendations - Prioritized improvements
5. Optimized CLAUDE.md - The improved file (if applying changes)

Example Assessment

## CLAUDE.md Optimization Report

**Summary:** Good foundation but overly verbose. Contains generic advice that adds token cost without value.

**Score:** 6/10
- Structure: 8/10 (well-organized sections)
- Conciseness: 4/10 (too verbose, 2000+ lines)
- Specificity: 5/10 (mix of specific and generic)
- Security: 9/10 (no sensitive data found)

**Critical Issues:**
1. File exceeds 500 lines - should use modular rules files
2. Contains generic "best practices" not specific to project

**Recommendations:**
1. [HIGH] Move detailed rules to .claude/rules/*.md files
2. [HIGH] Remove generic coding advice Claude already knows
3. [MED] Add missing quick-start commands section
4. [LOW] Consolidate duplicate information in docs/

Resources

references/

• best-practices.md - Complete checklist for CLAUDE.md optimization