The Claude Code
Maintenance Checklist

--- name: claude-code-maintenance description: Audits my Claude Code setup (CLAUDE.md files, rules, skills, auto memory, settings and permissions, hooks, MCP servers, plugins) for instructions that are outdated, repeated, contradictory, vague, or costing context for no reason. Produces keep, cut, merge, rewrite, or move recommendations with a context cost estimate, then waits for my approval before editing anything. Use when I ask for a maintenance audit, a setup cleanup, or a tune-up, or right after a new Claude model comes out. disable-model-invocation: true --- # Claude Code Maintenance Audit You are auditing my Claude Code setup. The standard is simple. Every instruction has to earn its place. For each one, ask whether Claude still needs it, and whether I could delete it and get the same result. You read everything. You change nothing until I approve specific items by number. ## Ground rules 1. Read-only until I approve. No edits, deletions, moves, renames, or settings changes until I reply with the numbers to apply. 2. Quote, never paraphrase. Every finding cites the file path, the line numbers, and the exact text. 3. Verify before you call something stale. Check that a file, script, command, path, or tool is really missing before you say so. Label each one VERIFIED STALE or POSSIBLY STALE. 4. Do not invent problems to look useful. If a line is good, the verdict is KEEP. A short audit with five real findings beats a long one with fifty weak ones. 5. Never print secrets. If you find an API key, token, or password in any instruction or config file, report the file and line number only, and flag it as a security item. 6. Do not rely on your training data for Claude Code features. Run `claude --version` first. If a recommendation depends on a command, setting, or frontmatter field, confirm it in the current docs at https://code.claude.com/docs before you recommend it. 7. Treat shared team files carefully. Changes to a checked-in CLAUDE.md, .claude/settings.json, .mcp.json, or project skills get marked "propose to team", not applied quietly. 8. Stay inside my Claude Code setup. Do not touch application code. ## Step 1: Inventory Find every piece of my setup and build one table with these columns. File | Scope (managed, user, project, local, plugin) | When it loads | Lines | Characters | Approx tokens Measure with `wc -l` and `wc -c`. Estimate tokens as characters divided by 4, and say clearly that this is a rough estimate. Real numbers come from /context. Loads at the start of every session: - Managed policy CLAUDE.md if one exists (macOS: /Library/Application Support/ClaudeCode/CLAUDE.md, Linux: /etc/claude-code/CLAUDE.md). Report it, but it cannot be excluded or edited by me. - ~/.claude/CLAUDE.md, plus ~/.claude/rules/ files with no `paths:` frontmatter - CLAUDE.md, .claude/CLAUDE.md, and CLAUDE.local.md in the folder I launched from and every parent folder above it - .claude/rules/ files with no `paths:` frontmatter - Every file pulled in by an `@path` import. Imports load at launch too, up to four hops deep. Splitting a file into imports does not save context. - The auto memory index at ~/.claude/projects/<this project>/memory/MEMORY.md. Only the first 200 lines or 25KB load, whichever comes first. Anything past that is silently dropped. - The name and description of every skill Claude is allowed to invoke. Skills with `disable-model-invocation: true` cost nothing here until I run them. - Subagent names and descriptions from ~/.claude/agents/ and .claude/agents/ Loads only when needed: - CLAUDE.md files in subfolders, and rules files with `paths:` frontmatter - Skill bodies (~/.claude/skills/*/SKILL.md, .claude/skills/*/SKILL.md, plugin skills) and their supporting files - Auto memory topic files next to MEMORY.md Configuration: - ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json (permissions, hooks, env, skillOverrides, enabledPlugins, claudeMdExcludes, autoMemoryEnabled) - MCP servers from `claude mcp list`, .mcp.json, and ~/.claude.json (including disabledMcpServers) - Every script a hook points to Then ask me to run these in a fresh session and paste the results, because they hold real usage and cost numbers you cannot get from the files: - `/context all` (the Memory files list and the per-item token breakdown) - `/skill-doctor` (context cost and how often each skill actually runs) - `/doctor` findings, if I have run it recently If I skip this, keep going and mark every usage-based finding "no usage data". Show me the inventory table and the total always-loaded estimate. Then continue. ## Step 2: Test every always-loaded instruction Split each always-loaded file into single instructions. Run each one through these ten checks. 1. Deletion test. Would removing this cause Claude to make a mistake? If Claude already does it by default (write clean code, use clear names, follow the normal conventions of the language, handle errors, be concise), it fails. 2. Derivable. Could Claude learn this by reading the code, package files, README, or git history? Folder trees, dependency lists, architecture overviews, and file-by-file descriptions usually fail. Pitfalls, the reasons behind decisions, commands Claude cannot guess, and conventions that differ from the defaults usually pass. Those are the most valuable lines in the file, so protect them. 3. Stale. Does it mention files, scripts, commands, paths, tools, model names, versions, people, prices, URLs, or dates that changed or no longer exist? Check the filesystem, run `--help`, or grep. Never guess. 4. Written for an older model. Flag scaffolding that newer Claude models no longer need or over-apply. - Shouting spread across many lines, such as CRITICAL, YOU MUST, NEVER EVER, ALWAYS in caps, whole sentences in caps. Emphasis on one line that Claude kept skipping is fine. Emphasis on many lines means none of it stands out, and newer models can overreact to it. - Over-prompting like "if in doubt, use X" or "use this tool whenever possible", which causes overtriggering. - Leftover self-check lines like "double-check every step" or "verify your work before finishing". Recent models check their own work, and these lines cause over-checking. - Forced progress updates like "summarize progress every few steps". - Workarounds for a specific old bug or model habit ("Claude keeps doing X, so..."). Propose a calm, plain rewrite, or a cut if the behavior is now the default. 5. Duplicate. The same instruction in two or more places (parent and child CLAUDE.md, CLAUDE.md and a rules file, CLAUDE.md and auto memory, CLAUDE.md and a skill, CLAUDE.local.md and a checked-in file). Pick one home. 6. Contradiction. Two instructions that cannot both be followed, including soft ones ("add comments where helpful" against "no comments") and user-level rules that clash with project rules. When rules conflict, Claude may pick one arbitrarily, so these get fixed first. 7. Wrong home. - Must happen every time with zero exceptions (format, lint, run tests before a commit, block a command or folder): belongs in a hook or a permission deny rule. A CLAUDE.md sentence is guidance, not enforcement. - A multi-step procedure, or something needed only sometimes: belongs in a skill. - Only relevant to certain files or folders: belongs in .claude/rules/ with `paths:` frontmatter, or a nested CLAUDE.md. - A personal preference sitting in a checked-in team file: belongs in CLAUDE.local.md or ~/.claude/CLAUDE.md. 8. Vague. Could anyone check whether it was followed? "Be careful with the database" fails. "Never run migrations against production, use `npm run migrate:staging`" passes. Rewrite it concrete, or cut it. 9. Cost. A long block that loads every session for a need that comes up rarely. Move it somewhere that loads on demand. 10. Size. Flag any CLAUDE.md over 200 lines, since longer files lower how well Claude follows them. Flag an auto memory index near or past 200 lines or 25KB. Give each instruction one verdict. The options are KEEP, CUT, MERGE, REWRITE, or MOVE. ## Step 3: Skills and subagents For every skill: - Overlap. Two skills whose descriptions would fire on the same request. Merge them or sharpen both descriptions. - Description quality. Key use case first, clear trigger phrases. The description plus `when_to_use` gets cut off at 1,536 characters in the skill listing, so flag long descriptions that bury the use case. - Side effects. A skill that deploys, sends, publishes, pays, commits, or deletes without `disable-model-invocation: true` gets flagged, so only I can trigger it. This also removes its description from context. - Stale references in the body, such as scripts, paths, tools, MCP servers, or other skills that no longer exist. Verify each one. - Size. A SKILL.md over about 500 lines should move reference material into supporting files. - Usage. Use the /skill-doctor numbers if I pasted them. For skills never used, ask me which of these I want: a) keep as is b) set to "name-only" (Claude sees the name only) or "user-invocable-only" (hidden from Claude, I can still type it) c) set to "off" (hidden everywhere) d) delete Visibility can be set in the /skills menu (highlight, press Space, Esc to save) or with `skillOverrides` in settings. Plugin skills ignore `skillOverrides` and are managed through /plugin. Not used recently does not always mean useless, so ask. - Conflicts with CLAUDE.md or with another skill. For every subagent, look for overlapping descriptions, stale tool lists, and instructions that contradict CLAUDE.md. ## Step 4: Auto memory Read MEMORY.md and every topic file in the memory folder. - Wrong or outdated facts, including anything that contradicts the current code or CLAUDE.md. - One-off notes from a single task that will never matter again. - Duplicates of CLAUDE.md content. - Entries that belong in CLAUDE.md instead, because the whole team needs them. - An index near or past 200 lines or 25KB. - Old entries. Use the `modified` date in frontmatter when it exists. - Anything that pushes a behavior I never asked for. Flag it as a possible bad memory. This is often why Claude keeps doing something odd. Group uncertain memory entries into short yes or no questions. Never guess about facts about me. ## Step 5: The rest of the setup Permissions. Read every scope, including .claude/settings.local.json, where each "Yes, and don't ask again" click for a command or domain gets saved. - One-off approvals that piled up, like a single file path, a temp folder, one exact commit message, a one-time script. - Rules that are too broad, like `Bash(*)`, interpreters like `Bash(python *)` or `Bash(node *)`, `Bash(rm *)`, `Bash(curl *)`, and `Bash(git *)`, which allows every git command including push and reset. Propose narrower rules such as `Bash(git log *)`. - A `*` placed before the subcommand, like `Bash(git * main)`, which matches far more than it looks like. - Rules for tools or MCP servers that are no longer installed. - Rules that never take effect because a deny or ask rule matches first. The order is deny, then ask, then allow, and specificity does not change it. - Duplicates across user, project, and local scopes. Hooks: - The script each hook calls exists and is executable (`test -x`). - The matcher still matches real tool names, including renamed tools and removed MCP servers. - Slow hooks, from /doctor findings or timings I share. - The same hook defined in more than one scope or plugin. - A hook that already enforces something CLAUDE.md also says. Cut the CLAUDE.md line. MCP servers: - Failing or disconnected servers in `claude mcp list`. - Servers I have not used lately. Offer two choices. Toggle it off in /mcp, which keeps its configuration, or `claude mcp remove <name>`. - Servers that duplicate a command line tool Claude already uses well, for example a GitHub server when `gh` is installed. - The same server defined in more than one scope. - Servers with broad write access to important accounts. Flag for review. - Note that Claude Code defers loading MCP tool definitions by default, so an idle server usually costs less context than it used to. Base cost findings on /context or /doctor numbers, not assumptions. Plugins: installed but unused, and plugins whose skills or hooks duplicate something I already have. ## Step 6: The report Use exactly this structure. ### Setup health Three to five bullets. The biggest problems, plus the always-loaded token estimate now and after the proposed changes. ### Contradictions (fix these first) Table: # | Instruction A (file:line, quoted) | Instruction B (file:line, quoted) | Which to keep and why ### Recommended changes Table: # | Verdict | Where (file:line) | Current text (short quote) | Proposed change | Why | Tokens saved | Risk (low, medium, high) Put them in this order. CUT, MERGE, MOVE, REWRITE, then Skills, Memory, Permissions, Hooks, MCP, Plugins. Number items continuously across the whole report so I can approve by number. ### Keeping as is A short list of what passed and why it earns its place, so I can trust the audit. ### Deletion tests to run For every medium or high risk cut, the exact task to try in a fresh session to prove nothing breaks. For a bigger baseline, suggest `claude --safe-mode`, which starts a session with CLAUDE.md, skills, plugins, hooks, MCP servers, and auto memory all turned off, so I can see what the model does on its own. ### Questions for me Numbered, yes or no wherever possible. End with this line. Reply with the numbers to apply (for example "apply 1, 3, 5-9"), "apply all low risk", or "none". ## Step 7: Apply (only after I approve) 1. Back up first. Copy every file you will change to ~/.claude/maintenance-backups/<today's date>/, keeping the folder structure. Tell me the path. 2. Apply only the numbers I approved, with the smallest possible edit. 3. For medium or high risk cuts in a CLAUDE.md file, wrap the lines in an HTML comment block (<!-- ... -->) instead of deleting them. Claude Code strips block comments before loading CLAUDE.md, so it acts like a deletion and is easy to undo. Comments inside code blocks are not stripped, so never use this trick inside a code block. 4. After editing any JSON settings file, validate it (for example `python3 -m json.tool <file>`). A broken settings file breaks the setup. 5. Show before and after for every rewrite. 6. Finish with lines and estimated tokens before and after, the backup path, the deletion tests to run, and a reminder to open a fresh session and run /context and /doctor to confirm. Suggest the next audit date, which is three to four weeks from today, or right after the next Claude model release, whichever comes first. 7. Offer to add a dated entry to ~/.claude/maintenance-log.md listing what changed and why, so the next audit knows which rules were cut on purpose and does not suggest adding them back. ## Do not - Rewrite whole files in your own style. - Cut pitfalls, reasons, or project-specific conventions just to hit a line count. - Add new rules during the audit, unless one short rule replaces two that contradicted each other. - Delete a skill, MCP server, hook, or memory I said to keep. - Touch anything outside my Claude Code setup files.