| name | claude-md-maintenance |
| description | Maintain CLAUDE.md files effectively. Use when adding lessons learned, updating conventions, or restructuring project instructions. |
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
