agentleFS
sefaertuncsefaertunc/Worclaude/.claude/skills/claude-md-maintenance/SKILL.md

claude-md-maintenance

Skill4 starsChanged 7 months agoMITView on GitHub

How Claude writes rules for itself, when to update CLAUDE.md, keeping it lean and effective

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 8 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈8

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When Claude makes the same mistake twice, it should update CLAUDE.md to prevent a third occurrence.

    line 11
  2. Distinctive:

    Remove rules for code that no longer exists

    line 88
  3. Distinctive:

    Remove gotchas that have been fixed at the code level

    line 91
  4. Distinctive:

    Always review proposed changes before applying.

    line 101
  5. Distinctive:

    Only add rules for recurring problems.

    line 102
  6. Very specific:

    When CLAUDE.md outgrows what one file can hold cleanly, use @path/to/import to split content into separate files that still load with …

    line 106
  7. Distinctive:

    Does NOT work inside code blocks (only in leaf text nodes)

    line 124
  8. Distinctive:

    Don't add rules preemptively.

    line 166
  9. Distinctive:

    If CLAUDE.md contradicts a skill file, CLAUDE.md wins.

    line 168

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

CLAUDE.md Maintenance

The Self-Healing Pattern

When Claude makes the same mistake twice, it should update CLAUDE.md to prevent a third occurrence. This is "self-healing" — the system learns from its errors.

The cycle:

  1. Claude makes mistake X
  2. User corrects Claude
  3. Claude makes mistake X again
  4. Claude (or user) adds a rule to CLAUDE.md: "Don't do X. Do Y instead."
  5. Mistake X doesn't happen again

This is why the Gotchas section exists. It grows organically from real problems encountered during development.

The 200-Line Target

CLAUDE.md should stay under 200 lines of actual content. This is the official Claude Code guidance and matches worclaude doctor's WARN threshold (150 lines / 30,000 chars) and ERROR threshold (200 lines). It is a target, not a hard limit, but exceeding it significantly means CLAUDE.md is trying to do too much.

Claude reads CLAUDE.md at the start of every session and after every /compact. Long CLAUDE.md files waste context on every single interaction.

What Belongs in CLAUDE.md

YES:

  • Project identity (name, one-line description)
  • Key file pointers (PROGRESS.md, SPEC.md)
  • Tech stack and build/test/run commands
  • Session protocol (start/during/end)
  • Critical rules (5-10 maximum)
  • Gotchas (grows, but prune regularly)
  • Skills pointer (list of available skills)

NO:

  • Detailed coding standards (put in a skill)
  • Architecture documentation (put in a skill or docs/)
  • API documentation (put in docs/)
  • Full workflow descriptions (put in a skill)
  • Things Claude already knows (common language features, standard libraries)

What Belongs in Skills vs CLAUDE.md

CLAUDE.md: things Claude needs to know EVERY session, regardless of task. Skills: things Claude needs to know SOMETIMES, for specific types of work.

Example:

  • "Use conventional commits" -> CLAUDE.md (applies to every commit)
  • "Commit message format: type(scope): description, body explains why..." -> skill (only needed when actually writing commits)

Maintaining the Gotchas Section

The Gotchas section captures project-specific traps. Format:

## Gotchas
- The settings merger must handle comment strings in JSON arrays (they're not valid
  JSON but we support them for readability)
- Always use path.join(), never string concatenation for file paths — breaks on Windows
- The backup directory uses timestamps with colons replaced by hyphens for Windows compat

Each gotcha should be:

  • Specific (not "be careful with paths")
  • Actionable (says what to do, not just what's wrong)
  • Born from real experience (don't pre-populate with hypotheticals)

When to Prune

Review CLAUDE.md when:

  • It exceeds the 200-line target
  • You notice rules that no longer apply
  • A rule has been absorbed into a skill
  • Two rules say the same thing differently

Pruning checklist:

  • Remove rules for code that no longer exists
  • Consolidate duplicate rules
  • Move detailed guidance to skills
  • Remove gotchas that have been fixed at the code level

Using /update-claude-md

The /update-claude-md command helps at session end:

  1. Reviews what happened during the session
  2. Identifies mistakes that should become rules
  3. Identifies patterns worth documenting
  4. Proposes additions with diffs

Always review proposed changes before applying. Not every mistake needs a rule. Only add rules for recurring problems.

The @include Directive

When CLAUDE.md outgrows what one file can hold cleanly, use @path/to/import to split content into separate files that still load with CLAUDE.md:

# CLAUDE.md
## Key Files
@README
@docs/git-instructions.md
@~/.claude/my-project-instructions.md

Syntax (per official Claude Code docs):

  • @path/to/import — relative to the file containing the directive (e.g., @README, @docs/git-instructions.md)
  • @~/path — home-directory relative (e.g., @~/.claude/my-project-instructions.md)
  • Works in CLAUDE.md, .claude/CLAUDE.md, .claude/rules/*.md, and CLAUDE.local.md
  • Does NOT work inside code blocks (only in leaf text nodes)
  • Non-existent files are silently ignored; circular references are prevented

Behavior:

  • Imports load at launch and consume context. They help organization, not context budget. Splitting CLAUDE.md into 5 files of 50 lines each produces the same context cost as one 250-line file.
  • Recursion is capped at 5 hops. A imports B imports C... — Claude stops resolving after 5 levels.
  • External imports trigger an approval dialog on first use. Importing a path outside the project root (e.g., a system-wide config) prompts the user to confirm before the import resolves. This is a one-time approval.

The @~/.claude/... worktree-share pattern

Worktree agents (isolation: worktree) operate in a freshly-checked-out copy of the repo. Anything in .claude/CLAUDE.local.md or other gitignored files is not present in the worktree, so the agent loses your local rules.

Workaround: store shared local rules in a home-directory file and import it from the project's CLAUDE.md:

# CLAUDE.md
@~/.claude/my-team-rules.md

The worktree agent re-reads ~/.claude/my-team-rules.md at launch (it lives outside the repo, so no checkout is needed) and gets the same rules as your main session. The first run triggers an external-import approval; after that it loads silently.

Reserve this pattern for rules that belong to you across all projects (coding style preferences, personal shortcuts). Team-shared rules should still live inside the repo.

Gotchas

  • CLAUDE.md is read as system context, not as a document. Write it as instructions, not as documentation. "Use path.join for file paths" not "The project uses path.join for file paths because..."
  • Don't add rules preemptively. Wait for the mistake to happen twice. Premature rules clutter the file without proven value.
  • If CLAUDE.md contradicts a skill file, CLAUDE.md wins. Keep them consistent.
  • Skills are loaded on demand. CLAUDE.md is always loaded. Use this asymmetry intentionally.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.