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.

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
.claude/commands/                — Slash commands for session workflow

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.