8.7 KiB

Raw Blame History

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

Copy this entire folder to your new project
Put your legacy code into legacy/ (read-only, never modified)
Adapt CLAUDE.md to your project (update the goal description)
Adapt docs/A_discovery/task.md to your specific discovery goals
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
/project:new-user-story — Create a new user story 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.

Batch-Modus: Mehrere Tasks automatisiert abarbeiten

Wenn die nächsten Schritte bereits geplant sind (z.B. Discovery-Waves, User Stories schreiben, Module analysieren), erspart der Batch-Modus den manuellen Session-Zyklus:

Vorher:  session-start → Aufgabe → session-end → clear → commit → repeat (pro Task)
Nachher: /project:run-batch → N Tasks laufen durch → Review → fertig

So funktioniert's

Starten: /project:run-batch oder natürlichsprachlich ("Arbeite die nächsten 3 Tasks ab").

Claude liest die task.md der aktiven Phase, zeigt die offenen Tasks, und fragt nach:

Welche Tasks? — alle, bestimmte Nummern, oder eine Gruppe
Checkpoint-Modus? — wann soll für Review pausiert werden

Checkpoint-Modi

Modus	Verhalten	Wann verwenden
`after-each` (Standard)	Pause nach jeder Gruppe, Zusammenfassung zeigen	Neue/unsichere Tasks
`after-batch:N`	N Gruppen durchlaufen, dann pausieren	"Mach 3, dann schau ich"
`at-end`	Alles durchlaufen, am Ende Review	Gut verstandene Tasks

Parallelisierung

Tasks sind in task.md unter ###-Überschriften gruppiert:

Tasks unter dem gleichen Heading laufen parallel (z.B. 3 Module gleichzeitig)
Zwischen Gruppen wird sequenziell gearbeitet (Wave 2 wartet auf Wave 1)

Was passiert im Hintergrund

Pro Task wird ein Subagent mit frischem Context gestartet
Jeder Subagent schreibt sein Ergebnis in eine eigene Output-Datei
Die Output-Dateien sind sofort in VS Code sichtbar — du kannst sie während des Laufs beobachten
Am Checkpoint zeigt Claude eine Tabelle mit Status und Zusammenfassung pro Task
Du entscheidest: weiter, stopp, oder zeig mir [datei]
Am Ende: Claude aktualisiert task.md, status.md und decisions-log.md und schlägt einen Commit vor

Sicherheitsregeln

Phasengrenze ist ein harter Stopp — der Batch läuft nie automatisch in die nächste Phase
Fehlgeschlagene Tasks bleiben offen ([ ]) und werden beim Checkpoint gemeldet
Ohne bestätigte Parameter startet kein Batch — Claude fragt immer nach

Beispiel

Du: /project:run-batch

Claude: Ich sehe 5 offene Tasks in Phase 1 — Discovery:
  1. [ ] structure-map.md (Wave 1)
  2. [ ] entry-points.md (Wave 2)
  3. [ ] Module: auth (Wave 3)
  4. [ ] Module: invoicing (Wave 3)
  5. [ ] Module: reporting (Wave 3)

  Welche Tasks? (alle / Nummern / Gruppe)
  Checkpoint-Modus? (after-each / after-batch:N / at-end)

Du: alle, after-each

Claude: [dispatcht Wave 1 → Checkpoint → Wave 2 → Checkpoint → Wave 3 parallel → Checkpoint]
Claude: Batch abgeschlossen. 5/5 erfolgreich. Soll ich committen?

Permissions

Damit der Batch nicht an Berechtigungsdialogen hängen bleibt, müssen die nötigen Tools in .claude/settings.json freigeschaltet sein. Das Projekt enthält bereits eine passende Konfiguration. Falls nicht vorhanden:

{ "permissions": { "allow": ["Read", "Write", "Edit", "Glob", "Grep", "Agent"] } }

User Stories

User stories are created during Phase 2 (Planning) and bridge the gap between "what the legacy system does" (Discovery) and "what we build" (Integration).

Creating stories: Use /project:new-user-story. Claude will ask for the role, the desired capability, and the business value — then generate a story file from template.

Where they live: docs/B_planning/user-stories/US-NNN-short-title.md — one file per story.

Numbering: Stories are numbered sequentially (US-001, US-002, ...). Claude picks the next free number automatically.

Each story includes:

The story itself (As a ... I want ... so that ...)
Testable acceptance criteria
Traceability back to a discovery document or legacy function
Explicit scope boundaries (what does NOT belong to this story)
Priority using MoSCoW (Must / Should / Could / Won't)

When to write them: After Discovery has produced enough understanding of the legacy system. Don't write stories before you know what the system actually does — that's what Phase 1 is for.

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
  batch-orchestration.md         — Rules for batch/subagent execution
.claude/commands/                — Slash commands for session workflow
  run-batch.md                   — Batch orchestrator command
.claude/settings.json            — Project-level tool permissions

Remakrs

How to use it?

Der Ablauf wäre:

Session 1: Legacy-Code ins Projekt, CLAUDE.md anpassen, task.md der Phase 1 mit ersten DoD-Punkten füllen
Session 2-N: Discovery-Arbeit — je ein DoD-Punkt pro Session (oder mehrere kleine)
Wenn alle DoD-Punkte ✅: Phasenwechsel zu Phase 2

Das Session-Protokoll ist kein Extra-Overhead für spezielle Anlässe — es ist der Standardrhythmus für jede Sitzung. Es stellt sicher, dass:

Der Kontext vom letzten Mal wiederhergestellt wird
Am Ende nichts verloren geht
Entscheidungen dokumentiert werden

Die task.md muss auch nicht in Session 1 perfekt sein. Du kannst mit 2-3 DoD-Punkten starten und sie in späteren Sessions erweitern, wenn du den Legacy-Code besser verstehst.

Kurz: Jede Interaktion = eine Session. Das Protokoll ist der Herzschlag des Frameworks, nicht ein Sonderereignis.

Wann Session-Workflow, wann Batch?

Situation	Empfehlung
Erkundend, unklar was als nächstes kommt	`/project:session-start` → manuell arbeiten
Nächste Schritte klar, Tasks in task.md definiert	`/project:run-batch`
Ein einzelner, klar definierter Task	Manuell oder Batch mit einem Item
Viele unabhängige Module analysieren	Batch mit Parallelisierung

Der Batch-Modus ergänzt den Session-Workflow — er ersetzt ihn nicht grundsätzlich. Für explorative Arbeit bleibt der manuelle Zyklus der richtige Ansatz.

8.7 KiB Raw Blame History