Claude Code Md Maintainer

CLAUDE.md Maintainer

Audit and maintain CLAUDE.md files across any repository. Ensures they function as Claude Code memory (not user documentation).

Core Principle

CLAUDE.md is Claude's memory, not a README. Every line loads into context, so keep it lean and actionable.

Algorithm

Phase 1: Plan (read-only)

1. Discover existing memory files:

   • ./CLAUDE.md or ./.claude/CLAUDE.md
   • ./CLAUDE.local.md
   • Nested **/CLAUDE.md
   • .claude/rules/**/*.md

2. Validate each against invariants (see docs/invariants.md)

3. Audit verbosity:

   • Count total lines (warn if > 300, suggest if > 60)
   • Detect verbose patterns (see docs/verbose-patterns.md)
   • Flag linter-duplicating instructions
   • Identify content that should move to agent_docs/
   • Report actionable findings with line numbers

4. Identify module roots (see docs/directory-heuristics.md)

5. Output proposed changes:

   • Files to update (with change summary)
   • Files to create
   • Ambiguous cases requiring human decision

Phase 2: Apply (with confirmation)

Only after user confirms:

1. Update existing files
2. Create missing files from templates
3. Report final state

Init Algorithm

For /bluera-base:claude-code-md init - creates new CLAUDE.md from scratch.

Detection Priority

Check files in order (stop at first match):

package.json → JavaScript/TypeScript
Cargo.toml   → Rust
pyproject.toml → Python
go.mod       → Go

Lockfile → Package Manager

Script Extraction

JavaScript/TypeScript:

jq -r '.scripts | keys[]' package.json 2>/dev/null | head -10

Python (pyproject.toml):

grep -A 20 '^\[project.scripts\]' pyproject.toml | grep '=' | cut -d'=' -f1 | tr -d ' "'

Rust/Go: Use standard commands (cargo build/test, go build/test).

Generated Structure

includes/CLAUDE-BASE.md

---

## Package Manager

**Use `{PM}`** - All scripts: `{PM} run <script>`

---

## Scripts

{SCRIPTS - grouped by category if many}

---

## CI/CD

{Only if .github/workflows/ or .gitlab-ci.yml exists}

---

Design Principles

1. Auto-detect over ask - Only interview when ambiguous
2. < 60 lines target - Start lean, user expands later
3. Never overwrite - Check for existing CLAUDE.md first
4. @include always - Start with CLAUDE-BASE.md reference

Learn Algorithm

For /bluera-base:claude-code-md learn - adds learnings to marker-delimited regions.

Marker Format

## Auto-Learned (bluera-base)
<!-- AUTO:bluera-base:learned -->
- Learning 1
- Learning 2
<!-- END:bluera-base:learned -->

Algorithm Steps

1. Determine target file:

   • Default: CLAUDE.local.md (personal, gitignored)
   • With --shared: CLAUDE.md (team-shared)

2. Read target file (or create if missing)

3. Find markers:

   • Start: <!-- AUTO:bluera-base:learned -->
   • End: <!-- END:bluera-base:learned -->

4. If markers missing: Insert at end of file:

   
   ---
   
   ## Auto-Learned (bluera-base)
   <!-- AUTO:bluera-base:learned -->
   <!-- END:bluera-base:learned -->
   

5. Parse existing learnings between markers into list

6. Dedupe check:

   • Normalize: trim whitespace, lowercase
   • If learning already exists (fuzzy match), skip with message

7. Secrets check (CRITICAL):

   • Regex: api[_-]?key|token|password|secret|-----BEGIN|AWS_|GITHUB_TOKEN|ANTHROPIC_API
   • If match: REJECT with warning, do NOT write

8. Hard cap check:

   • Max 50 lines in auto-managed section
   • If exceeded: warn user, suggest pruning old learnings

9. Insert learning as new bullet point

10. Write file using Edit tool (replace marker region only)

Secrets Denylist

api[_-]?key
token
password
secret
-----BEGIN
AWS_
GITHUB_TOKEN
ANTHROPIC_API_KEY
OPENAI_API_KEY
private[_-]?key
credential

Example Implementation

# Pseudo-code for the Edit operation
OLD_CONTENT="<!-- AUTO:bluera-base:learned -->
- Old learning 1
<!-- END:bluera-base:learned -->"

NEW_CONTENT="<!-- AUTO:bluera-base:learned -->
- Old learning 1
- New learning here
<!-- END:bluera-base:learned -->"

User Control Modes

Control auto-learning behavior via /bluera-base:config command:

/bluera-base:config enable auto-learn    # Opt-in to learning observation
/bluera-base:config set .autoLearn.mode auto  # Change mode

Configuration stored in .bluera/bluera-base/config.json:

{
  "autoLearn": {
    "enabled": false,    // opt-in by default
    "mode": "suggest",   // suggest | auto
    "threshold": 3,      // occurrences before suggesting
    "target": "local"    // local | shared
  }
}

Session signals are tracked in .bluera/bluera-base/state/session-signals.json (ephemeral, gitignored). Commands with ≥threshold occurrences trigger learning suggestions.

References

• Audit Templates: ${CLAUDE_PLUGIN_ROOT}/skills/claude-code-md-maintainer/templates/

  • root_CLAUDE.md - Root project memory
  • module_CLAUDE.md - Directory-scoped memory
  • local_CLAUDE.local.md - Personal notes

• Init Templates: ${CLAUDE_PLUGIN_ROOT}/skills/claude-code-md-maintainer/templates/init/

  • js-ts.md - JavaScript/TypeScript projects
  • python.md - Python projects
  • rust.md - Rust projects
  • go.md - Go projects
  • ci-github.md - GitHub Actions CI section
  • ci-gitlab.md - GitLab CI section

• Validation rules: ${CLAUDE_PLUGIN_ROOT}/skills/claude-code-md-maintainer/docs/invariants.md

• Directory detection: ${CLAUDE_PLUGIN_ROOT}/skills/claude-code-md-maintainer/docs/directory-heuristics.md

• Reliability guidance: ${CLAUDE_PLUGIN_ROOT}/skills/claude-code-md-maintainer/docs/reliability.md

• Scope decision guide: ${CLAUDE_PLUGIN_ROOT}/skills/claude-code-md-maintainer/docs/scope-guide.md

Key Rules

1. Never duplicate - Module CLAUDE.md should not repeat root rules
2. Prefer rules files - Move topic-specific rules to .claude/rules/<topic>.md
3. Use paths: scoping - Rules files can use paths: frontmatter
4. Hard cap - If > 25 modules, summarize at bucket level, defer individuals

Output Format

Report these sections:

• Memory files found
• Files to create
• Files to update (with diff summary)
• Rules files to create/update
• Verbosity report (if issues detected)
• Follow-ups (ambiguous items)

Verbosity Report

When line count exceeds targets or verbose patterns detected, include:

Line Count:

• CLAUDE.md: 142 lines (target: < 60, hard limit: < 300)

Verbose Patterns Detected: