105 lines
4.9 KiB
Markdown
105 lines
4.9 KiB
Markdown
# 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. |