claude-md-optimizer

CLAUDE.md Optimizer Skill

Generiert evidenzbasierte Verbesserungsvorschlaege fuer CLAUDE.md anhand von Log-Mining-Ergebnissen und Pattern-Katalog. Aendert CLAUDE.md NIEMALS automatisch.

Trigger-Phrases

• "claude.md optimieren", "claude.md verbessern", "instructions verbessern"
• "optimize claude.md", "improve agent instructions"
• "was sollte in die claude.md", "welche regeln fehlen"

Assumptions

• Log-Miner wurde bereits ausgefuehrt und .agent-memory/log-analysis/latest.json existiert
• CLAUDE.md liegt im Projekt-Root (Standard-Pfad fuer Claude Code)
• Pattern-Katalog liegt in .agent-memory/patterns.json (optional, wird von pattern-extractor erstellt)
• Der Skill generiert NUR Vorschlaege — keine automatischen Aenderungen

Konfiguration

{
  "claude_md_optimizer": {
    "claude_md_path": "CLAUDE.md",
    "min_occurrences_for_rule": 3,
    "max_suggestions": 10,
    "output_path": ".agent-memory/CLAUDE_IMPROVEMENTS.md"
  }
}

Prozedur

Schritt 1: Inputs sammeln

Lies die folgenden Dateien (in dieser Reihenfolge):

1. Aktuelle CLAUDE.md — Volltext lesen, Struktur verstehen
2. Log-Mining-Report — .agent-memory/log-analysis/latest.json
3. Pattern-Katalog (falls vorhanden) — .agent-memory/patterns.json
4. Fehler-Historie (falls vorhanden) — .agent-memory/errors.json

Falls eine Datei nicht existiert, ueberspringe sie mit Warnung. Mindestens CLAUDE.md und der Log-Mining-Report muessen vorhanden sein.

Schritt 2: Fehlermuster priorisieren

Erstelle eine Rangliste der Fehlermuster nach:

Score = occurrences * severity_weight * recency_factor

severity_weight:
  user_frustration: 3.0    # Hoechste Prio — User war unzufrieden
  reverted_changes: 2.5    # Arbeit wurde verworfen
  code_errors: 2.0         # Wiederholte technische Fehler
  architecture_misunderstandings: 2.0
  tool_misuse: 1.5
  repeated_questions: 1.0

recency_factor:
  letzte 24h: 2.0
  letzte 3 Tage: 1.5
  letzte 7 Tage: 1.0
  aelter: 0.5

Nur Muster mit occurrences >= min_occurrences_for_rule (Default: 3) qualifizieren sich fuer einen Vorschlag.

Schritt 3: Vorschlaege generieren

Fuer jedes qualifizierte Muster:

1. Problem identifizieren: Was geht schief? (1 Satz)
2. Evidenz sammeln: 2-3 rohe Zitate aus den Logs (gekuerzt auf max 200 Zeichen)
3. CLAUDE.md-Regel formulieren: Konkrete Instruktion, die das Problem verhindert
4. Platzierung bestimmen: Wo in der CLAUDE.md soll die Regel stehen? (existierende Sektion oder neue Sektion)
5. Diff-Preview erstellen: Zeige den konkreten Textblock, der eingefuegt/geaendert werden soll

Format fuer jeden Vorschlag:

### Vorschlag {N}: {KURZTITEL}

**Problem:** {BESCHREIBUNG}
**Haeufigkeit:** {COUNT}x in den letzten {DAYS} Tagen
**Score:** {SCORE}

**Evidenz aus Logs:**
> {ZITAT_1}
> {ZITAT_2}

**Vorgeschlagene CLAUDE.md-Aenderung:**

Sektion: `{SEKTIONSNAME}`
Aktion: {INSERT_AFTER / REPLACE / NEW_SECTION}

```diff
+ {NEUE_ZEILEN}

Begruendung: {WARUM_HILFT_DAS}

### Schritt 4: Konflikt-Check

Pruefe ob vorgeschlagene Regeln:
- Sich gegenseitig widersprechen
- Mit bestehenden CLAUDE.md-Regeln kollidieren
- Zu spezifisch sind (nur fuer einen Einzelfall relevant)
- Zu generisch sind (wuerden normales Verhalten einschraenken)

Markiere problematische Vorschlaege mit `[WARNUNG: ...]`.

### Schritt 5: Output generieren

Schreibe `.agent-memory/CLAUDE_IMPROVEMENTS.md`:

```markdown
# CLAUDE.md Verbesserungsvorschlaege

Generiert: {TIMESTAMP}
Basierend auf: Log-Mining Report {REPORT_TIMESTAMP}
Analysierte Fehlermuster: {TOTAL_PATTERNS}
Qualifizierte Vorschlaege: {QUALIFIED_COUNT}

## Zusammenfassung

{2-3 Saetze: Was sind die Hauptprobleme? Was wuerde sich aendern?}

## Vorschlaege (nach Score sortiert)

{VORSCHLAG_1}
{VORSCHLAG_2}
...

## Nicht qualifizierte Muster

Diese Muster traten weniger als {MIN_OCCURRENCES}x auf — noch nicht genug Evidenz:

| Muster | Vorkommen | Kategorie |
|--------|-----------|-----------|
| ...    | ...       | ...       |

## Naechste Schritte

- [ ] Vorschlaege reviewen
- [ ] Gewuenschte Aenderungen mit `--apply` uebernehmen
- [ ] Nach 1 Woche erneut log-miner + optimizer laufen lassen

Schritt 6: Apply-Modus (nur mit --apply Flag)

Wird NUR ausgefuehrt wenn der User explizit --apply angibt oder bestaetigt.

1. Erstelle Backup: cp CLAUDE.md CLAUDE.md.backup.{TIMESTAMP}
2. Lies CLAUDE_IMPROVEMENTS.md
3. Fuer jeden Vorschlag den der User akzeptiert hat (markiert mit [x]):
   • Fuehre die beschriebene Aenderung durch
   • Logge die Aenderung in .agent-memory/claude_md_changelog.json
4. Zeige finales Diff: diff CLAUDE.md.backup.{TIMESTAMP} CLAUDE.md

Changelog-Format:

{
  "changes": [
    {
      "timestamp": "2026-03-24T12:00:00",
      "suggestion_id": 1,
      "action": "insert",
      "section": "Code-Konventionen",
      "content_added": "...",
      "evidence_count": 5,
      "source_report": "report_20260324_120000.json"
    }
  ]
}

Error-Handling

Fehlerfall	Reaktion
CLAUDE.md nicht gefunden	Abbruch mit Hinweis: "Kein CLAUDE.md im Projekt-Root gefunden"
Log-Mining-Report fehlt	Abbruch mit Hinweis: "Fuehre zuerst log-miner aus"
Keine Muster qualifizieren sich	Report mit "Keine Vorschlaege — zu wenig Evidenz" generieren
CLAUDE.md ist leer	Vorschlaege als initiale Struktur formulieren
--apply ohne vorherige Vorschlaege	Abbruch: "Generiere zuerst Vorschlaege ohne --apply"
Backup-Erstellung fehlgeschlagen	Abbruch: "Kann kein Backup erstellen — Aenderung abgelehnt"

Abgrenzung

• pattern-extractor: Extrahiert generische Patterns aus errors.json. Claude-md-optimizer nutzt diese als EINE Quelle, generiert aber spezifisch CLAUDE.md-Regeln.
• context-keeper: Dokumentiert Architektur-Entscheidungen. Claude-md-optimizer generiert Verhaltens-Instruktionen fuer den Agenten.
• iteration-logger: Erfasst Einzelereignisse. Claude-md-optimizer aggregiert und priorisiert.