Skip to main content
Generalspences10

claude-md-maintenance

Maintain CLAUDE.md files effectively. Use when adding lessons learned, updating conventions, or restructuring project instructions.

Stars
33
Source
spences10/claude-code-toolkit
Updated
2026-04-29
Slug
spences10--claude-code-toolkit--claude-md-maintenance
View on GitHubRaw SKILL.md

// install — copy + paste into any project

mkdir -p .claude/skills && curl -fsSL https://raw.githubusercontent.com/spences10/claude-code-toolkit/HEAD/plugins/claude-workflow/skills/claude-md-maintenance/SKILL.md -o .claude/skills/claude-md-maintenance.md

Drops the SKILL.md into .claude/skills/claude-md-maintenance.md. Works with Claude Code, Cursor, and any agent that loads SKILL.md files from .claude/skills/.

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