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
• /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

1. Pro Task wird ein Subagent mit frischem Context gestartet
2. Jeder Subagent schreibt sein Ergebnis in eine eigene Output-Datei
3. Die Output-Dateien sind sofort in VS Code sichtbar — du kannst sie während des Laufs beobachten
4. Am Checkpoint zeigt Claude eine Tabelle mit Status und Zusammenfassung pro Task
5. Du entscheidest: weiter, stopp, oder zeig mir [datei]
6. 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:

1. Session 1: Legacy-Code ins Projekt, CLAUDE.md anpassen, task.md der Phase 1 mit ersten DoD-Punkten füllen
2. Session 2-N: Discovery-Arbeit — je ein DoD-Punkt pro Session (oder mehrere kleine)
3. 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.