Wie mein Agenten-System wirklich funktioniert

Eine Kundin hat mich gefragt, wie mein Setup funktioniert.

Sie hat eine Aufgabe zu automatisieren (Bug-Eingang aus Sentry, Triage mit einem LLM, Ticket-Erstellung in Jira, Benachrichtigung in Slack) und wollte wissen, wie ich das bauen würde. Wir haben am Ende eine Stunde am Bildschirm verbracht. Mir wurde klar, dass ich dasselbe erklärte, wonach ich jede Woche gefragt werde.

Hier ist die schriftliche Version, länger als die am Telefon, weil das Telefonat ständig von “warte, was ist das” unterbrochen wurde.

Die drei Teile

Es gibt drei Komponenten. Keine davon ist für sich genommen clever. Die Arbeit steckt darin, wie sie nebeneinander sitzen.

Ein IDE. Ich nutze VS Code. Jeder Editor mit Agenten-Integration funktioniert. Das IDE ist dort, wo die Dateien leben, wo die Änderungen passieren, wo der Agent tatsächlich etwas tun kann, statt nur darüber zu reden.
Ein Agent im IDE. Ich nutze Claude Code. Der Agent liest und schreibt Dateien, führt Befehle aus und spricht über Werkzeuge mit externen Systemen. Es ist kein Chatbot. Es ist ein Prozess mit Händen.
Orchestratoren auf der anderen Seite. n8n, Make, eigener Code auf einem Server. Der Agent verbindet sich mit ihnen und konfiguriert sie, damit die langlaufenden Automationen ohne mich laufen.

Das Muster ist immer dasselbe. Du sitzt im IDE. Der Agent liest dein Projekt, stellt Fragen, bearbeitet Dateien, ruft APIs auf und meldet zurück. Wenn du etwas willst, das draußen in der Welt von allein läuft, geht der Agent hin und verdrahtet es im Orchestrator.

Warum ein leerer Arbeitsbereich plus KI nicht das System ist

Das ist der Teil, den die meisten beim ersten Versuch übersehen.

Du kannst Claude in einem Browser-Tab öffnen und es bitten, eine Automation zu bauen. Du kannst Claude Code in einem leeren Ordner öffnen und es ein Projekt aufsetzen lassen. Beides funktioniert ein bisschen und bricht schnell. Der Grund ist, dass das Modell keine Ahnung hat, wie deine Arbeit aussieht.

Die Hälfte dessen, was ich jeden Tag mache, ist, die Hülle zu verbessern, in der der Agent sitzt. Eine Beschreibung, wie meine Projekte aufgebaut sind. Regeln, was zu tun ist, bevor er mir eine Frage stellt. Fähigkeiten, die in bestimmten Situationen geladen werden. Speicher, der über Sitzungen hinweg überlebt. Fest verdrahtete Prüfungen, die genau die Fehler abfangen, die der Agent vorher gemacht hat.

Wenn mein Agent in etwas gut ist, liegt es meist daran, dass diese Hülle von zwanzig Sitzungen voller Fehler geformt wurde. Das Modell ist dasselbe Modell. Was sich geändert hat, ist die Hülle.

Die vier Ebenen: Regeln, Fähigkeiten, Befehle, Hooks

Wenn Leute mein Setup sehen, fragen sie, wo die Magie steckt, und erwarten eine clevere Datei. Es gibt keine clevere Datei. Es gibt vier Ebenen, und der Trick besteht darin, zu wissen, auf welche Ebene ein bestimmtes Verhalten gehört.

Regeln sind die unterste Ebene. Eine Regel ist Text, den der Agent liest: “Bevor du mir eine Frage stellst, probier zuerst das Naheliegende.” Billig zu schreiben, leicht zu ändern. Der Haken ist, dass eine Regel nicht deterministisch ist. Der Agent liest sie, deutet sie und befolgt sie meistens. Meistens. In einem gewissen Anteil der Fälle liest er einfach darüber hinweg.

Fähigkeiten sind das, was du bekommst, wenn sich mehrere Regeln um eine Aufgabe sammeln. Genug Regeln darüber, wie man eine E-Mail schreibt, und es ist nicht mehr lose Anleitung, sondern eine benannte Fähigkeit, die der Agent laden kann, wenn diese Aufgabe auftaucht. Immer noch vom Modell gelesen, immer noch deutbar, aber gebündelt und wiederverwendbar.

Befehle sind vordefinierte Prompts, die eine feste Abfolge von oben nach unten durchlaufen. Der Unterschied zwischen “führe diesen Befehl aus” und denselben Worten als normale Nachricht ist echt. Als loser Prompt überfliegt der Agent und improvisiert. Als Befehl ausgeführt, geht er die Schritte der Reihe nach durch, hält an, um die klärenden Fragen zu stellen, die du ihm aufgetragen hast, und überspringt nicht still den Schritt, der dir wichtig war. Wenn ein Ablauf eine Reihenfolge hat, auf die es ankommt, will er ein Befehl sein.

Hooks sind die oberste Ebene und die einzige deterministische. Ein Hook ist ein kleines Stück Python, das bei einem Auslöser feuert, jedes Mal, ob das Modell “Lust hatte” oder nicht. Hier legst du das Verhalten ab, das nicht scheitern darf. Regeln und Fähigkeiten sind Ratschläge. Ein Hook ist ein Gesetz.

Die Ebenen sind kein Menü, aus dem du einmal wählst. Sie sind eine Pipeline. Ein Verhalten beginnt als Regel. Wenn ich mich oft darauf stütze oder es ständig umschreibe, sammeln sich die Regeln zu einer Fähigkeit. Wenn eine Fähigkeit ständig genutzt wird oder immer wieder von dem abweicht, was ich eigentlich will, ist das das Signal, sie auf einen Hook anzuheben und deterministisch zu machen. Das System sagt dir, wann etwas eine Ebene höher muss: je öfter ein Fehler wiederkehrt, desto höher die Ebene, auf die seine Behebung gehört.

Was ein Hook tatsächlich tut

Drei von meinen, zur Veranschaulichung:

Einer wacht über den Moment, in dem der Agent versucht, mir eine Aufgabe zurückzugeben. In der Sekunde, in der er anfängt zu sagen “du solltest X erledigen”, greift der Hook ein und lässt ihn prüfen, ob er tatsächlich selbst den Zugriff hat, X zu tun. Meistens hat er ihn. Dieser eine Hook ist der größte Teil des Unterschieds zwischen einem Werkzeug, das mir Hausaufgaben gibt, und einem Werkzeug, das die Arbeit erledigt.
Einer erzwingt am Ende jeder Sitzung eine Synchronisierung mit Git. Diesen Hook gibt es, weil eine Sitzung einmal stundenlang lief, hunderte Dateien bearbeitete und keine davon hochlud. Ich habe es erst später bemerkt. Jetzt darf das nicht mehr passieren, weil es kein Ratschlag mehr ist, sondern Code.
Einer ist ein Sicherheitstor. Wenn der Agent in einem Kontext arbeitet, der als Live-Produktion markiert ist, werden Änderungen blockiert und die Sitzung wird gestoppt, bevor irgendetwas live geht. Diesen installiere ich inzwischen auch für Kunden. Du willst nicht, dass der Unterschied zwischen “Entwurf” und “live” davon abhängt, ob das Modell aufpasst.

Der ehrliche Grund, warum es Hooks gibt, ist Halluzination. Das Modell ist hervorragend und tut trotzdem in einem gewissen Prozentsatz der Fälle selbstbewusst das Falsche. Du kannst diesen Prozentsatz nicht auf null prompten. Du kannst die Dinge, auf die es ankommt, über eine Ebene leiten, auf der der Prozentsatz nicht gilt.

Das berühmte kleine Beispiel ist der lange Gedankenstrich. Modelle lieben ihn, und es gibt keine Taste auf der Tastatur, die ihn erzeugt, also ist er ein Fingerabdruck dafür, dass ein Text durch eine KI gelaufen ist. Ich kann eine Regel schreiben, die ihn verbietet. Das Modell wird ihn trotzdem ab und zu produzieren. Was wirklich hält, ist ein Hook, der ihn beim Hinausgehen entfernt.

Sitzungen, Checkpoints und den Faden nicht verlieren

Eine Sitzung ist ein durchgehendes Gespräch mit dem Agenten innerhalb eines Projekts. Je länger sie läuft, desto mehr Kontext trägt sie, und irgendwann ist der Kontext voll. Dann ist das Standardverhalten, zu komprimieren: Der Agent fasst das bisherige Gespräch zusammen und macht aus der Zusammenfassung weiter. Für einen Chat ist das in Ordnung. Es ist ein stilles Desaster, wenn das Detail, das er wegfasste, genau das war, das du brauchtest, vor allem, wenn deine echte Kommunikation und deine Entscheidungen im System leben und exakt bleiben müssen.

Also lasse ich es nicht still komprimieren. Bevor der Kontext voll ist, führe ich einen Checkpoint-Befehl aus. Er schreibt eine Checkpoint-Datei: was wir getan haben, was noch offen ist, was kaputtging, was ich entschieden habe. Die nächste Sitzung beginnt damit, diese Datei zu lesen, und startet so mit dem echten Kontext statt mit einer verlustbehafteten Zusammenfassung. Der Faden überlebt die Übergabe.

Das hält auch Projekte davon ab, ineinander zu bluten. Jedes Projekt hat seinen eigenen Geltungsbereich. Die Blog-Arbeit sieht die Kundenarbeit nicht und kann die beiden nicht verwechseln, weil die Sitzungen getrennt sind und jede nur ihren eigenen Kontext lädt.

Der Kreislauf, der das System selbst verbessert

Die Checkpoints speisen den Teil, an dem ich am meisten hänge.

Jeder Checkpoint protokolliert die Reibung: die Momente, in denen der Agent etwas tat, das ich korrigieren musste. Wenn sich genug davon angesammelt hat, lasse ich einen Entwicklungsdurchlauf über das ganze System laufen. Er liest die gesamte Reibung seit dem letzten Durchlauf und behebt die konkreten Fehler. Dann tut er das, worauf es eigentlich ankommt: Er tritt einen Schritt zurück und fragt, ob dieselbe Art von Fehler immer wieder auftaucht, weil das Design darunter falsch ist. Behebe die drei Bugs, dann frage, ob die drei Bugs in Wirklichkeit eine schlechte Annahme in drei Mänteln sind.

Das ist der Unterschied zwischen einem Setup, das langsam besser wird, und einem, das langsam verworrener wird. Den Bug zu beheben räumt heute auf. Das Design zu beheben ist das, was dich davon abhält, denselben Bug zum zwanzigsten Mal zu beheben.

Eine Anmerkung zur Eingabe, weil sie all das speist: Ich spreche weit mehr mit dem System, als ich tippe. Spracheingabe ist schneller und reicher, und reichere Eingabe ergibt bessere Ausgabe. Einer meiner Hooks bemerkt sogar, ob eine Anweisung per Stimme oder per Tastatur kam, weil sich die beiden unterschiedlich lesen und es verdienen, unterschiedlich behandelt zu werden.

Wie ich ein neues Projekt tatsächlich beginne

Die Kurzfassung: Ich lege eine einzige Markdown-Datei in den neuen Ordner, richte den Agenten darauf aus und lasse ihn den Rest aufsetzen.

Die Datei beschreibt die Form des Projekts. Was es ist. Welches Problem es löst. Wie das Layout aussieht. Welche Regeln der Agent befolgen soll. Was “fertig” für eine typische Änderung bedeutet. Es sind zwei Seiten, nicht zehn.

Der Agent liest die Datei, stellt seine Fragen und beginnt, die Struktur zu bauen. Die nächsten dreißig Minuten verbringe ich damit, das Aufgesetzte zu kritisieren. Die Kritik geht als neue Regeln zurück in die Markdown-Datei. Die nächste Sitzung ist schärfer, weil die vorige aufgeschrieben wurde.

Nach sechs Monaten habe ich eine Hülle, die meine Stimme kennt, meine Projekte, meine Werkzeuge, meine Fehlerquellen. Die Arbeit daran summiert sich. Die Arbeit, die ich beim zwanzigsten Mal mit demselben Fehler gehabt hätte, nicht.

Die Falle, und was das wirklich kostet

Die Falle ist, den Agenten auf einer Infrastruktur laufen zu lassen, die du nicht verstehst.

Er wird Dinge produzieren. Dateien tauchen auf. Workflows werden konfiguriert. APIs werden aufgerufen. Wenn du nicht lesen kannst, was er geschrieben hat, besitzt du nicht, was er gebaut hat. Beim ersten Mal, wenn etwas bricht, hast du nichts, woraus du debuggen kannst. Die Spur ist die Hülle plus der Code plus dein Verständnis von beidem. Nimm eines der drei weg, und du mietest nur ein Ergebnis.

Es gibt einen zweiten, leiseren Preis, bei dem ich ehrlich sein sollte. Ein so geformtes System ist mächtig und fragil zugleich. Es ist eng damit verdrahtet, wie ich arbeite, wie ich denke, wie ich Dinge formuliere. Ich habe versucht, eine abgespeckte Version an jemanden zu übergeben, der eng mit mir arbeitet, und sie hat größtenteils nicht gegriffen, weil der Wert nie nur die Dateien waren. Der Wert waren sechs Monate meiner spezifischen Korrekturen, die in ihnen leben. Du kannst das Ergebnis nicht klonen. Du kannst nur dein eigenes wachsen lassen.

Das deutet darauf, was meine Arbeit tatsächlich geworden ist. Ich schreibe inzwischen fast keinen Code mehr und lese sehr wenig davon. Was ich tue, ist den Kontext halten, prüfen, ob das Zurückkommende stimmt, und das Ding in die richtige Richtung weisen. Das System ist der Arbeiter. Ich bin der, der weiß, ob die Arbeit richtig ist und wohin sie als Nächstes soll. Das ist eine seltsame Rolle, in die man hineinwächst, und es ist die echte.

Die ehrliche Version von “mit KI schneller liefern” lautet: Du gibst die Zeit, die du sparst, dafür aus, das System zu bauen, das dir erlaubt, der Geschwindigkeit zu vertrauen. Das ist ein fairer Tausch. Kein kostenloser.

Ein Start-Prompt zum Einfügen

Wenn du das heute ausprobieren willst, leg das Folgende in eine CLAUDE.md-Datei im Wurzelverzeichnis eines leeren Ordners, öffne sie in Claude Code und sag dem Agenten, er soll die Datei lesen und ein Gerüst vorschlagen. Bearbeite die Datei unterwegs. Sie soll wachsen.

# Project

What this is: [one sentence]
Why it exists: [one sentence]
What done looks like: [one sentence per milestone]

## Stack

Language: [e.g. TypeScript / Python / Go]
Frameworks: [e.g. Astro, FastAPI, Hono]
Hosting: [e.g. Cloudflare Pages, Railway, Vercel]
External services: [e.g. Stripe, Supabase, Sentry, N8N]

## How I work with the agent

- Before asking me a question, try the obvious thing first.
- After two failed attempts at the same fix, stop and explain what is happening.
- Never run destructive commands without confirming.
- When you make a change, tell me which files changed and why.
- When you finish a task, summarize in one sentence.

## House rules

- No emojis in code or commits.
- No em-dashes in any prose output.
- Match the voice of existing files.
- If a pattern exists in the codebase, reuse it instead of inventing a new one.

Diese Datei ist der Samen. Sie ist eine Regeldatei, die unterste Ebene. Du ergänzt sie jedes Mal, wenn der Agent etwas tut, das du nicht wolltest, und jedes Mal, wenn er etwas tut, das du behalten willst. Wenn eine Regel zu viel Gewicht trägt, ist das dein Stichwort, sie zu einer Fähigkeit zu befördern und irgendwann zu einem Hook.

Das System ist nicht der Agent. Es ist das, was du darüber aufschreibst, wie du arbeitest, damit der Agent aufhört zu raten.

Wenn du mehr als den Samen willst, habe ich eine ausführlichere Version mit Installationsanleitung und der Struktur, die um diese Datei herum wächst, zusammengestellt. Siehe richte deinen eigenen Agenten-Arbeitsbereich ein für die Anleitung und den Download.