Files

Marcel e85057bed2 refactor(document): move document domain core to document/ package

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-05-05 12:39:20 +02:00

12 KiB

Raw Blame History

Presentation Outline: AI-Assisted Development in Production

Brainstorming document — structure subject to change before we build the slides.

Audience: Developers + Project Manager, gemischte KI-Erfahrung Length: 30 Minuten (≈ 25 min Vortrag + 5 min Fragen) Language: Deutsch — Code, Gitea-Issues und Persona-Auszüge bleiben auf Englisch

Decisions

Language: Deutsch — Folien und gesprochener Text auf Deutsch; Code, Gitea-Inhalte und Persona-Auszüge bleiben auf Englisch (kein Bruch — das Publikum liest Englisch)
Code depth: Ein kurzes Code-Snippet maximal — reicht für Devs, PMs folgen dem Konzept
Gitea: Echte Screenshots — überzeugender als nachgebaute Beispiele
Roter Faden: Ein echtes Issue von Anfang bis Ende (z.B. #358 Stammbaum)
- Das Publikum verfolgt dasselbe Issue von der vagen Idee → Spec → Review → Code → gemergte PR
- Verhindert das "und jetzt ein anderes Beispiel"-Gefühl
Demo: Keine Live-Demo — zu riskant für 30 min. Annotierte Screenshots stattdessen.

Working title

„KI als Team, nicht als Werkzeug" (Untertitel: ein strukturierter Workflow für LLM-gestützte Entwicklung)

Alternativen:

„Von der vagen Idee zum Merge-Request — mit Claude"
„Ein strukturierter Workflow für LLM-gestützte Entwicklung"

Timing Budget

Section	Slides	Minutes
1. Title + Hook	1	1
2. The Project	2	2
3. The Problem with "just ask the AI"	1	2
4. Workflow overview	1	1
5. Idea & UI exploration	2	3
6. The Personas	2	3
7. Spec with Elicit → Gitea issue	2	4
8. Persona issue review	2	4
9. Implementation (TDD)	2	4
10. PR review loop	1	3
11. Takeaways	1	2
Total	17	29

Slide-by-Slide Outline

1 · Titel (1 min)

„KI als Team, nicht als Werkzeug" Ein strukturierter Workflow für LLM-gestützte Entwicklung

Einstiegssatz: „Die meisten nutzen KI als sehr schnelle Schreibkraft. Ich nutze sie als Team von Spezialisten."
Keine separate Agenda-Folie — das Workflow-Diagramm in Abschnitt 4 übernimmt diese Rolle

2 · Das Projekt: Familienarchiv (2 min, 2 Folien)

Folie 2a — Domäne

Familienarchiv: handgeschriebene Kurrent- und Sütterlin-Briefe, 1899–1950
Crowd-Transkription durch 60+-Jährige am Laptop
Mobile-first Leseerlebnis für jüngere Familienmitglieder
Solo-Entwicklerprojekt — kein Team zum Review, Pair-Programming oder Rubber-Ducking

PM-Takeaway: echte Domäne, echte Nutzer, echte Constraints Dev-Takeaway: kein Toy-Projekt — voller Stack

Folie 2b — Stack & Umfang

Spring Boot 4 · SvelteKit 5 · PostgreSQL · MinIO · Paraglide i18n (de/en/es)
40+ UI/UX-Spec-Dateien, 360+ Gitea-Issues, laufende Entwicklung
Screenshot der laufenden Anwendung

Dev-Hinweis: Backend und Frontend, der Workflow muss die gesamte Vertikale abdecken

3 · Das Problem mit „Einfach die KI fragen" (2 min, 1 Folie)

Die vier typischen Misserfolge:

Was man tut	Was schiefläuft
Vage Idee beschreiben → Code anfordern	Output passt nicht zu dem, was man eigentlich wollte
Langen Prompt einfügen → Review anfragen	„Sieht gut aus!" — kein echter Widerspruch
Design + Code + Review in einer Session	Befangenheit: was selbst geschrieben wurde, wird nicht ehrlich kritisiert
Auf Gesprächskontext vertrauen	Nächste Session startet blank — kein Gedächtnis

Die Lösung für alle vier: Struktur und Trennung von Verantwortlichkeiten Das ist ein Workflow-Problem, kein Prompt-Problem

4 · Der Workflow im Überblick (1 min, 1 Folie)

Vage Idee
  │
  ▼
UI-Exploration ──► Spec (Elicit-Persona) ──► Gitea-Issue
                                                  │
                              ┌───────────────────┤
                              ▼                   │
                       Persona-Review  ◄──────────┘
                       (6 Spezialisten)
                              │
                              ▼
                       Feature-Branch
                              │
                        TDD: Red → Green → Refactor → Commit
                              │
                              ▼
                       Pull Request ──► Persona-PR-Review ──► Merge

Das ist die Karte. Jeder Abschnitt zoomt in einen Schritt hinein. Roter Faden: wir verfolgen Issue #358 durch jeden Schritt.

5 · Idee & UI-Exploration (3 min, 2 Folien)

Folie 5a — Von vage zu visuell

Start: „Ich möchte Familienbeziehungen auf der Dokumentdetailseite anzeigen"
Bevor ein Wort Spec geschrieben wird: laufende App öffnen und erkunden
Statisches HTML-Mockup generieren — es ist ein Denkwerkzeug, kein Produktionscode
Zeigen: specs/stammbaum-relationship-badge-spec.html im Browser
Visuell iterieren, bis der Scope konkret wird

Warum zuerst? Das Mockup bringt Entscheidungen ans Licht, von denen man nicht wusste, dass man sie treffen muss. Scope-Unklarheiten auf Pixel-Ebene zu lösen ist billiger als in einem Requirements-Dokument.

Folie 5b — Die HTML-Spec als Kommunikationsartefakt

Screenshot der Spec: annotiert mit Farb-Tokens, Breakpoints, Interaktionshinweisen
Dient als Eingabe für das Elicit-Interview
PM-Perspektive: ein Lo-fi-Wireframe, der in jedem Browser funktioniert

6 · Die Personas (3 min, 2 Folien)

Folie 6a — Das Team vorstellen

Name	Rolle	Schwerpunkt
Elicit	Requirements Engineer	Nutzerforschung, JTBD, BABOK
Markus Keller	Architekt	Systemdesign, Trade-offs, Layering
Felix Brandt	Senior Developer	TDD, Clean Code, SvelteKit + Spring Boot
Leonie Voss	UX Designerin	Accessibility, Responsive Design, Brand
Sara Holt	QA Engineer	Testpyramide, Playwright, Randfälle
Nora „NullX" Steiner	Security Engineer	AppSec, OWASP, Auth
Tobias „tobi" Wendt	DevOps	Docker, CI/CD, Infrastruktur

Markdown-Dateien in .claude/personas/. Jede mit echtem Namen und Biografie.

Folie 6b — Aufbau einer Persona

Kurzer Auszug aus developer.md (Felix) — auf Englisch, kein Kommentar nötig:

You are Felix Brandt, Senior Fullstack Developer …

## Hard Limits — What You Do NOT Do
- You NEVER write a test after the fact to justify existing code
- You NEVER skip the Red step, even for "obvious" implementations
- You NEVER commit a test and its implementation in separate commits

## What You DO
- Write the failing test first. Always.
- Reference specific line numbers in every review comment.

Der „Hard Limits"-Abschnitt ist die entscheidende Idee. Eine Persona ohne Grenzen driftet. Separation of Concerns gilt auch für KI-Rollen.

7 · Spec schreiben mit Elicit → Gitea-Issue (4 min, 2 Folien)

Folie 7a — Das Elicit-Interview

Elicit führt ein strukturiertes Interview (kein Code — nur Requirements)
Input: das HTML-Mockup + die vage Idee
Prozess: User Journey, Fehlerszenarien, nicht-funktionale Anforderungen, explizites Out-of-Scope
Output: ein dichtes Gitea-Issue — keine Markdown-Datei im Repo

Warum Gitea, nicht eine Datei?

LLM-Gespräche sind flüchtig; Gitea-Issues sind dauerhaft
Issues sind verlinkbar: jeder Commit und jede PR referenziert sie
Review-Kommentare, Spec und Entscheidungen leben in einem Thread
Kein Risiko, dass eine Spec-Datei vom tatsächlich Gebauten abweicht

Folie 7b — Aufbau eines echten Spec-Issues

Issue #358 (oder ähnliches) annotiert zeigen — auf Englisch, kein Kommentar nötig:

Problem statement: was fehlt/kaputt ist und warum es wichtig ist
User Journey: Schritt für Schritt in einfacher Prosa, aus Nutzerperspektive
E2E-Szenarien (Given/When/Then) → werden direkt zu Red-Tests in TDD
Requirements: funktional + NFR
Out of scope: explizite Ausschlüsse — verhindert Scope Creep

PM-Perspektive: das ist der Vertrag vor Baubeginn. Dev-Perspektive: das Szenario IST der erste fehlschlagende Test.

8 · Persona-Issue-Review (4 min, 2 Folien)

Folie 8a — Vor dem ersten Code: die Spec reviewen

review-issue-Skill schickt einen Agenten pro Persona
Jede liest das Issue unabhängig — kein Group-Think
Kommentare werden direkt als echte Gitea-Kommentare gepostet
Jede Persona sucht nach Anderen Dingen:
- Nora: Gibt es neue Endpoints? Ist Auth spezifiziert?
- Sara: Sind die Szenarien tatsächlich testbar?
- Leonie: Berücksichtigt die User Journey Mobile?
- Markus: Verletzt das Design Domain-Grenzen?

Folie 8b — Einen echten Review-Kommentar zeigen

Screenshot oder Auszug: ein Kommentar einer Persona, der die Spec verändert hat

Ideal: ein Fall, in dem eine Reviewerin etwas gefunden hat, das sonst einen Bug oder Rework verursacht hätte
„Hier zu finden kostet null. Nach dem PR-Öffnen kostet es einen Tag."

9 · Implementierung: Red/Green/Refactor (4 min, 2 Folien)

Folie 9a — Spec → Test → Code

deliver-issue-Skill koordiniert den gesamten Zyklus
Das E2E-Szenario aus dem Issue IST der äußerste fehlschlagende Test
Zyklus: fehlschlagender E2E-Test → fehlschlagende Unit-Tests → minimaler Produktionscode → grün → Refactor → atomarer Commit
Ein logischer Change pro Commit; immer Feature-Branch

PM-Perspektive: die Akzeptanzkriterien aus dem Issue sind die Definition of Done. Das Feature ist nicht fertig, bis der aus dem Szenario geschriebene Test grün ist.

Folie 9b — Ein Code-Beispiel (kurz)

Echter Test aus feat/stammbaum-issue-358 — auf Englisch, kein Kommentar nötig:

@Test
void getFamilyNetwork_excludesEdgesWithNonFamilyEndpoints() {
    // … setup …
    var result = service.getFamilyNetwork(personId);
    assertThat(result.edges())
        .noneMatch(e -> isNonFamilyPerson(e.targetId()));
}

git log-Auszug, der zeigt dass der Test-Commit vor dem Impl-Commit liegt

Dev-Hinweis: Test und Implementierung liegen im selben atomaren Commit. Das Log ist der Beweis, dass der Red-Schritt stattgefunden hat.

10 · PR-Review-Schleife (3 min, 1 Folie)

Wie der PR-Review funktioniert

review-pr-Skill liest den Diff; jede Persona postet Kommentare zur Gitea-PR
Dieselben Spezialisten, jetzt auf Code-Ebene statt Spec-Ebene
Andere Fragestellungen als beim Issue-Review:
- Felix: folgt der Code dem Projektstil? Toter Code?
- Nora: ist jeder neue Endpoint hinter @RequirePermission?
- Sara: fehlen Randfallstests?
- Leonie: stimmt der gerenderte Output mit der Spec überein?
Zeigen: einen PR-Kommentar, der den Merge blockiert hat, bis das Problem behoben war

Die Personas sind keine Gummistempel. Jede hat eine harte Checkliste. Merge erst wenn alle Stimmen zufrieden sind.

Schleife: Kommentare adressieren → pushen → Review erneut starten → wiederholen

11 · Fazit (2 min, 1 Folie)

Spezialisierung schlägt den Generalisten — eine Persona die „alles macht" driftet und genehmigt sich selbst
Issues sind dauerhaftes Gedächtnis — Spec + Entscheidungen + Review-Thread überleben jedes LLM-Gespräch
Struktur tötet Leeres-Blatt-Lähmung — Skills definieren WIE, Issues definieren WAS, du fokussierst auf WARUM
Der Workflow ist das Produkt — Code ist nur die Ausgabe; Reproduzierbarkeit kommt vom Prozess

Ehrliches Caveat:

Aufwand am Anfang: gute Personas zu schreiben kostet Zeit
Der Ertrag ist kumulativ: jedes neue Issue profitiert von der bestehenden Infrastruktur
Kein Allheilmittel: die Personas sind nur so gut wie ihre Hard Limits

Schlusssatz: „Ihr wisst bereits, dass ihr einen Requirements Engineer, einen Architekten, einen Security Reviewer und einen QA-Spezialisten braucht. Die Frage ist nur, ob ihr euch alle Vollzeit leisten könnt — oder ob ihr einer KI beibringen könnt, jede dieser Rollen zu spielen."

Vorzubereiten vor dem Folienbau

Das eine Issue für den roten Faden auswählen — prüfen ob es eine gute Spec, echte Review-Kommentare und einen sauberen TDD-Trail in git hat
Screenshots sammeln: laufende App, Spec-HTML, Gitea-Issue, Review-Kommentar, PR-Kommentar
Den einen Persona-Auszug auswählen (Felix' Hard-Limits-Abschnitt ist am klarsten)
Echte Zahlen eintragen: Anzahl Issues, Specs, Personas, Commits auf dem Branch
Folienthema festlegen (Dunkel passt zu Code-Blöcken; alternativ Familienarchiv-Brandfarben Navy/Mint)

12 KiB Raw Blame History Unescape Escape