refactoring framework
This commit is contained in:
beo3000
parent
bf439383e8
commit
95df4d65e2
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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?
|
||||
|
|
@ -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
|
||||
|
|
@ -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.
|
||||
|
|
@ -1,7 +1,9 @@
|
|||
{
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"Skill(review)"
|
||||
"Skill(review)",
|
||||
"Bash(mkdir:*)",
|
||||
"Bash(mv:*)"
|
||||
]
|
||||
}
|
||||
}
|
||||
|
|
|
|||
57
CLAUDE.md
57
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
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
```
|
||||
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
# Decisions Log
|
||||
|
||||
<!-- Neue Einträge oben einfügen. Bestehende Einträge nie editieren. -->
|
||||
<!-- Vorlage: docs/templates/decisions-log-entry.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
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -19,7 +19,7 @@ Wie wurde dieses Wissen gewonnen?
|
|||
|
||||
## Befunde
|
||||
|
||||
[Hier der eigentliche Inhalt — struktur je nach Dokumenttyp:]
|
||||
[Hier der eigentliche Inhalt — Struktur je nach Dokumenttyp:]
|
||||
|
||||
### [Abschnitt 1]
|
||||
...
|
||||
|
|
@ -35,8 +35,8 @@ Dinge, die unklar geblieben sind oder nur vermutet werden.
|
|||
|
||||
## 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?
|
||||
|
|
@ -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
|
||||
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
|
||||
|
|
|
|||
|
|
@ -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].
|
||||
|
|
@ -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?
|
||||
|
|
|
|||
|
|
@ -4,8 +4,8 @@ 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?]
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
Loading…
Reference in New Issue