refactor(document): move document domain core to document/ package
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Marcel
314
docs/presentation/outline.md
Normal file
314
docs/presentation/outline.md
Normal file
@@ -0,0 +1,314 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user