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
- sefaertunc/anthropic-watchword for word, first seen Apr 30, 2026
Other versions1 project uses a version of this.
Word for word · 1
- sefaertunc/anthropic-watch★ 1100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository18 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- agent-routingSkill
- backend-conventionsSkill
- coding-principlesSkill
- context-managementSkill
- coordinator-modeSkill
- frontend-design-systemSkill
- git-conventionsSkill
- memory-architectureSkill
- planning-with-filesSkill
- project-patternsSkill
- prompt-engineeringSkill
- review-and-handoffSkill
- security-checklistSkill
- subagent-usageSkill
- testingSkill
- verificationSkill
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
- Distinctive: line 11
When Claude makes the same mistake twice, it should update CLAUDE.md to prevent a third occurrence.
- Distinctive: line 88
Remove rules for code that no longer exists
- Distinctive: line 91
Remove gotchas that have been fixed at the code level
- Distinctive: line 101
Always review proposed changes before applying.
- Distinctive: line 102
Only add rules for recurring problems.
- Very specific: line 106
When CLAUDE.md outgrows what one file can hold cleanly, use @path/to/import to split content into separate files that still load with …
- Distinctive: line 124
Does NOT work inside code blocks (only in leaf text nodes)
- Distinctive: line 166
Don't add rules preemptively.
- Distinctive: line 168
If CLAUDE.md contradicts a skill file, CLAUDE.md wins.
≈ “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.
Files
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:
- Claude makes mistake X
- User corrects Claude
- Claude makes mistake X again
- Claude (or user) adds a rule to CLAUDE.md: "Don't do X. Do Y instead."
- 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 compatEach 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:
- Reviews what happened during the session
- Identifies mistakes that should become rules
- Identifies patterns worth documenting
- 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.mdSyntax (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.mdThe 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.
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
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.

