# 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:

```java
@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)

1. **Spezialisierung schlägt den Generalisten** — eine Persona die „alles macht" driftet und genehmigt sich selbst
2. **Issues sind dauerhaftes Gedächtnis** — Spec + Entscheidungen + Review-Thread überleben jedes LLM-Gespräch
3. **Struktur tötet Leeres-Blatt-Lähmung** — Skills definieren WIE, Issues definieren WAS, du fokussierst auf WARUM
4. **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)