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 for details.

References

• structure-guide.md - Section organization

• lesson-patterns.md - Writing effective rules

• hierarchy.md - Global vs project scope