diff --git a/.claude/commands/decision.md b/.claude/commands/decision.md new file mode 100644 index 0000000..52cdd0f --- /dev/null +++ b/.claude/commands/decision.md @@ -0,0 +1,11 @@ +Erstelle einen neuen Eintrag im Entscheidungsprotokoll. + +1. Lies docs/templates/decisions-log-entry.md als Vorlage +2. Frage den User nach folgenden Informationen (sofern nicht schon aus dem Kontext bekannt): + - Was wurde entschieden? + - Warum stand diese Entscheidung an? + - Welche Alternativen wurden verworfen und warum? + - Ist die Entscheidung endgültig oder revisierbar? +3. Fülle das Template mit den Antworten aus +4. Füge den Eintrag OBEN in docs/B_planning/decisions-log.md ein (nach dem Header) +5. Bestehende Einträge werden NIEMALS verändert diff --git a/.claude/commands/new-discovery.md b/.claude/commands/new-discovery.md new file mode 100644 index 0000000..dec46cd --- /dev/null +++ b/.claude/commands/new-discovery.md @@ -0,0 +1,9 @@ +Erstelle ein neues Discovery-Dokument. + +1. Lies docs/templates/discovery-document.md als Vorlage +2. Frage den User (sofern nicht aus dem Kontext bekannt): + - Welchen Aspekt des Legacy-Systems dokumentiert dieses Dokument? + - Wie soll die Datei heißen? (Vorschlag: kebab-case, z.B. domain-model.md) +3. Erstelle die Datei in docs/A_discovery/ basierend auf dem Template +4. Setze das Erstelldatum auf heute +5. Trage einen Querverweis in status.md ein, dass ein neues Dokument angelegt wurde diff --git a/.claude/commands/phase-transition.md b/.claude/commands/phase-transition.md new file mode 100644 index 0000000..da96a4a --- /dev/null +++ b/.claude/commands/phase-transition.md @@ -0,0 +1,28 @@ +Führe einen Phasenwechsel durch. + +## Voraussetzungen prüfen +1. Lies task.md der aktuellen Phase +2. Prüfe: Sind ALLE Definition-of-Done-Punkte mit [x] markiert? +3. Falls nein: Liste die offenen Punkte und frage den User, ob trotzdem gewechselt werden soll + +## Phasenwechsel durchführen +1. Erstelle einen Eintrag in docs/B_planning/decisions-log.md: + - Typ: Prozess + - Entscheidung: "Phase N abgeschlossen, Wechsel zu Phase N+1" + - Offene Punkte aus der alten Phase dokumentieren + +2. Neue Phase vorbereiten: + - Falls task.md und status.md für die neue Phase noch nicht existieren: + Erstelle sie basierend auf docs/templates/status.md + - task.md der neuen Phase muss ein Ziel und Definition-of-Done-Punkte enthalten + - Frage den User nach dem Ziel und den erwarteten Ergebnissen der neuen Phase + +3. CLAUDE.md aktualisieren: + - "Aktuelle Phase" auf die neue Phase setzen + - "Arbeitsverzeichnis" auf das neue Phasenverzeichnis ändern + - "Schreibrechte" anpassen (neue Phase + decisions-log) + +4. Zusammenfassung zeigen: + - Was wurde in der abgeschlossenen Phase erreicht? + - Was ist das Ziel der neuen Phase? + - Was sind die ersten Schritte? diff --git a/.claude/commands/session-end.md b/.claude/commands/session-end.md new file mode 100644 index 0000000..f0e8973 --- /dev/null +++ b/.claude/commands/session-end.md @@ -0,0 +1,23 @@ +Führe den Session-Abschluss durch. Lies zuerst CLAUDE.md um die aktive Phase zu bestimmen, dann: + +1. **status.md aktualisieren** — Lies die aktuelle status.md der aktiven Phase und aktualisiere sie: + - Erledigtes markieren mit [x] + - Aktuellen Stand in 2-3 Sätzen beschreiben + - Nächste Schritte auflisten + - Offene Fragen / Blocker notieren + - Bewusst Ausgeklammertes dokumentieren + +2. **Entscheidungen protokollieren** — Falls in dieser Session Entscheidungen getroffen wurden: + - Erstelle für jede Entscheidung einen Eintrag nach docs/templates/decisions-log-entry.md + - Füge ihn oben in docs/B_planning/decisions-log.md ein + +3. **task.md aktualisieren** — Markiere abgeschlossene Definition-of-Done-Punkte mit [x] + +4. **Zusammenfassung** — Zeige dem User: + - Was wurde in dieser Session erreicht? + - Was sind die nächsten Schritte? + - Welche offenen Fragen bleiben? + +5. **Phase prüfen** — Falls alle DoD-Punkte in task.md erledigt sind: + - Weise den User darauf hin, dass ein Phasenwechsel ansteht + - Verweise auf den /project:phase-transition Command diff --git a/.claude/commands/session-start.md b/.claude/commands/session-start.md new file mode 100644 index 0000000..8215aa7 --- /dev/null +++ b/.claude/commands/session-start.md @@ -0,0 +1,18 @@ +Lies folgende Dateien in dieser Reihenfolge, ohne sofort zu handeln: +1. CLAUDE.md +2. task.md der aktiven Phase (siehe "Aktiver Scope" in CLAUDE.md) +3. status.md der aktiven Phase +4. docs/B_planning/decisions-log.md (nur die letzten 5 Einträge) + +Fasse danach in 3-5 Sätzen zusammen: +- Was ist das Gesamtziel des Projekts? +- Was ist das Ziel dieser Phase? +- Was wurde zuletzt erreicht, und wo stehen wir gerade? +- Was sind bekannte offene Fragen oder Blocker? + +Frage dann den User: +> Was ist dein Ziel für diese Session? +> Was ist explizit nicht in Scope heute? +> Welches konkrete Ergebnis (Datei, Dokument, Funktion) soll am Ende stehen? + +Warte auf die Antworten, bevor du mit der inhaltlichen Arbeit beginnst. diff --git a/.claude/settings.local.json b/.claude/settings.local.json index 8a39111..8681318 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -1,7 +1,9 @@ { "permissions": { "allow": [ - "Skill(review)" + "Skill(review)", + "Bash(mkdir:*)", + "Bash(mv:*)" ] } } diff --git a/CLAUDE.md b/CLAUDE.md index 110313e..e50557f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -13,20 +13,65 @@ Der rote Faden war durchgehend: Struktur vor Inhalt. Das Gerüst steht, bevor di Liegt in: legacy/ Regel: Keine Datei in legacy/ wird verändert. Nur lesen. +## Regeln +@rules/framework-constraints.md +@rules/session-protocol.md + ## Aktiver Scope Aktuelle Phase: 1 — Discovery Arbeitsverzeichnis: docs/A_discovery/ -Schreibrechte: docs/A_discovery/**, docs/B_planning/decisions-log.md, - phase-1/status.md -Keine Änderungen an: src/**, legacy/** +Schreibrechte: docs/A_discovery/**, docs/B_planning/decisions-log.md +Keine Änderungen an: src/**, legacy/**, docs/templates/** ## Konventionen - Entscheidungen immer in decisions-log.md eintragen (oben anfügen, nie editieren) - Jede Session endet mit aktuellem status.md - Offene Fragen explizit notieren, nicht stillschweigend überspringen +## Verzeichnisstruktur +``` +legacy/ — Legacy-Code (read-only) +docs/ + A_discovery/ — Phase 1: Analyse des Legacy-Codes + task.md — Aufgabendefinition & Definition of Done + status.md — Aktueller Stand (wird jede Session aktualisiert) + B_planning/ — Phase 2: Architektur & Entscheidungen + task.md — Aufgabendefinition & Definition of Done + status.md — Aktueller Stand + decisions-log.md — Entscheidungsprotokoll (append-only) + C_integration/ — Phase 3: Umsetzung + task.md — Aufgabendefinition & Definition of Done + status.md — Aktueller Stand + templates/ — Vorlagen (read-only, nie direkt editieren) +rules/ — Regeln für Claude (automatisch geladen) +.claude/commands/ — Projekt-Commands (/project:...) +``` + +## Workflow-Commands +- `/project:session-start` — Session beginnen (Kontext laden, Session-Ziel klären) +- `/project:session-end` — Session abschließen (Status, Entscheidungen, offene Fragen) +- `/project:decision` — Neue Entscheidung im Log protokollieren +- `/project:new-discovery` — Neues Discovery-Dokument aus Template anlegen +- `/project:phase-transition` — Phasenwechsel durchführen (DoD prüfen, CLAUDE.md aktualisieren) + ## Session-Einstieg +Nutze `/project:session-start` oder manuell: 1. Diese Datei lesen -2. phase-N/task.md lesen -3. phase-N/status.md lesen -4. Kurze Zusammenfassung, dann auf Bestätigung warten \ No newline at end of file +2. task.md der aktiven Phase lesen +3. status.md der aktiven Phase lesen +4. docs/B_planning/decisions-log.md lesen (letzte 5 Einträge) +5. Kurze Zusammenfassung, dann Session-Ziel mit dem User klären +6. Auf Bestätigung warten + +## Session-Ende +Nutze `/project:session-end` oder manuell: +1. status.md der aktiven Phase aktualisieren +2. Entscheidungen in docs/B_planning/decisions-log.md eintragen +3. In task.md abgeschlossene Punkte markieren +4. Offene Fragen oder nächste Schritte explizit notieren + +## Phasenwechsel +Ein Phasenwechsel erfolgt über `/project:phase-transition` wenn: +- Alle Definition-of-Done-Punkte in task.md der aktuellen Phase [x] sind +- Der User den Wechsel bestätigt +Dabei wird: Decision-Log-Eintrag erstellt, neue Phase vorbereitet, CLAUDE.md aktualisiert. diff --git a/README.md b/README.md new file mode 100644 index 0000000..5045ec8 --- /dev/null +++ b/README.md @@ -0,0 +1,63 @@ +# Reverse-Engineering Framework for Claude Code + +A project scaffold for multi-session reverse-engineering projects with Claude Code. +Keeps context coherent across sessions by storing everything in files — not in chat history. + +## Quick Start + +1. Copy this entire folder to your new project +2. Put your legacy code into `legacy/` (read-only, never modified) +3. Adapt `CLAUDE.md` to your project (update the goal description) +4. Adapt `docs/A_discovery/task.md` to your specific discovery goals +5. Start your first session with `/project:session-start` + +## How It Works + +The project has three phases, each in its own directory: + +| Phase | Directory | Purpose | +|-------|-----------|---------| +| 1 — Discovery | `docs/A_discovery/` | Understand the legacy system | +| 2 — Planning | `docs/B_planning/` | Design the new system | +| 3 — Integration | `docs/C_integration/` | Build and migrate | + +Each phase has a `task.md` (what needs to be done) and a `status.md` (where we are). +Decisions are tracked in `docs/B_planning/decisions-log.md` across all phases. + +## Session Workflow + +**Start a session:** `/project:session-start` +- Claude reads the project state, summarizes it, and asks you for your session goal. + +**During a session:** Work normally. Use these as needed: +- `/project:decision` — Record an architectural or process decision +- `/project:new-discovery` — Create a new discovery document from template + +**End a session:** `/project:session-end` +- Claude updates status, logs decisions, marks completed tasks, and lists open questions. + +**Switch phases:** `/project:phase-transition` +- Only when all Definition-of-Done items in the current phase are checked off. + +## Key Principles + +- **Project lives in files, not sessions.** Every insight, decision, and status update is written down. +- **Structure before content.** The scaffold exists before any analysis begins. +- **Legacy code is read-only.** The `legacy/` folder is never modified. +- **Templates are read-only.** `docs/templates/` contains structural references, not working documents. +- **Decisions are append-only.** Once logged, entries in `decisions-log.md` are never edited. + +## File Overview + +``` +CLAUDE.md — Project memory (Claude reads this first) +README.md — You are here +legacy/ — Legacy code (read-only) +docs/ + A_discovery/ — Phase 1 working directory + B_planning/ — Phase 2 working directory + decisions log + C_integration/ — Phase 3 working directory + templates/ — Document templates (read-only reference) +rules/ — Constraints Claude follows automatically +.claude/commands/ — Slash commands for session workflow +``` diff --git a/docs/A_discovery/status.md b/docs/A_discovery/status.md new file mode 100644 index 0000000..b6a156e --- /dev/null +++ b/docs/A_discovery/status.md @@ -0,0 +1,20 @@ +# Status — Phase 1: Discovery + +Letzte Aktualisierung: 2026-03-20 +Session-Nr.: 0 + +## Erledigtes +- [x] Projektgerüst erstellt (Verzeichnisstruktur, Templates, CLAUDE.md) + +## Aktueller Stand +Framework steht. Noch kein Legacy-Code analysiert. Bereit für erste Discovery-Session. + +## Nächste Schritte +1. Legacy-Code in legacy/ ablegen +2. Erste Analyse: domain-model.md beginnen + +## Offene Fragen / Blocker +- Legacy-Code muss noch ins Projekt kopiert werden + +## Nicht angefasst (bewusst ausgeklammert) +- Keine Punkte verschoben diff --git a/docs/C_integration/phase-1/task.md b/docs/A_discovery/task.md similarity index 99% rename from docs/C_integration/phase-1/task.md rename to docs/A_discovery/task.md index 9438a23..6dedcf8 100644 --- a/docs/C_integration/phase-1/task.md +++ b/docs/A_discovery/task.md @@ -14,5 +14,3 @@ die Capabilities und die KI-Kandidaten dokumentiert sind. - Architekturentscheidungen für das neue System - Embedding- oder KI-Strategie - Irgendwelcher neuer Code -``` - diff --git a/docs/B_planning/decisions-log.md b/docs/B_planning/decisions-log.md new file mode 100644 index 0000000..eca7ba3 --- /dev/null +++ b/docs/B_planning/decisions-log.md @@ -0,0 +1,4 @@ +# Decisions Log + + + diff --git a/docs/B_planning/status.md b/docs/B_planning/status.md new file mode 100644 index 0000000..3f3eb2f --- /dev/null +++ b/docs/B_planning/status.md @@ -0,0 +1,20 @@ +# Status — Phase 2: Planung + +Letzte Aktualisierung: — +Session-Nr.: 0 + +## Erledigtes +— Phase noch nicht gestartet — + +## Aktueller Stand +Wartet auf Abschluss von Phase 1 (Discovery). + +## Nächste Schritte +1. Phase 1 abschließen +2. Discovery-Ergebnisse als Input für Architekturentscheidungen nutzen + +## Offene Fragen / Blocker +- Abhängig von Phase 1 + +## Nicht angefasst (bewusst ausgeklammert) +- Noch keine diff --git a/docs/B_planning/task.md b/docs/B_planning/task.md new file mode 100644 index 0000000..13b89b9 --- /dev/null +++ b/docs/B_planning/task.md @@ -0,0 +1,15 @@ +# Phase 2 — Planung + +## Ziel +Auf Basis der Discovery-Ergebnisse die Architektur, Technologie-Entscheidungen +und den Umsetzungsplan für das neue System definieren. + +## Ergebnisse (Definition of Done) +- [ ] docs/B_planning/architecture.md — Systemarchitektur, Komponenten, Schnittstellen +- [ ] docs/B_planning/tech-stack.md — Technologie-Entscheidungen mit Begründung +- [ ] docs/B_planning/migration-strategy.md — Wie wird vom alten zum neuen System migriert? +- [ ] docs/B_planning/implementation-plan.md — Priorisierte Arbeitspakete + +## Nicht in Scope +- Implementierung von Code +- KI-Modell-Training oder -Evaluation diff --git a/docs/C_integration/phase-1/status.md b/docs/C_integration/.gitkeep similarity index 100% rename from docs/C_integration/phase-1/status.md rename to docs/C_integration/.gitkeep diff --git a/docs/C_integration/status.md b/docs/C_integration/status.md new file mode 100644 index 0000000..c015319 --- /dev/null +++ b/docs/C_integration/status.md @@ -0,0 +1,20 @@ +# Status — Phase 3: Umsetzung + +Letzte Aktualisierung: — +Session-Nr.: 0 + +## Erledigtes +— Phase noch nicht gestartet — + +## Aktueller Stand +Wartet auf Abschluss von Phase 2 (Planung). + +## Nächste Schritte +1. Phase 2 abschließen +2. Implementierung gemäß Umsetzungsplan beginnen + +## Offene Fragen / Blocker +- Abhängig von Phase 2 + +## Nicht angefasst (bewusst ausgeklammert) +- Noch keine diff --git a/docs/C_integration/task.md b/docs/C_integration/task.md new file mode 100644 index 0000000..8d44c9c --- /dev/null +++ b/docs/C_integration/task.md @@ -0,0 +1,14 @@ +# Phase 3 — Umsetzung + +## Ziel +Das neue System auf Basis der Planungsergebnisse implementieren, +den Legacy-Code ablösen und die Migration durchführen. + +## Ergebnisse (Definition of Done) +- [ ] Neues System implementiert gemäß Architektur aus Phase 2 +- [ ] Datenmigration durchgeführt und verifiziert +- [ ] Legacy-Funktionalität vollständig abgedeckt +- [ ] Dokumentation aktualisiert + +## Nicht in Scope +- Wird in Phase 2 definiert diff --git a/docs/templates/discovery-document.md b/docs/templates/discovery-document.md index 3838d6c..4a14145 100644 --- a/docs/templates/discovery-document.md +++ b/docs/templates/discovery-document.md @@ -12,14 +12,14 @@ Was dokumentiert dieses Dokument, und warum ist es relevant für das Projekt? ## Methode -Wie wurde dieses Wissen gewonnen? +Wie wurde dieses Wissen gewonnen? (z.B. Schema-Analyse, Code-Lektüre, UI-Flows, Validierungsregeln) --- ## Befunde -[Hier der eigentliche Inhalt — struktur je nach Dokumenttyp:] +[Hier der eigentliche Inhalt — Struktur je nach Dokumenttyp:] ### [Abschnitt 1] ... @@ -30,13 +30,13 @@ Wie wurde dieses Wissen gewonnen? --- ## Unsicherheiten -Dinge, die unklar geblieben sind oder nur vermutet werden. +Dinge, die unklar geblieben sind oder nur vermutet werden. - [ ] [Unsicherheit] → Klärung nötig durch: _______________ ## Querverweise Welche anderen Discovery-Dokumente oder Entscheidungen hängen damit zusammen? -- docs/discovery/___ -- docs/planning/decisions-log.md → Eintrag vom ___ +- docs/A_discovery/___ +- docs/B_planning/decisions-log.md → Eintrag vom ___ ## Nächste Schritte -Was muss auf Basis dieses Dokuments als nächstes passieren? \ No newline at end of file +Was muss auf Basis dieses Dokuments als nächstes passieren? diff --git a/docs/templates/session_end_static.md b/docs/templates/session_end_static.md index 7bf1874..a008201 100644 --- a/docs/templates/session_end_static.md +++ b/docs/templates/session_end_static.md @@ -1,5 +1,5 @@ Am Ende der Session, bevor du aufhörst: -- Aktualisiere phase-N/status.md mit dem aktuellen Stand -- Trage getroffene Entscheidungen in decisions-log.md ein -- Markiere in task.md, was abgeschlossen ist -- Notiere offene Fragen oder nächste Schritte explizit \ No newline at end of file +1. Aktualisiere docs/A_discovery/status.md (bzw. aktive Phase) mit dem aktuellen Stand +2. Trage getroffene Entscheidungen in docs/B_planning/decisions-log.md ein +3. Markiere in task.md der aktiven Phase, was abgeschlossen ist +4. Notiere offene Fragen oder nächste Schritte explizit diff --git a/docs/templates/session_goal_dynamic.md b/docs/templates/session_goal_dynamic.md deleted file mode 100644 index 2715e01..0000000 --- a/docs/templates/session_goal_dynamic.md +++ /dev/null @@ -1,3 +0,0 @@ -Das Ziel dieser Session ist: [konkrete Aufgabe]. -Nicht in Scope heute: [was du explizit ausklammern willst]. -Ergebnis am Ende soll sein: [konkretes Artefakt — Datei, Funktion, Dokument]. \ No newline at end of file diff --git a/docs/templates/session_start_static.md b/docs/templates/session_start_static.md index b0d9fd2..1a46e7d 100644 --- a/docs/templates/session_start_static.md +++ b/docs/templates/session_start_static.md @@ -1,9 +1,8 @@ Lies zunächst diese Dateien in dieser Reihenfolge, ohne sofort zu handeln: 1. CLAUDE.md -2. docs/planning/session-plan.md -3. docs/planning/decisions-log.md (nur die letzten 5 Einträge) -4. phase-N/task.md -5. phase-N/status.md +2. docs/A_discovery/task.md (bzw. aktive Phase) +3. docs/A_discovery/status.md (bzw. aktive Phase) +4. docs/B_planning/decisions-log.md (nur die letzten 5 Einträge) Fasse danach in 3-5 Sätzen zusammen: - Was ist das Gesamtziel des Projekts? @@ -11,4 +10,4 @@ Fasse danach in 3-5 Sätzen zusammen: - Was wurde zuletzt erreicht, und wo stehen wir gerade? - Was sind bekannte offene Fragen oder Blocker? -Warte auf meine Bestätigung, bevor du anfängst. \ No newline at end of file +Warte auf meine Bestätigung, bevor du anfängst. diff --git a/docs/templates/status.md b/docs/templates/status.md index cf0958a..cb9e254 100644 --- a/docs/templates/status.md +++ b/docs/templates/status.md @@ -1,11 +1,11 @@ # Status — Phase N: [Phasenname] -Letzte Aktualisierung: YYYY-MM-DD +Letzte Aktualisierung: YYYY-MM-DD Session-Nr.: N ## Erledigtes -- [ ] Aufgabe A → erledigt, Ergebnis: [Datei/Befund] -- [ ] Aufgabe B → erledigt, Ergebnis: [Datei/Befund] +- [x] Aufgabe A → erledigt, Ergebnis: [Datei/Befund] +- [x] Aufgabe B → erledigt, Ergebnis: [Datei/Befund] ## Aktueller Stand [2-3 Sätze: Wo stehen wir? Was ist der Zwischenstand?] @@ -18,4 +18,4 @@ Session-Nr.: N - [Frage oder Problem, das nicht in dieser Session lösbar war] ## Nicht angefasst (bewusst ausgeklammert) -- [Was in Scope war, aber verschoben wurde — und warum] \ No newline at end of file +- [Was in Scope war, aber verschoben wurde — und warum] diff --git a/legacy/.gitkeep b/legacy/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/rules/framework-constraints.md b/rules/framework-constraints.md new file mode 100644 index 0000000..09882b1 --- /dev/null +++ b/rules/framework-constraints.md @@ -0,0 +1,7 @@ +- Never write to legacy/ — read-only, no exceptions +- Never write to docs/templates/ — read-only, use as reference only +- Only write to the active phase directory defined in CLAUDE.md "Aktiver Scope" +- docs/B_planning/decisions-log.md is always writable (append-only, never edit existing entries) +- Before any file write: verify target path is within allowed scope +- CLAUDE.md is only modified during phase transitions +- Never delete or rename existing discovery documents or decision entries diff --git a/rules/session-protocol.md b/rules/session-protocol.md new file mode 100644 index 0000000..5100a14 --- /dev/null +++ b/rules/session-protocol.md @@ -0,0 +1,7 @@ +- Every session starts with the session-start protocol — no content work before context is restored +- After reading context files: summarize state, then ask for the user's session goal +- No content work before user confirms the session goal +- Uncertainties are never silently skipped — log them in status.md or open-questions.md +- At the end of a session: always ask "Soll ich den Session-Abschluss machen?" before closing +- Use docs/templates/ as structural reference when creating new documents +- When all Definition-of-Done items are complete: proactively inform the user that a phase transition is possible