SPEC · PROTOTYPE · TASKS · HARNESS ·
SPEC · PROTOTYPE · TASKS · HARNESS ·
◆ Training · 2026
Agentic
Engineering
& Harness.
Spec-driven Softwareentwicklung mit KI-Agents —
Theorie, Praxis, Sicherheit.
▸ Scope vs. Quality
Je grösser der Scope,
desto schlechter das Ergebnis.
Kein Gefühl — messbar.
I · ERROR COMPOUNDING
Fehler propagieren
Eine falsche Annahme früh im Kontext kippt alle folgenden Entscheidungen. Kleine
Schritte begrenzen den Radius.
II · CONTEXT ROT
Jedes Modell degradiert
Agents akkumulieren Rauschen. Ab ~100k Tokens bevorzugen sie Wiederholung statt
Synthese.
Chroma Research 2025 · 18 Modelle
III · SILENT INCORRECTNESS
Sieht richtig aus
Kompiliert, besteht oberflächliche Checks — ist aber semantisch falsch. Breiter Scope
→ höhere Rate.
DIE EVIDENZ
SWE-Bench Pro (Scale AI): GPT-5, Opus
4.1 lösen 23% der
Long-Horizon-Tasks. SWE-Bench Verified:
70%+.
Lost in the Middle:
30%+ Accuracy-Verlust bei mittiger Info.
Prompt Chaining: gewinnt
77/100 Vergleiche gegen All-in-One.
Unsere Erfahrung: präzise Specs vor dem Start sparen ein Vielfaches an Nacharbeit. Die 8
Tage Spec-Arbeit vor dem Marathon-Tag (40 Commits) waren kein Overhead — sondern
Voraussetzung. Das Tempo war vertretbar, weil der Harness die komplette Suite pro Commit
fuhr.
◎ Thesis
Nicht der Agent
wird besser.
Die Arbeit wird
besser strukturiert.
I · SPECS ALS FORCING FUNCTION
Specs zwingen implizite Entscheidungen an die Oberfläche. Was der Mensch nicht
aufschreibt, füllt das Modell mit generischen Priors — meistens falsch für
Domänenregeln.
II · KLEINE TASKS, BLAST RADIUS
Jeder Task ist so geschnitten, dass ein Agent ihn in einem Durchlauf umsetzt. Fehler
bleiben lokal. Frischer Kontext — kein Context Rot.
III · TESTS ALS SICHERHEITSNETZ
Die Testsuite ist kein Nachgedanke, sondern Fundament. Sie wächst mit jedem Task und
sichert den nächsten Agent-Durchlauf ab.
↗ OPEN QUESTIONS —
Der Ingenieur verschiebt sich vom Autor zum Reviewer, Architekten und Spec-Schreiber.
Andere Fähigkeiten, offene Fragen: Review-Qualität bei fremdem Code, Skill-Entwicklung für
Junioren, Delegation ohne Kontrollverlust.
◆ Four Steps
Vom Konzept
zum Code.
/PROTOTYPE, /GENERATE-TASKS, /IMPLEMENT-TASK SIND EIGENE CLAUDE CODE SKILLS — KEINE
BORDMITTEL.
01
Spec schreiben
docs/10-business/*.md
Datenmodell, Abläufe, Geschäftsregeln, Randfälle. Die Spec zwingt implizite
Entscheidungen an die Oberfläche.
02
Prototyp erzeugen
/prototype
Klickbares Alpine.js-Prototype aus der Spec. Stakeholder erleben das Verhalten, Lücken
werden sichtbar.
03
Tasks generieren
/generate-tasks
Spec vs. Codebase analysieren, Mehrdeutigkeiten finden, zerlegen: Schema → Domain →
API → UI → Test.
04
Task umsetzen
/implement-task
Ein Task pro Durchlauf. Implementieren, Tests laufen lassen, Security-Review, Commit.
Mensch reviewed.
↻
Kein linearer Prozess. Der Prototyp deckt
Lücken auf → Spec wird verfeinert.
/generate-tasks findet Widersprüche
→ zurück zur Spec. Selbst
/implement-task erzeugt manchmal
neue Spec-Aufgaben. Jeder Übergang ist ein Quality Gate.
◆ 01 · Spec schreiben
Was nicht aufgeschrieben ist,
wird halluziniert.
WAS EINE SPEC ENTHÄLT
✓ Datenmodell mit Typen und Constraints
✓ Benutzerabläufe Schritt für Schritt
✓ Geschäftsregeln mit
SHALL / SHOULD / MAY
✓ Randfälle und Fehlerzustände
✓ Sicherheitsüberlegungen
✓ Nicht-funktionale Anforderungen
Specs sind portabler als Prompt-Engineering. Dieselben Specs lassen sich mit
verschiedenen Modellen verwenden.
BEISPIEL · HAFCOIN STORNO-REGELN
### Stornierung
Kostenlose Stornierung ≥ 24h vor Beginn.
Keine Rückerstattung bei Stornierung < 24h.
Admin kann jederzeit stornieren (volle Rückerstattung).
Coins werden als «refund» zurückgebucht.
Stornierte Buchungen bleiben im Audit Trail.
Ohne Spec würde das Modell eine generische «jederzeit stornierbar»-Logik bauen. Die
24h-Regel und der Refund-Audit-Trail würden fehlen.
◆ 02 · Prototyp erzeugen
Feedback vor der ersten
Zeile Produktionscode.
SO FUNKTIONIERT ES
/prototype docs/10-business/04-bookings.md
→ Generiert eine HTML-Datei mit Alpine.js
→ In-Memory State — keine Datenbank, kein Backend
→ Stakeholder öffnet die Datei im Browser, klickt durch
→ Findet Lücken, Spec wird verfeinert
Der Prototyp macht abstrakte Spec-Regeln greifbar. Ein «Coin-Abzug bei Buchung» im
Markdown liest sich anders als ein sichtbar schrumpfender Kontostand im Browser.
HAFCOIN · WAS ENTDECKT WURDE
PROFIL
Profilseite brauchte Password-Änderung und Firmendaten-Anzeige. Spec
erweitert.
RECHNUNGEN
CHF-Beträge für Pauschale-Buchungen fehlten in der Spec.
NAVIGATION
Kalender-Abonnement brauchte zwei Feed-Optionen statt einer.
Der Prototyp wird verworfen. Sein Wert liegt in den Lücken, die er aufdeckt.
— Ob das billiger ist als klassische UX-Forschung, hängt vom Projekt ab.
◆ 03 · Tasks generieren
Zerlegt in Schichten,
geordnet nach Abhängigkeit.
/generate-tasks liest die Spec,
analysiert die bestehende Codebase und zerlegt die Arbeit in schichtspezifische,
abhängigkeitsgeordnete Tasks.
WAS DER SKILL TUT
Findet Mehrdeutigkeiten, fehlende Informationen, Konflikte mit bestehendem Code
Zerlegt in Schichten:
SCHEMA → DOMAIN → API → UI → TEST
Ordnet Abhängigkeiten: Domain braucht Schema, API braucht Domain
Jeder Task bekommt testbare Akzeptanzkriterien
↻ Wenn die Analyse
Mehrdeutigkeiten findet, geht es zurück zur Spec. Kein «weiter trotzdem».
BEISPIEL · PASSWORT-RESET → 5 TASKS
1
TASK-121 · Token-Tabelle und Enum-Migration
SCHEMA
2
TASK-122 · Token-Logik: erzeugen, validieren, einlösen
DOMAIN
3
TASK-123 · Server Actions und E-Mail-Template
API
4
TASK-124 · UI-Seiten und Login-Link
UI
5
TASK-125 · E2E-Tests für den gesamten Flow
TEST
◆ 04 · Task umsetzen
Ein Task pro
Agent-Durchlauf.
/implement-task TASK-138 · Klare
Eingabe, klares Ergebnis, reviewbar in Minuten.
DER DURCHLAUF
✓
Task-Datei und Spec lesen
· Abhängigkeiten prüfen. Alle erfüllt?
✓
Code schreiben
· Architekturschicht, Coding Standards, Akzeptanzkriterien
✓
Gesamte Testsuite laufen lassen
· Scheitert ein Test → Task nicht abgeschlossen
✓
Security Review
· Automatische Sicherheitsprüfung der Änderungen
✓
Writedown & Commit
· Dokumentation, Feature-Branch, Pull Request
★
Mensch reviewed
· Erst nach Freigabe geht es weiter
GRANULARITY SWEET SPOT
200–400 LOC
pro Code Review
ERFAHRUNG · HAFCOIN
~4 kognitive Chunks
gleichzeitig
COWAN 2001
1–2 Tage
pro Task
AGILE CONSENSUS
Frischer Kontext
pro Subtask
CHROMA · LIU ET AL.
KI-Agents senken die Transaktionskosten pro Task. Mit Reinertsens Logik verschiebt das
das Optimum nach links — kleinere Tasks als
bei rein menschlicher Arbeit.
◆ Harness
Dreistufige Testsuite.
Bei jeder Änderung.
Prüft, ob der Agent-Code korrekt ist, und schützt bestehende Funktionalität vor
Regressionen.
LEVEL 01
Unit-Tests
Vitest · src/domain/
Isolierte Geschäftslogik: Coin-Berechnung, Storno-Regeln, Quartals-Verfall. Jede
Domain-Funktion hat eine Spec. Der Test ist ihr automatisierter Beweis.
LEVEL 02
Integration
Vitest · echte PostgreSQL
Server Actions gegen eine echte DB. Bewusste Entscheidung:
keine Mocks. Migrationsfehler scheitern im
Test, nicht in Produktion. Bei grösseren Projekten: Trade-off gegen Laufzeit.
LEVEL 03
E2E-Tests
Playwright · Browser
Simulieren echte Nutzer: einloggen, buchen, Coins prüfen, stornieren. Decken
Regressionen auf, die kein Unit-Test findet: das kaputte Formular, der fehlende
Button.
/implement-task erzeugt nicht nur
Code, sondern auch Tests — und lässt die gesamte bestehende Suite laufen. Mit
jedem Inkrement wird das Netz dichter.
Erst das macht das Tempo vertretbar.
◆ In Practice
Das wachsende Netz.
WOFÜR DER HARNESS SORGT
Tests verifizieren gegen Spec-Akzeptanzkriterien. Nicht das Bauchgefühl des
Reviewers entscheidet, ob der Code stimmt, sondern die Suite.
Die gesamte Suite läuft bei jedem Task. Regressionen werden sofort entdeckt, nicht
erst beim nächsten Release.
Der Mensch muss nicht jede Zeile lesen. Die Tests sind gegen die Spec geschrieben
und damit nachvollziehbar.
HAFCOIN · COMMANDS
$ npm run test — Unit & Integration (Vitest)
$ npm run test:e2e — Browser-E2E (Playwright)
$ npm run test:gherkin — Akzeptanz (Cucumber)
$ /security-review — Sicherheitsprüfung
Bewusste Entscheidung:
echte Datenbank, keine Mocks. Funktioniert
bei 129 Tasks. Bei 10'000+ Tests wäre das ein Laufzeit-Problem. Für diese
Projektgrösse ist der Trade-off richtig.
◈ Reality Check
Specs verhindern
keine Fehler.
Sie machen sie billig.
SACKGASSE · 01
Auth-Kehrtwende
Custom Auth → Auth.js v5. Pivot in 4 Stunden, am selben Tag.
SACKGASSE · 02
Buchungs-UX
3 Iterationen, 24 Tage. 572 LOC gelöscht. Einfachste Lösung gewann.
SACKGASSE · 03
No-Show entfernt
Komplett gebaut, komplett gelöscht. User-Testing hat es gezeigt.
↳ 572 Zeilen Code zu löschen tut nicht
weh, wenn sie in Minuten entstanden sind. Kleine Tasks machen Pivots billig. Der Harness
schützt den Rest während der Entfernung. Die eigentliche Entdeckungsarbeit passiert im
User-Testing und Prototyping, nicht in der Spec selbst.
SACKGASSE
23. MÄRZ 2026
Ein Tag, zwei
Entscheidungen.
MORGENS
Entscheid dokumentiert: «Kein Auth.js, wir bauen Custom Auth.» Begründung: Rolling
Timeout, Session Limits, Forced Password Change «unverzichtbar».
NACHMITTAGS
Erkenntnis: Diese 4 Features erhöhen die Komplexität
unverhältnismässig zum Sicherheitsgewinn für ein internes Gebäudesystem
mit 19 Mietern.
RESULTAT
Komplette Kehrtwende. Auth.js v5 in 4 Tasks migriert. Selber Tag.
DER PIVOT
Custom Auth
→
ADR-0005
→
Auth.js v5
~10 Commits verworfen, 4 neue Tasks erstellt
ADR geschrieben — Entscheid dokumentiert für die Zukunft
Forced Password Change: gestrichen (TASK-039 cancelled)
Kleine Tasks machen Pivots billig. Ein ADR dokumentiert das Warum. Die Spec wird
angepasst, nicht der Code drumherum.
24 TAGE
BUCHUNGS-UX
Die einfachste Lösung
gewann.
Aber es brauchte Exploration, um sie zu finden.
01
Wizard
24. MÄRZ · 632 LOC
Dreistufiges Formular: Ressource → Datum → Zeit. Funktioniert, aber zu viele Klicks
für eine einfache Buchung.
Zweigeteilte Ansicht: Raumliste links, Buchungs-Timeline rechts. Höhere
Informationsdichte, aber zu komplex.
03
Pauschale-Buttons
18. APRIL · −572 LOC
Drei Buttons pro Raum: Vormittag, Nachmittag, Ganzer Tag. Ein Klick → vorgefüllter
Dialog. Die einfachste Lösung.
↗ Drei Iterationen über 24 Tage kosten
Zeit. Aber jede war in Stunden gebaut und in Minuten entfernt.
Ob frühere UX-Forschung das verkürzt hätte, bleibt offen.
GESTRICHEN
FEATURE · NO-SHOW TRACKING
Auf Papier logisch.
In der Realität: unmöglich.
WAS GEBAUT WURDE
✓ DB-Schema: no_show Status in
Enums
✓ Repository:
markNoShow() Funktion
✓ Server Action:
markNoShowAction()
✓ Admin-UI: Tabs, Filter, Badges
✓ E2E-Tests: TASK-037
WAS USER-TESTING ZEIGTE
«Nicht erschienen kann entfernt werden, da wir das nicht tracken können.»
Das Gebäude hat keinen Mechanismus, um die tatsächliche Raumnutzung zu erfassen. Das
Feature war technisch korrekt — aber real unmöglich zu bedienen.
$
grep -r "no.show\|noShow\|no_show"
→ 0 Treffer
↳ Test mit echten Nutzern. Entferne
ohne Reue. Nach dem Entfernen läuft die gesamte Suite und bestätigt, dass nichts kaputt
ging.
◆ Takeaways
Fünf Prinzipien.
01
Spec
before Code
Was nicht aufgeschrieben ist, wird halluziniert.
02
Prototype before
Implementation
Feedback vor der ersten Zeile Produktionscode.
03
Kleine Tasks,
Blast Radius
Frischer Kontext, reviewbar in Minuten.
04
Tests sind
der Harness
Ohne Sicherheitsnetz ist das Tempo unverantwortlich.
05
Falsche Entscheid-
ungen billig machen
Specs verhindern keine Fehler. Sie machen Rückbau billig.
⚠ DISCLAIMER —
HafCoin ist ein Existenzbeweis, kein Universalrezept. Ein Projekt, ein Team, 19 Nutzer,
internes Buchungstool. Nicht getestet: >100 Stakeholder, Legacy-Codebases,
regulatorische Anforderungen. Die 40h Coding-Zeit beschleunigen den billigsten Schritt —
die restlichen 46 Tage gingen in Spec-Arbeit, Review, User-Testing und Denkzeit.
WIR BEGLEITEN TEAMS AUF DEM WEG ZU AGENTIC ENGINEERING
Sprechen wir drüber.
christine@betterlabs.ch
pawel@betterlabs.ch
BetterLabs GmbH · Altenbergstrasse 29 · 3013 Bern