Merge pull request #402 from raifdmueller/fix/brownfield-i18n

fix: add German translations for brownfield workflow

Author: rdmueller

docs/brownfield-workflow.de.adoc

@@ -0,0 +1,170 @@
+= Workflow-Anpassung für Brownfield-Projekte
+Ralf D. Müller
+2026-03-31
+:toc:
+:toc-placement: preamble
+
+== Einleitung
+
+Du hast den link:#/workflow[Greenfield-Workflow] gemeistert.
+Jetzt willst du ihn auf eine bestehende Codebasis anwenden.
+
+Die Grundprinzipien bleiben gleich: kleine Schritte, hohe Autonomie, Fehlerkorrektur-Schleifen.
+Aber Brownfield-Projekte bringen eine Herausforderung, die Greenfield-Projekte nicht haben: *das System existiert bereits*.
+Man kann nicht bei null anfangen.
+Man muss verstehen, was da ist, bevor man etwas ändert.
+
+Dieses Dokument beschreibt, wie man eine bestehende Codebasis in den Spec-Driven-Workflow überführt.
+Die zentrale Erkenntnis stammt aus Simon Martinellis https://unifiedprocess.ai/[AI Unified Process]: *Man muss nicht das gesamte System spezifizieren*.
+Man arbeitet einen Bounded Context nach dem anderen.
+Die Spec-Abdeckung wächst inkrementell, Feature für Feature.
+
+== Das Brownfield-Paradox
+
+Bei Greenfield-Projekten schreibt man zuerst die Spec, dann folgt der Code.
+Bei Brownfield-Projekten existiert der Code bereits -- aber die Spec oft nicht.
+Das System *ist* die Spezifikation, nur kann sie niemand lesen.
+
+Die Versuchung ist groß, das gesamte System vor jeder Änderung in Dokumentation zu überführen.
+Das ist Big Upfront Documentation, und es scheitert aus denselben Gründen wie Big Upfront Design.
+
+Stattdessen: Nur den Bounded Context spezifizieren, den man gerade ändern will, und auch nur so viel, wie für eine sichere Änderung nötig ist.
+
+== Phase 0: Bounded Context eingrenzen
+
+Vor jeder Code-Änderung den Bereich identifizieren, der geändert werden soll.
+
+Ein Bounded Context ist ein zusammenhängender Ausschnitt des Systems mit klaren Grenzen.
+Das kann ein Modul sein, ein Service, ein Feature-Bereich oder ein Bildschirm.
+Die Grenzen sollten klein genug sein, dass man den Kontext in einer einzigen Session verstehen kann.
+
+⚓ link:#/anchor/domain-driven-design[Domain-Driven Design] nutzen, um die Kontextgrenzen zu identifizieren.
+Die KI kann dabei helfen: auf den Code zeigen und nach Bounded Contexts und deren Schnittstellen fragen.
+
+.Prompt
+----
+Analyze the codebase in src/. Identify bounded contexts using Domain-Driven Design.
+For each context, list: name, responsibility, key entities, interfaces to other contexts.
+Present as a table.
+----
+
+Einen Bounded Context zum Starten auswählen.
+Einen wählen, der klein, gut isoliert ist und eine anstehende Änderungsanforderung hat.
+
+== Phase 0.5: Sicherheitsnetz aufbauen
+
+Vor jeder Änderung braucht man zwei Dinge: Verständnis und Tests.
+
+=== Bestehendes Verhalten als Use Cases extrahieren
+
+Die KI den Code im Bounded Context lesen lassen und extrahieren, was das System aktuell tut.
+Das Ergebnis sind Use Cases, die das *bestehende* Verhalten beschreiben -- nicht was man bauen will, sondern was bereits da ist.
+
+.Prompt
+----
+Read the code in [bounded context path]. Extract the existing behavior as Use Cases.
+For each Use Case: ID, Trigger, Actors, Preconditions, Main Flow, Alternative Flows, Postconditions, Business Rules.
+Save as docs/specs/use-cases-[context-name].adoc.
+----
+
+Die extrahierten Use Cases gegen das laufende System prüfen.
+Die KI kann implizites Verhalten übersehen oder Code falsch interpretieren.
+Das ist der eine Schritt, bei dem Domänenwissen unersetzlich ist.
+
+=== Basis-Tests aufbauen
+
+Tests schreiben, die das bestehende Verhalten verifizieren.
+Diese Tests sind das Sicherheitsnetz: Wenn eine Änderung etwas kaputt macht, fangen die Tests es ab.
+
+.Prompt
+----
+Based on the Use Cases in docs/specs/use-cases-[context-name].adoc, write tests that verify the current behavior.
+Use TDD, London School. Each test references its Use Case ID for traceability.
+Do not change any production code. Only add tests.
+----
+
+Tests ausführen.
+Jeder Test muss gegen den aktuellen Code bestehen.
+Wenn ein Test fehlschlägt, war der extrahierte Use Case falsch -- Use Case korrigieren, dann Test korrigieren.
+
+[IMPORTANT]
+====
+Basis-Tests nicht überspringen.
+Ohne sie kann man nicht unterscheiden zwischen "meine Änderung hat etwas kaputt gemacht" und "es war schon vorher kaputt".
+Das ist die geschlossene Schleife, die Brownfield-Änderungen sicher macht.
+====
+
+== Phase 1-12: Der Standard-Workflow
+
+Sobald Use Cases und Basis-Tests für den Bounded Context vorhanden sind, greift der normale Workflow.
+
+* *Neue Features* bekommen neue Use Cases, neue Akzeptanzkriterien und neue Tests -- genau wie bei Greenfield.
+* *Bug Fixes* beginnen damit, den verletzten Use Case zu identifizieren, dann folgt der TDD-Bug-Fix-Loop (Schritt 12).
+* *Refactoring* ist durch die Basis-Tests abgesichert. Solange die Tests grün bleiben, ist das Refactoring sicher.
+
+Der einzige Unterschied: Die arc42-Dokumentation ist vielleicht anfangs unvollständig.
+Das ist in Ordnung.
+Die Architektur-Abschnitte ausfüllen, während man das System kennenlernt.
+Nach ein paar Bounded Contexts deckt die Architekturdokumentation die relevanten Teile ab.
+
+== Inkrementelle Erweiterung
+
+Nach dem ersten Bounded Context den nächsten auswählen.
+Jeder eingeführte Kontext erweitert die Spec-Abdeckung des Systems.
+
+Mit der Zeit ergibt sich ein Muster:
+
+[cols="1,3"]
+|===
+|Iteration |Abdeckung
+
+|Erster Kontext
+|Ein Feature-Bereich hat Use Cases, Tests und Architekturdokumentation.
+
+|3-5 Kontexte
+|Der Kern des Systems ist dokumentiert. Querschnittsthemen werden sichtbar.
+
+|10+ Kontexte
+|Die meisten Änderungen passieren in Bereichen mit bestehenden Specs. Neue Arbeit fühlt sich an wie Greenfield.
+|===
+
+100% Abdeckung ist nicht nötig.
+Das Ziel ist, die Bereiche abzudecken, die sich am häufigsten ändern.
+Stabiler Code, den niemand anfasst, braucht keine Specs.
+
+== Prompt Cheat Sheet: Brownfield
+
+[cols="1,3,2"]
+|===
+|Phase |Prompt |Anker
+
+|Scope
+|`Analyze the codebase in [path]. Identify bounded contexts using DDD. List name, responsibility, entities, interfaces.`
+|link:#/anchor/domain-driven-design[DDD]
+
+|Reverse-Engineering
+|`Read the code in [path]. Extract existing behavior as Use Cases with Trigger, Main Flow, Alternative Flows, Postconditions, Business Rules.`
+|{empty}--
+
+|Basis-Tests
+|`Write tests for the Use Cases in [spec file]. Each test references its Use Case ID. Do not change production code.`
+|link:#/anchor/tdd-london-school[TDD London] / link:#/anchor/tdd-chicago-school[Chicago]
+
+|Weiter
+|Ab hier dem link:#/workflow[Standard-Workflow] ab Schritt 3 (PRD) oder Schritt 8 (Implementierung) folgen, je nachdem ob neue Features oder Bugs bearbeitet werden.
+|{empty}--
+|===
+
+== Wann dieser Ansatz nicht passt
+
+Dieser Workflow setzt voraus, dass man das bestehende System *weiterentwickeln* will.
+Wer einen kompletten Neubau plant, nimmt stattdessen den Greenfield-Workflow.
+
+Er setzt auch voraus, dass der bestehende Code lauffähig ist.
+Wenn das System nicht gebaut oder gestartet werden kann, liegt ein anderes Problem vor -- das zuerst lösen.
+
+== Weiterführende Literatur
+
+* Simon Martinelli, https://unifiedprocess.ai/[AI Unified Process] -- der Bounded-Context-Ansatz für Spec-Driven Development in bestehenden Systemen.
+* Eric Evans, https://www.domainlanguage.com/ddd/[Domain-Driven Design] -- das grundlegende Werk zu Bounded Contexts und strategischem Design.
+* Michael Feathers, _Working Effectively with Legacy Code_ -- Techniken zum Aufbau von Testabdeckung in Systemen ohne Tests.

docs/spec-driven-workflow.de.adoc

@@ -33,7 +33,7 @@ Ein Klick auf einen Anker führt zur vollständigen Definition auf der Semantic
 [IMPORTANT]
 ====
 Dieser Workflow ist für Greenfield-Projekte konzipiert, die von Grund auf mit KI-Unterstützung gebaut werden.
-Die Anpassung an Legacy-Codebasen erfordert zusätzliche Überlegungen (Reverse Engineering der bestehenden Architektur, Aufbau von Testabdeckung, inkrementelle Migration), die hier noch nicht behandelt werden.
+Für bestehende Codebasen siehe link:#/brownfield[Workflow-Anpassung für Brownfield-Projekte].
 ====
 
 == Das Grundprinzip: Kleine Schritte, hohe Autonomie
@@ -220,12 +220,27 @@ Aus dem PRD eine vollständige Spezifikation generieren:
 [source]
 ----
 Create a detailed specification from the PRD. Include:
-- Use Cases
+- Use Cases (Trigger, Main Flow, Alternative Flows, Postconditions, Business Rules)
 - Activity Diagrams for all flows (not just the happy path)
 - Acceptance criteria in Gherkin format
 Save as .adoc files in src/docs/specs/.
 ----
 
+Jeder Use Case muss fünf Elemente definieren:
+
+* *Trigger*: Das spezifische Ereignis, das den Use Case auslöst ("Benutzer klickt auf Absenden", "System empfängt Webhook").
+Ohne Trigger weiß weder die KI noch ein Tester, wann der Use Case beginnt.
+* *Hauptablauf (Main Flow)*: Die nummerierten Schritte des Happy Path, jeder beschreibt beobachtbares Systemverhalten.
+* *Alternativabläufe (Alternative Flows)*: Benannte Verzweigungen (A1, A2, ...) für Fehlerbehandlung, Validierungsfehler und Randfälle.
+* *Nachbedingungen (Postconditions)*: Der garantierte Systemzustand nach erfolgreicher Ausführung.
+Nachbedingungen sind das, was die Tests prüfen.
+* *Geschäftsregeln (Business Rules)*: Nummerierte Regeln (BR-001, BR-002, ...) für Validierungslogik, Berechnungen oder Domäneninvarianten.
+Geschäftsregeln machen implizites Wissen explizit.
+Ohne sie erfindet die KI eigene Validierungslogik -- oder lässt sie komplett weg.
+
+Diese Struktur folgt dem Use-Case-Format von Alistair Cockburn, das LLMs zuverlässig erkennen.
+Je präziser der Use Case, desto weniger muss die KI bei der Implementierung raten.
+
 ⚓ link:#/anchor/gherkin[*Gherkin*] (Given/When/Then) liefert Akzeptanzkriterien, die sowohl für Menschen lesbar als auch maschinell testbar sind.
 Diese Kriterien werden später die Grundlage für TDD.
 
@@ -318,14 +333,15 @@ Mit wachsendem Projekt das Backlog regelmäßig groomen und nach neuen Erkenntni
 Create a feature branch for this EPIC.
 Select the next logical issue from the backlog (respect dependencies).
 Analyze it and document your analysis as a comment on the issue.
-Implement it using TDD (choose London or Chicago School as appropriate). Commit when done.
+Implement it using TDD (choose London or Chicago School as appropriate).
+Each test references its Use Case ID for traceability. Commit when done.
 Check if the spec or architecture docs need updating.
 ----
 
 Für jedes Issue:
 
 . *Analysieren*: Die KI untersucht das Issue, prüft zugehörige Specs und Architektur, checkt Abhängigkeiten zu anderen Issues und postet eine Analyse als Kommentar
-. *Mit TDD implementieren*: Die KI schreibt zuerst Tests, dann die Implementierung
+. *Mit TDD implementieren*: Die KI schreibt zuerst Tests, dann die Implementierung. Jeder Test referenziert die Use-Case-ID, die er verifiziert (z.B. `UC-01`). Die KI wählt den passenden Mechanismus für die Sprache -- Annotationen in Java, Kommentare in JavaScript, Docstrings in Python. Das schafft Rückverfolgbarkeit von Tests zu Spezifikationen ohne zusätzliches Tooling.
 . *Committen*: Nach Implementierung und grünen Tests committen mit Referenz auf die Issue-Nummer
 . *Docs prüfen*: Fragen, ob Spezifikation oder Architekturdokumentation basierend auf den Erkenntnissen aktualisiert werden muss
 
@@ -433,8 +449,7 @@ Das Backlog häufiger groomen, je größer das Projekt wird.
 
 *Legacy-Codebasen*::
 Dieser Workflow geht von einem Neustart aus.
-Die Anpassung an bestehenden Code erfordert zusätzliche Schritte: Reverse Engineering der bestehenden Architektur in arc42, Aufbau einer Basis-Testabdeckung und inkrementelle Migration.
-Erste Schritte: die KI arc42-Dokumentation aus der bestehenden Codebasis generieren lassen, dann Tests für die Bereiche hinzufügen, die geändert werden sollen.
+Siehe link:#/brownfield[Workflow-Anpassung für Brownfield-Projekte] für eine Anleitung zu Reverse Engineering, Basis-Testabdeckung und inkrementeller Migration mit Bounded Contexts.
 
 *Frontend / HTML-Anwendungen*::
 Dieser Workflow funktioniert gut für Backend-Code, CLIs und Bibliotheken, wo Compiler und TDD starke Fehlerkorrektur bieten.
@@ -462,7 +477,7 @@ Die wichtigsten Einzeiler pro Phase mit den Semantic Anchors, die sie aktivieren
 |link:#/anchor/plain-english-strunk-white[Strunk & White]
 
 |Spezifikation
-|`Create a detailed spec with Use Cases, Activity Diagrams (all paths), and Gherkin acceptance criteria.`
+|`Create a detailed spec with Use Cases (Trigger, Main Flow, Alternative Flows, Postconditions, Business Rules), Activity Diagrams (all paths), and Gherkin acceptance criteria.`
 |link:#/anchor/gherkin[Gherkin]
 
 |Architektur
@@ -482,7 +497,7 @@ Die wichtigsten Einzeiler pro Phase mit den Semantic Anchors, die sie aktivieren
 |INVEST, link:#/anchor/moscow[MoSCoW]
 
 |Implementierung
-|`Select next issue (respect dependencies). Analyze and comment. Implement with TDD. Commit. Check if docs need updating.`
+|`Select next issue (respect dependencies). Analyze and comment. Implement with TDD. Each test references its Use Case ID. Commit. Check if docs need updating.`
 |link:#/anchor/tdd-london-school[TDD London] / link:#/anchor/tdd-chicago-school[Chicago], link:#/anchor/solid-principles[SOLID], link:#/anchor/dry-principle[DRY], link:#/anchor/domain-driven-design[DDD]
 
 |Code Review
@@ -533,6 +548,9 @@ Beim nächsten Projekt ausprobieren.
 Mit der Sokratischen Methode für die Anforderungen starten und sehen, wohin es führt.
 Wer Anker entdeckt, die im eigenen Workflow gut funktionieren: https://github.com/LLM-Coding/Semantic-Anchors/blob/main/CONTRIBUTING.md[zur Sammlung beitragen].
 
+Wer mit diesem Greenfield-Workflow vertraut ist, kann ihn auf bestehende Codebasen anpassen.
+Siehe link:#/brownfield[Workflow-Anpassung für Brownfield-Projekte] für eine Schritt-für-Schritt-Anleitung.
+
 === Weiterführende Literatur
 
 * Birgitta Böckeler, https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html[Exploring Gen AI] (martinfowler.com) -- eine kritische Analyse von Spec-Driven-Development-Tools (Kiro, spec-kit, Tessl) und deren Trade-offs. Untersucht, wo aufwändige Upfront-Spezifikationen helfen und wo sie Overhead erzeugen.

scripts/render-docs.js

@@ -88,6 +88,10 @@ renderFile(
   path.join(ROOT, 'docs/brownfield-workflow.adoc'),
   path.join(WEB_DOCS, 'brownfield-workflow.html')
 )
+renderFile(
+  path.join(ROOT, 'docs/brownfield-workflow.de.adoc'),
+  path.join(WEB_DOCS, 'brownfield-workflow.de.html')
+)
 
 renderFile(
   path.join(ROOT, 'docs/anchor-evaluations.adoc'),