claude-md-maintenance

Keep CLAUDE.md files lean, accurate, and useful.

Core Pattern

After mistakes or discoveries:

"Update CLAUDE.md so you don't make that mistake again"

This captures learnings before context resets.

When to Update

Add rules when:

• Same mistake happens twice
• Non-obvious convention discovered
• Critical project constraint identified

Remove rules when:

• Rule no longer applies (deps changed, pattern evolved)
• Duplicate or redundant with other rules
• Too specific (one-time fix, not pattern)

Structure Template

# Project Name

Brief purpose (1-2 lines).

## Key Commands

- `npm test` - run tests
- `npm run build` - production build

## Conventions

- Use X pattern for Y
- Always Z before committing

## Mistakes to Avoid

- Don't assume X (actually Y)
- Remember to check Z first

Hierarchy

Two levels, both loaded:

| File | Scope | Use For | | --------------------- | ------------ | ------------------------------------- | | ~/.claude/CLAUDE.md | All projects | Personal preferences, global patterns | | .claude/CLAUDE.md | This repo | Project conventions, tech stack rules |

Project-level overrides global when conflicting.

Size Guideline

Keep under 500 lines. Claude scans on every request.

Too long? Extract to references:

## API Patterns

See [api-patterns.md](docs/api-patterns.md) for details.

References

• structure-guide.md - Section organization
• lesson-patterns.md - Writing effective rules
• hierarchy.md - Global vs project scope