Skip to content

Claude MD management plugin

  • Date: 2026-04-21
  • Status: Accepted
  • Tags: tooling

Context

Multiple repositories now have CLAUDE.md files with project-specific instructions. As the number of repos grows, keeping these files consistent, correctly structured, and properly inheriting from global config becomes a maintenance burden. The existing claude-md-wrangler script handles bulk operations but lacks linting and inheritance resolution.

Decision

Install the claude-md-management plugin on the work laptop. It provides CLAUDE.md linting, merging across config levels, and inheritance resolution. Complements the claude-md-wrangler script — the script handles bulk file operations while the plugin handles structural validation and conflict detection.

Alternatives Considered

Option Why Rejected
claude-md-wrangler script only Handles bulk ops but no linting or inheritance resolution
Manual CLAUDE.md maintenance Does not scale across many repos
Shared CLAUDE.md template with no validation Templates drift; no enforcement mechanism

Consequences

Positive:

  • Structural issues in CLAUDE.md caught before they cause session behavior problems
  • Clear visibility into the full instruction inheritance chain
  • Complements existing claude-md-wrangler script

Negative / Trade-offs:

  • Two tools for CLAUDE.md management — need clear division of responsibility
  • Community plugin — may lag behind CLAUDE.md format changes

Ongoing obligations:

  • ✅ Validated 2026-04-21 — claude-md-management:revise-claude-md and claude-md-management:claude-md-improver skills confirmed active on work laptop
  • Division of responsibility: claude-md-wrangler script handles bulk file operations (copy, sync, template propagation across repos); claude-md-management plugin handles per-session structural validation, linting, and inheritance resolution. Use the script for bulk ops, the plugin for quality gates.