Als die ersten Coding-Agenten herauskamen, hatte ich einen naiven Traum: Ich sitze im Garten oder bin im Wald unterwegs, während mein Agent die ganze harte Arbeit erledigt.
Wie viele andere auch fühlte ich mich ein bisschen betrogen. Klar, ich habe mehr geschafft und musste nicht mehr den ganzen Code selbst schreiben. Trotzdem saß ich die meiste Zeit vor dem Chatfenster und gab Anweisungen, was als Nächstes zu tun ist.
Dadurch verbrachte ich sogar mehr Zeit vor dem Bildschirm, nicht weniger.
War das Versprechen nicht ein anderes?
Doch, schon. Aber dafür müssen wir ein bisschen anders vorgehen und vorab etwas Zeit investieren, bevor wir aufhören können, den Chat zu babysitten.
Ich zeige dir die wunderbare Welt des Spec-Driven Development – eine Art zu entwickeln, bei der du wandern gehen kannst, während dein Agent die Schwerarbeit erledigt.
Spec-Driven was?
In diesem etwas längeren Beitrag führe ich dich durch ein einzelnes Epic, das wir gemeinsam entwickeln. Danach hast du alles, was du brauchst, um selbst mit Spec-Driven Development loszulegen.
Für den Einstieg brauchst du:
- ein Claude-Abo (die kostenlose Version reicht nicht)
- Claude Code (installiert)
- ein Terminal
- Node.js und npm
- git
- deine ganze Vorstellungskraft für das Tool, das wir bauen
Lege auf deinem Rechner einen Ordner für die Anwendung an. Da wir mit Node.js arbeiten, schreib den Ordnernamen klein und ohne Leerzeichen.
Starte in diesem Ordner Claude Code (Befehl `claude`) und füge diesen Prompt ein:
Create a Hello world boilerplate based on Next.js and Tailwind in this folder. Initialize a git repository if there is none.
Falls noch nicht geschehen, stell Claude Code auf den Auto-Modus um: Drück so lange Shift+Tab, bis im Terminal „auto mode“ steht.
Genug vorbereitet – jetzt bauen wir etwas.
Was wir bauen
Wir bauen eine Plattform für Visumanträge. Jedes Mal, wenn ich verreise und ein Visum beantragen muss, ärgere ich mich über die altmodischen Portale und ihre umständliche Bedienung.
Also lass uns etwas Cooles und Einfaches bauen – vielleicht verkaufst du es danach ja an deine Regierung.
Dafür habe ich ein kurzes Briefing geschrieben, wie die Anwendung funktionieren soll:
# Spec — Mini Visa System
## Goal
A tiny two-sided app: applicants submit visa applications; an officer reviews them.
Deliberately minimal. Applicant and officer views are switchable via a switch on top right.
## Technical Decisions
Use sqlite as a database.
## Form Submission - Applicant Side
**Behaviour:** A form where an applicant enters their details and submits. On submit,
the application is saved to the database and the applicant sees a confirmation.
Fields:
- Full name (required, text)
- Country of origin (required, text)
- Purpose of visit (required, one of: tourism / business / study)
- Interested in committing crimes? (required, yes/no)
Acceptance criteria:
- Submitting a valid form persists one application with status = "pending".
- Required fields are validated before save; errors are shown inline.
- After a successful submit the form clears and shows "Application received".
## Officer view
**Behaviour:** A list of pending applications. The officer opens one and approves or
rejects it. If the applicant is **interested in committing crimes**, a clear warning is shown
before the officer decides.
Acceptance criteria:
- Officer sees a list of all "pending" applications.
- Opening an application shows all submitted fields.
- If interested-in-crimes = yes → a visible warning banner: "⚠ Applicant intends to commit crimes".
- Approve/Reject sets status to "approved"/"rejected" and removes it from pending.
## Out of scope
- Auth / login, payments, email, document uploads, multiple officers.
- Deployment
Du kannst natürlich auch gleich deine eigene App bauen. Was wir hier machen, funktioniert für die meisten Webanwendungen genauso.
Kopiere jetzt das Briefing von oben, lege einen Ordner `specs` an, erstelle darin eine Datei `briefing.md` und füge den Inhalt dort ein.
Dein Verzeichnis sollte jetzt so aussehen:
Wenn du den Code selbst schreiben würdest, würdest du die Anwendung auch in einzelne Teile zerlegen. Genau das lassen wir jetzt die KI machen.
Alles, was du ab jetzt in einem Codeblock siehst, ist ein Prompt, den du in Claude Code kopieren kannst.
Based on the @specs/briefing.md please create a roadmap.md file in specs folder, with 2 epics, one for the applicant one for the officer.
Resolve dependencies so that epics can be built and validated independently and incrementally.
Each epic should have a visible deliverable.
Und jetzt kommt das Detail, auf das du achten solltest:
Wenn du Claude nicht sagst, wie viele Epics du willst, entscheidet es selbst. Und aus Erfahrung kann ich sagen: Dabei übertreibt es gern ziemlich. Deshalb lege ich inzwischen selbst fest, wie wir die Epics aufteilen.
Außerdem sagen wir Claude, dass jedes Epic ein sichtbares Ergebnis haben soll. Bei deiner App kann es sinnvoll sein, zuerst Grundlagen wie Datenbank und Infrastruktur zu bauen. Ich habe aber gern immer etwas zum Anschauen, um zu prüfen, ob wir in die richtige Richtung gehen.
Wenn in deinem specs-Ordner eine `roadmap.md` liegt, hat alles geklappt. Stellt Claude dir im Chat Fragen, ist das auch in Ordnung: Beantworte sie und warte, bis die Roadmap-Datei geschrieben ist.
Sieht das nicht nach einer schönen Roadmap aus? Meine zu zeigen bringt dir nichts, denn sie sieht anders aus als deine. Solange du zwei Epics hast, kann es weitergehen.
Vielleicht fragt Claude dich jetzt, ob es mit Epic 1 weitermachen soll. Das machen wir nicht. Bei dieser kleinen App würde es wahrscheinlich sogar klappen, aber ich will dich auf echte Projekte vorbereiten.
Unser erstes PRD – Zeit fürs Brainstorming
Jetzt lassen wir Claude Code ein PRD erstellen, ein Product Requirements Document – also ein Anforderungsdokument.
Based on the @specs/roadmap.md please create a concise prd for epic 1 in the specs folder. If there are gaps in requirements please ask me questions. Place questions at the end of the PRD. Each question should be provided with four options one of the options should be labeled as recommended based on our briefing and roadmap context. Options should be provided with [ ] so it's easy for me to select an option
For demonstration purposes you are only allowed to ask me 3 questions. For other technical or design decisions stick to industry standards and best practices.
Bei deinem eigenen Produkt beschränkst du dich natürlich nicht auf drei Fragen. Achte außerdem darauf, dass deine Roadmap mit Epic 1 beginnt. Fängt sie bei 0 an, musst du hier Epic 0 schreiben.
Ein PRD ist ein bewährtes Format, um Anforderungen festzuhalten. Je nach Team sieht es bei dir vielleicht etwas anders aus. Wenn du das später ändern willst, sag es Claude einfach – für dieses Tutorial reicht es so. Mehr über PRDs erfährst du hier.
Wenn Claude fertig ist, liegt in deinem specs-Ordner eine Datei mit einem Namen wie `prd-epic-1.md`. Da wir im Prompt keinen Namen vorgegeben haben, denkt Claude sich einen aus. Das kannst du vermeiden, indem du ein festes Schema vorgibst, zum Beispiel `prd/epic-X.md`. Das sagen wir Claude gleich.
Öffne die Datei und lies sie durch. Hast du dir unseren Visumantrag so vorgestellt? Wenn ja, geh zu den Fragen am Ende der Datei. (Wenn nicht, ändere den Text direkt. Für diese Demo lasse ich ihn, wie er ist.)
Beantworte jetzt die Fragen, indem du ein X in die Klammern setzt. Und wenn dir keine der Antworten gefällt – du ahnst es –, änderst du sie.
...
## Open questions
Pick one option per question by changing `[ ]` to `[x]`.
### Q1. How does the top right switch change views?
The briefing says the views are "switchable via a switch" and gives no detail on how that should behave.
- [ ] A. Separate routes, `/` for Applicant and `/officer` for Officer, with the switch as a link toggle. Each view has its own URL and survives a refresh. (Recommended)
- [ ] B. One page with client-side state. Refreshing always returns to Applicant.
- [ ] C. One page with the view held in a query parameter, for example `/?view=officer`.
- [ ] D. One page with client-side state remembered in `localStorage`.
Why A is recommended: Epic 2 replaces a placeholder with real data, and a route of its own keeps the two epics from touching each other's code.
### Q2. What kind of input is Country of origin?
...
Wenn du fertig bist, sag Claude, dass es die Fragen in feste Anforderungen umwandeln soll. Es sollen keine verworfenen Antworten mehr drinstehen, die die KI später zum Halluzinieren bringen könnten.
Answered all questions, now reconcile them into direct requirements in the PRD. For demonstration purposes, don't open another round, fill in the gaps yourself.
Das war unser erstes Brainstorming. Je nachdem, wie komplex deine Anwendung ist, geht das über mehrere Runden, bis keine Lücken mehr bleiben. (In einem echten Projekt lässt du den Teil „For demonstration purposes“ natürlich weg.)
In der nächsten Runde wollen wir das nicht alles noch einmal eintippen – also packen wir es in einen Skill. Und dabei regeln wir gleich die Benennung der PRD-Datei.
Based on how our conversation went, create a skill called brainstorm that will create a simple PRD based on the roadmap if it's not created. It will ask questions to cover large gaps in the requirements and continue reconciling and asking questions until we reach 80% confidence for the PRD. Make sure PRD files are named consistently in the format of `specs/prd/epic-{N}.md` and rename the existing PRD for epic 1 accordingly. Use Claude Code Documentation to create skills. Skill should be created for this project only. Also include to do a commit after each round of questions.
Write spec skillDanach erstellen wir ein paar weitere Skills: fürs Schreiben der Tech-Spec, für die Umsetzung und für die Prüfung. Deshalb vorab ein paar Details, die für alle Skills gelten:
- Projekt-Skills: Wir erstellen den Skill nur für dieses Repository. So können wir ihn ganz genau auf dieses Projekt und seinen Tech-Stack zuschneiden. Ein Skill für eine Mobile-App sieht anders aus als einer für eine Web-App, einer für eine Kunden-App anders als einer für ein internes Tool.
- Konfidenzniveau: Die Zahl denkt sich das LLM komplett selbst aus. Trotzdem hilft sie ihm, die Anforderungen kritisch zu hinterfragen. Und sie gibt uns für jedes Epic einen Anhaltspunkt, ob Claude mit der Umsetzung loslegen kann.
- Format: Wir können dem Skill alle möglichen Formatierungswünsche für unsere PRDs mitgeben. Wir könnten ihn sogar das PRD über eine MCP-Verbindung in Jira oder Notion schreiben lassen, sobald es 80 % erreicht.
- Dokumentation: Es lohnt sich immer, Claude auf seine eigene Dokumentation hinzuweisen. Das Modell weiß nicht unbedingt, was sich zuletzt geändert hat, und übersieht sonst womöglich Funktionen, die es nutzen könnte.
- Commit: Es ist einfach gute Praxis, den Agenten seine Arbeit selbst versionieren zu lassen. Er kann auch mal etwas kaputt machen – genau wie ein echter Engineer.
Inzwischen sollte der Brainstorm-Skill fertig sein. Führe `/reload-skills` aus, damit er in deiner aktuellen Session verfügbar ist.
Zeit, Claudes Kopf freizuräumen und neu anzufangen. Niemand arbeitet gern mit vollem Kopf, nicht einmal eine KI. Der Befehl dafür heißt `/clear` – ich weiß, sehr kreativ.
Die nächsten Skills
Wie in der klassischen Softwareentwicklung ist auch das Programmieren mit KI ein Kreislauf.
Du brainstormst ein Feature und arbeitest es zu einem PRD aus.
Du überlegst, wie du die Idee technisch umsetzt und wie du testen kannst, ob sie sich so verhält, wie sie soll.
Du setzt sie um, mit allen nötigen Tests und den Akzeptanzkriterien, die du vorher festgelegt hast.
Du prüfst sie. Du stellst sicher, dass sich ein Nutzer wirklich durchklicken kann – nicht nur per Tests, sondern auch mit einem Agenten, der einen echten Browser bedient.
Für den ersten Schritt haben wir schon einen Skill, die anderen erstellen wir jetzt. Du kannst dafür mehrere Claude-Sessions parallel öffnen und die Prompts dort einfügen.
Skill: write-spec
Based on Claude Code Documentation, please create a new skill called "write-spec". "write-spec" skill will take an input of a PRD file with an epic and will create an epic technical specification. Technical specification should include exact implementation steps to achieve requirements from the PRD and should apply TDD as a part of the development process.
If there are major architectural decisions to make, please add them as open questions at the end of the technical specification file.
Provide four options, with one option labeled as the recommended option. Each option should be provided [ ] so I can select an option. Ask me questions until all major architecture decisions are done for this technical specification.
Inzwischen hast du sicher gemerkt, wie das Erstellen von Skills funktioniert: Du sagst ganz einfach, was du willst – in deinen eigenen Worten. Es soll zuerst die Tests schreiben und genaue Schritte festhalten? Dann sag es.
Skill: implement-epic
Dafür brauchen wir das Playwright-Plugin. Gib Folgendes in den Chat ein:
/plugin install playwright@claude-plugins-official
Du wirst gefragt, wo du es installieren willst. Wähl den User-Scope, dann kannst du es auch in anderen Projekten nutzen. Außerdem musst du `/reload-plugins` eingeben, damit Claude die Plugins erkennt – neue Sessions haben sie sofort.
Based on Claude Code Documentation, please create a new skill named "implement-epic", that takes an epic name as input, and executes agentic flow based on this prompt:
implement the technical specification of the given epic until all requirements of its PRD in `specs/prd/epic-{N}.md` are implemented and confirmed.
Follow this workflow:
1. Analyze specification.
2. Build tests According to the spec.
3. Implement the requirements.
4. Verify the implementation by running tests.
5. Fix issues until all tests are passing.
When all tests pass, finish Implementation and provide a report with covered AC (done/partly/not done).
Use playwright MCP to validate the epic visuals (use click through mode) at the end of implementation.
Ein Skill fehlt noch: `/verify-epic`. Den erstellen wir, sobald unsere erste Umsetzungsrunde durch ist.
Falls deine Sessions von vorhin noch offen sind, lade die Skills dort mit `/reload-skills` neu. Neue Sessions erkennen sie automatisch.
Tech-Spec erstellen und umsetzen
Zeit für unsere technische Spezifikation. Im Grunde ist es derselbe Ablauf wie beim PRD, nur mit Blick auf die technische Umsetzung. Los geht's.
/write-spec epic 1
Claude plant jetzt die Umsetzung bis ins Detail und schreibt – wie beim Brainstorm-Skill – offene Fragen ans Ende. Die Datei heißt dann zum Beispiel „spec“ oder landet sogar in einem eigenen Unterordner von specs. Bei mir hat Claude dort einen Ordner `tech-spec` angelegt.
Wenn du neugierig bist, wie der Agent denkt und abwägt, nimm dir die Zeit und lies die Datei durch. Mit diesem Schritt sorgen wir dafür, dass der Agent sich überlegt, wie er das Feature baut, statt einfach drauflos zu improvisieren.
Markiere deine Entscheidungen mit einem X, geh zurück in den Chat und schreib „fertig“ oder „weiter“ – oder führe `/write-spec epic 1` einfach noch einmal aus. Richtig oder falsch gibt es hier nicht. Je nachdem, ob alle Lücken geschlossen sind, kommt noch eine zweite Fragerunde. Vergiss nicht: Du sprichst mit einer KI, die sich auch schwierigere Fragen einfallen lässt. ;)
Jetzt arbeiten die Agenten für uns
Wenn du die letzte Fragerunde hinter dir hast, hast du dir eine Pause verdient – und wir können endlich den Agenten übernehmen lassen.
Vorher solltest du sicherstellen, dass
- dein Laptop oder Rechner am Strom hängt,
- der Auto-Modus aktiviert ist,
- wirklich alle Fragen in deiner Tech-Spec beantwortet sind.
Wenn das alles passt, kannst du die Umsetzung starten.
/implement-epic epic 1
Während die Tests laufen, öffnen und schließen sich Browserfenster. Das ist normal – das bin nicht ich, der auf deinen Rechner zugreift.
Jetzt hol dir einen Kaffee und lass den Agenten zaubern. Bis gleich.
Nein, wirklich, mach etwas anderes. Das dauert eine Weile.
Zeit, die Ergebnisse zu prüfen
Wie war der Kaffee, was hast du gemacht? Ich hoffe, du hast nicht auf den Bildschirm gestarrt und zugeschaut, was der Agent genau macht.
Gewöhn dir das gar nicht erst an. Wie auch immer – schauen wir uns das Ergebnis an.
Öffne http://localhost:3000/ in deinem Browser. Wenn die Seite nicht lädt, starte deinen Server in einem separaten Terminal (neu) mit:
npm run dev
Die Anwendung in deinem Browser sollte jetzt so aussehen:
Natürlich solltest du deine App auch selbst benutzen und testen. Aber willst du wirklich jedes Mal alles durchtesten? Ich auch nicht. Dafür haben wir Tests – und zusätzlich können wir die KI durchklicken lassen, um sicherzugehen, dass unser Epic nichts kaputt gemacht hat.
Auf dem Weg dahin zeige ich dir noch etwas: wie du deine Skills anpasst. Denn irgendwann willst du im Implement-Skill eine Fortschrittsanzeige, eine Slack-Nachricht, wenn er fertig ist, oder Updates in Jira …
Als wir den Skill `/implement-epic` erstellt haben, haben wir festgelegt, dass er die App mit Playwright durchklickt und Tests ausführt. Das wollen wir jetzt nicht mehr, denn gleich erstellen wir den Skill `/verify-epic`, der genau das und noch mehr übernimmt.
Das ist ganz einfach: Wir sagen es einfach. Wenn wir jetzt den Skill zum Prüfen des Epics erstellen, schreiben wir im zweiten Absatz, dass unnötige Tests im implement-epic-Skill reduziert werden sollen.
Please create a new skill verify-epic, that will execute relevant epic tests (unit/integration/functional/e2e) and run playwright feature click through. If I pass key --screenshots I want that playwright takes screenshots and places them into e2e/screenshots folder.
verify-epic skill should take epic name as input parameter and operate with the selected epic, and wire verify-epic skill into implement-epic skill so that at the very end of implementation it runs full epic QA. You can reduce unnecessary testing that is currently present in the implement-epic skill that will be covered by this change. During step/task implementation we should execute only light weight testing, not full epic e2e test suite.
Make sure that we run verify epic skill, at the very end of implement epic skill, and based on the verify epic skill we fix all issues until it's done.
So kannst du jeden Skill ändern: Du sagst der KI einfach, was sie tun soll.
Wenn alle Skills eine `status.md` im specs-Ordner pflegen sollen, sag es Claude.
Sobald der Skill erstellt ist, führen wir ihn aus und schauen, ob die Tests durchlaufen.
/verify-epic epic 1 --screenshots
Mach dich wieder auf ein paar aufpoppende Fenster gefasst. Und weil wir `--screenshots` mitgegeben haben, findest du im e2e-Ordner auch Screenshots – praktisch für die weitere Entwicklung. Vielleicht siehst du auch, dass die Anwendung in verschiedenen Auflösungen getestet wurde. All das kannst du genauer festlegen, indem du den Skill an deinen tatsächlichen Bedarf anpasst.
Willst du es noch cooler? Finde heraus, wie Claude ein Video vom Testlauf aufnimmt und in einem Ordner in deinem Repo speichert.
Und Epic 2?
Epic 2 überlasse ich dir. Der Ablauf ist genau derselbe.
Zuerst brainstormst du mit `/brainstorm epic 2` und stellst sicher, dass der Agent versteht, was du umsetzen willst.
Wenn keine Fragen mehr offen sind, erstellst du mit `/write-spec epic 2` die Tech-Spec. Auch hier beantwortest du Fragen, bis keine mehr übrig sind, und übergibst dann an `/implement-epic epic 2`.
Dann ist es Zeit für den nächsten Kaffee oder eine Pause. Gewöhn dir nicht an, dem Agenten bei der Arbeit zuzuschauen. Sonst bringt dir die KI nichts.
Und `/verify-epic` – musst du das ausführen? Nein, denn beim Erstellen haben wir festgelegt, dass der Skill immer nach `/implement-epic` läuft. Falls das aus irgendeinem Grund nicht klappt, würde ich zuerst in `.claude/skills/verify-epic/SKILL.md` nachsehen, ob `disable-model-invocation` auf `true` steht, und es auf `false` setzen.
Was das bedeutet, findest du selbst heraus – und wenn nicht, frag Claude. ;)
Und nach Epic 2 überlegst du, was du noch in dein Tool einbauen willst, und startest `/brainstorm epic 3`.
Zum Schluss
Das war's. Du hast jetzt das Rüstzeug für Agentic Engineering bzw. Spec-Driven Development. Aber das ist erst der Anfang.
Von hier aus wirst du unzählige Möglichkeiten entdecken. Das Wichtigste ist, dass du experimentierst, deine Skills immer wieder durchgehst und sie verbesserst, wo es geht.
Der Ablauf, den ich dir gezeigt habe, ist nicht perfekt. Die Dateinamen für die Spec sind nicht ideal, sie liegen nicht sauber in einem Ordner pro Epic … und gehört das überhaupt in Dateien oder nicht eher in Tickets in Jira oder Linear?
Das ist Absicht. Diese vier Skills sind ein Ausgangspunkt. Du fängst hier an und passt sie unterwegs an.
Die Alternative wäre eine schwergewichtigere Lösung wie spec-kit oder ein anderes fertiges Harness. Dann verbringst du erst einmal eine Weile damit, es zu verstehen, statt einfach etwas fertigzubekommen. Den Ansatz, den du heute gelernt hast, kannst du dagegen sofort nutzen – auch in einem bestehenden Repository.
Übrigens: Wir haben uns den Code kein einziges Mal angeschaut. Das kannst du jederzeit tun, und ich wette, du wirst positiv überrascht sein. Mir geht es heute nicht um eine Diskussion über Codequalität, sondern darum zu zeigen, wie Spec-Driven Development funktionieren kann.
Wenn du es bis hierher geschafft hast, freue ich mich über deine Rückmeldung: Wie ist es gelaufen? Was hat funktioniert, was nicht?
Wenn du tiefer einsteigen willst: Ich biete auch Workshops zu Agentic Engineering an, remote und vor Ort. Mehr dazu findest du hier.