claudemd-optimizer

A comprehensive instruction file management system for Claude Code. Audits, restructures,
optimises, and synchronises CLAUDE.md files, rules, auto memory, and settings across
multiple environments.

Quick Start

When invoked, present this menu:

╔══════════════════════════════════════════════════════════════════╗
║                      claudemd-optimizer                          ║
║           Instruction file management for Claude Code            ║
╚══════════════════════════════════════════════════════════════════╝

 1. AUDIT        Full diagnostic of all instruction files across project,
                 user, and auto memory scopes. Inventories every file,
                 measures line counts, identifies topics, assesses priority
                 saturation, checks reference integrity, and flags issues.

 2. EXTRACT      Splits an oversized CLAUDE.md into focused rule files.
                 Classifies sections as core/safety/domain/personal/stale.
                 Produces plan for review before executing. Always backs up.

 3. SCOPE        Reviews existing rule files and recommends paths: frontmatter.
                 Cross-references against project file structure. Protects
                 safety-critical rules from scoping.

 4. VALIDATE     Cross-scope conflict and integrity checker. Contradictions,
                 duplicates, staleness, coverage gaps, hierarchy violations,
                 build command drift, style conflicts, env var references.

 5. DEPS         Builds instruction dependency graph. Maps every reference
                 (files, commands, env vars, MCP servers, globs). Produces
                 reverse index for staleness prevention after refactors.

 6. REPORT       Comprehensive health report with all recommendations and
                 impact assessments (context savings, adherence improvement,
                 risk reduction, effort tier). No cap on recommendations.

 7. ROLLBACK     Restore instruction files to a previous state. Lists all
                 backup snapshots. Creates safety backup before restoring.
                 Supports --dry-run.

 8. CONFIG       Manage skill settings: backup retention, environment
                 registry, sync preferences.

 9. SMART RUN    [Recommended first use] Audit → findings → relevant actions.
                 Adapts to what it finds. The guided path.

10. SYNC         Compare and synchronise across environments (local, server,
                 API). Sub-modes: diff, push, pull. Git for tracked files,
                 rsync for non-git. Auto memory excluded.

Scope: --project | --user | --memory | (no flag = all)
Sync:  diff | push | pull | --env <n> | --all

If the user provides a number or mode name, execute that mode.
If invoked bare (/claudemd), run SMART RUN (option 9).

---

Core Concepts

The 7-Level Instruction Hierarchy

Claude Code loads instructions from most specific to least specific:

1. Managed Policy (/Library/Application Support/ClaudeCode/CLAUDE.md) — org-wide, cannot exclude
2. User Instructions (~/.claude/CLAUDE.md) — personal, all projects
3. User Rules (~/.claude/rules/*.md) — personal, optionally path-scoped
4. Project CLAUDE.md (./CLAUDE.md or ./.claude/CLAUDE.md) — team-shared via git
5. Project Rules (./.claude/rules/*.md) — path-specific, team-shared
6. Local Instructions (./CLAUDE.local.md) — personal, gitignored
7. Auto Memory (~/.claude/projects/<project>/memory/) — Claude-written, machine-local

Key Mechanics

• CLAUDE.md target: under 200 lines. Longer files consume more context and reduce adherence.
• Subdirectory CLAUDE.md files load lazily when Claude reads files in that directory. These often grow unnoticed — audit them.
• Rules with paths: frontmatter load only when Claude reads matching files. Rules without paths: load every session.
• Rules fire on Read, not Edit. Safety-critical rules must NOT use paths:.
• Auto memory caps at 200 lines in MEMORY.md. Overflow goes to topic files.
• @import syntax in CLAUDE.md expands at load time. Max 5 hops.
• Conflicting instructions are resolved arbitrarily. Eliminate conflicts.

Safety Classification

Rules containing safety keywords (never, always, critical, forbidden, doctrine, non-negotiable,
mandatory, must not, destructive, production, credential, secret) should NOT be path-scoped.
They must load every session. When in doubt, keep a rule universal.

---

Mode Reference

For each mode, read the corresponding reference file before executing:

Mode	Reference File	Read Before Executing
AUDIT	references/audit-logic.md	Always
EXTRACT	references/extract-logic.md	Always
SCOPE	references/scope-logic.md	Always
VALIDATE	references/validate-logic.md	Always
DEPS	references/deps-logic.md	Always
REPORT	references/report-templates.md	Always
SYNC	references/sync-logic.md	Always
ROLLBACK	(inline below)	N/A
CONFIG	(inline below)	N/A
SMART RUN	Runs AUDIT then offers modes	Read audit-logic.md

---

ROLLBACK (inline — no separate reference needed)

1. List backups: ls -la .claude/claudemd-optimizer/backups/
2. Read target manifest: cat .claude/claudemd-optimizer/backups/<timestamp>/manifest.json
3. Create safety backup of CURRENT state first
4. Restore: copy backed-up files over current files
5. Delete files that were created by the operation being rolled back
6. Report what changed

For --dry-run: do steps 1-2, then show what WOULD change without writing.

Retention: configured in config.json (default 10). Prune oldest on each new backup.

---

CONFIG (inline)

Config file: .claude/claudemd-optimizer/config.json

If it doesn't exist, create it with defaults:

{
  "retention": 10,
  "environments": {
    "local": {
      "type": "claude-code",
      "ssh_host": null,
      "project_path": null,
      "user_claude_path": null,
      "account": "claude-max",
      "is_primary": true
    }
  },
  "sync": {
    "auto_backup_on_receive": true,
    "exclude_auto_memory": true,
    "git_auto_commit": true,
    "git_commit_prefix": "claudemd-optimizer",
    "primary_source": "local"
  }
}

Guide user through adding environments interactively.

---

Backup Protocol

Every write operation MUST create a backup first. No exceptions.

1. Create timestamped directory: .claude/claudemd-optimizer/backups/<ISO-timestamp>/
2. Copy every file that will be modified or deleted into the backup
3. Write manifest.json recording: timestamp, mode, scope, reason, files backed up, files to be created, pre/post metrics
4. Only THEN proceed with modifications
5. After modifications, update manifest with actual post metrics

For user-level files, backups go to ~/.claude/claudemd-optimizer/backups/.

---

Critical Rules

1. Never modify settings files. Read them, flag issues, recommend fixes — but never write to settings.json or settings.local.json.
2. Never read .env values. Only check that referenced keys exist. Never log, display, or process env var values.
3. Never modify auto memory. Read it, assess it, flag promotion candidates — but never write to MEMORY.md or topic files. Memory is Claude's domain.
4. Always confirm before writing. Present the plan, wait for explicit approval, then execute.
5. Safety rules stay universal. Never add paths: frontmatter to rules containing safety keywords without explicit human confirmation.
6. Backup before everything. Every write operation creates a timestamped backup with manifest. No exceptions.
7. Auto memory is never synced. It is machine-local by design. Syncing would corrupt machine-specific learnings.