Claude Code nutzen: Trennung von Planung und Ausführung

• Der Einsatz von AI-Coding-Tools wird grundlegend neu strukturiert: Vorgestellt wird ein Workflow, der vor dem Schreiben von Code zwingend eine explizite Phase zur Überprüfung des Plans vorsieht
• Das Kernprinzip lautet: „Claude darf keinen Code schreiben, bevor der Plan freigegeben ist“. Dadurch werden strukturelle Kontrolle und ein effizienter Token-Einsatz erreicht
• Der gesamte Prozess verläuft als Kreislauf aus Research → Plan → Annotation → Todo List → Implementation → Feedback
• In jeder Phase wird rund um Markdown-Dokumente (research.md, plan.md) zusammengearbeitet; durch Kommentare und wiederholte Überarbeitungen steigt die Qualität
• Dieser Ansatz fokussiert sich darauf, die Ausführungskraft der AI und das Urteilsvermögen des Menschen zu trennen und zugleich zu verbinden, um auch in komplexen Systemen stabile und konsistente Ergebnisse zu erzielen

---

Überblick über den gesamten Workflow

• Über rund 9 Monate hinweg wurde Claude Code als primäres Entwicklungstool genutzt; statt des üblichen Musters „Prompt eingeben → Code generieren → wiederholt nachbessern“ wurde ein systematisches Verfahren mit getrennter Planung und Ausführung aufgebaut
• Bevor Claude Code schreibt, darf es nur auf Basis eines vom Autor geprüften und freigegebenen Plan-Dokuments (plan.md) arbeiten
• Dieser Ansatz reduziert unnötige Trial-and-Error-Schleifen, bewahrt die Entscheidungshoheit über die Architektur und maximiert die Qualität im Verhältnis zum Token-Verbrauch

Phase 1: Research

• Jede Aufgabe beginnt mit einer tiefgehenden Analyse der Codebasis
  • Claude wird angewiesen, bestimmte Ordner oder Funktionen „gründlich zu lesen“ und detailliert zu analysieren
  • Die Ergebnisse müssen stets in einer Datei research.md festgehalten werden
• Dieses Dokument dient als Review-Oberfläche, um Claudes Verständnis zu überprüfen; Missverständnisse werden in dieser Phase korrigiert
• Da fehlerhafte Recherche zu fehlerhafter Planung und Implementierung führt, wird hier der teuerste Fehlerfaktor frühzeitig abgefangen
• So lassen sich zum Beispiel Probleme vermeiden wie das Ignorieren einer Caching-Schicht, das Nichtbeachten von ORM-Regeln oder die Erzeugung doppelter Logik

Phase 2: Planning

• Nach der Prüfung der Recherche lässt man Claude einen detaillierten Implementierungsplan (plan.md) erstellen
  • Einschließlich konkreter Code-Snippets, zu ändernder Dateipfade und Trade-offs
  • Statt des eingebauten Plan-Modus wird eine selbst verwaltbare Markdown-Datei verwendet
• Wenn zusätzlich eine Open-Source-Referenzimplementierung bereitgestellt wird, verbessert sich die Qualität von Claudes Plan deutlich
• Noch wichtiger als das Plan-Dokument selbst ist der anschließende Annotation-Zyklus

Annotation-Zyklus

• Der Autor öffnet plan.md und fügt direkt Inline-Kommentare hinzu
  • Korrektur falscher Annahmen, Ablehnung von Ansätzen, Ergänzung von Domain-Wissen usw.
  • Zum Beispiel: „Das muss PATCH sein“, „Caching ist unnötig“, „Das Feld visibility sollte auf Listenebene verschoben werden“
• Anschließend wird Claude angewiesen, „das Dokument anhand der Kommentare zu aktualisieren, aber noch nicht zu implementieren“
• Dieser Kommentar-Aktualisierungs-Zyklus wird 1 bis 6 Mal wiederholt, wobei der Befehl „don’t implement yet“ eine vorzeitige Ausführung verhindert
• Das Markdown-Dokument fungiert als teilbarer Zustand, der klarer und strukturierter ist als rein dialogbasierte Anweisungen
• Durch die Iteration entwickelt sich ein allgemeiner Plan zu einer Spezifikation, die perfekt auf das reale System passt

Erstellen der Todo List

• Vor der Implementierung lässt man Claude eine detaillierte Aufgabenliste (Todo List) ergänzen
  • Mit konkreten Teilaufgaben pro Schritt, um den Fortschritt nachzuverfolgen
  • Da Claude erledigte Punkte markiert, bleibt der Status auch in langen Sessions leicht nachvollziehbar

Phase 3: Implementation

• Sobald alle Entscheidungen feststehen, erfolgt die Ausführung per standardisiertem Prompt
  • Etwa: „Nicht anhalten, bis alle Aufgaben abgeschlossen sind“, „keine unnötigen Kommentare“, „keine Typen any/unknown“, „fortlaufende Typechecks durchführen“ usw.
• Dieser Schritt ist eine mechanische Phase, die den Plan unverändert ausführt; kreative Entscheidungen sind dann bereits gefallen
• Wer ohne Plan direkt implementiert, baut Code auf falschen Annahmen auf; deshalb ist die Regel „don’t implement yet“ ein zentraler Sicherheitsmechanismus

Feedback während der Implementierung

• Während der Ausführung wechselt der Autor in die Rolle eines Supervisors
  • Feedback wird kurz und klar gegeben: „Diese Funktion fehlt“, „in die Admin-App verschieben“ usw.
  • Bei Frontend-Änderungen genügen kurze Anweisungen wie „breiter“, „2px Abstand“ oder Screenshots
• Häufige Bezugnahme auf bestehenden Code hilft dabei, eine konsistente UI/UX zu erhalten
• Läuft die Arbeit in die falsche Richtung, ist git revert und ein neuer Versuch mit kleinerem Scope oft wirksamer als schrittweises Nachbessern

Am Steuer bleiben

• Claude erhält keine vollständige Autonomie; die endgültigen Entscheidungen trifft immer der Mensch
• Aus Claudes Vorschlägen werden nur Teile ausgewählt oder diese werden geändert, gelöscht oder technisch neu definiert
  • Zum Beispiel: „Beim ersten Promise.all verwenden“, „den vierten und fünften Punkt ignorieren“
  • „Download-Funktion entfernen“, „Funktionssignatur nicht ändern“, „Methode aus einer bestimmten Library verwenden“ usw.
• Claude übernimmt die mechanische Ausführung, der Mensch Beurteilung und Priorisierung

Eine einzige lange Session

• Von Research bis Implementierung wird alles in einer einzigen langen Session durchgehend erledigt
  • Während der Session sammelt Claude fortlaufend Kontext; dank Auto-Compaction bleibt genügend Zusammenhang erhalten
  • plan.md bleibt über die gesamte Session hinweg vollständig erhalten und kann jederzeit referenziert werden

Kernaussagen

• „Lies gründlich, schreibe einen Plan, verfeinere ihn mit Kommentaren und führe dann alles in einem Zug aus.“
• Auch ohne komplexe Prompts oder Systemanweisungen lässt sich durch eine disziplinierte Pipeline, die Thinking und Typing trennt, hohe Qualität sichern
• Research verhindert uninformierte Änderungen, Plan verhindert falsche Änderungen, und Annotation bringt menschliches Urteilsvermögen ein
• Die finale Ausführung erfolgt erst, nachdem alle Entscheidungen feststehen, als automatisierter Prozess, wodurch eine effiziente Kollaborationsstruktur entsteht

[naka98]

Ich habe mit ähnlichen Problemen ebenfalls ständig zu tun. Wenn man mit der KI nur auf Chat-Basis zusammenarbeitet, werden die Zerlegung in Arbeitseinheiten (WBS), der Fortschritt und die Dokumentation von Entscheidungen schnell unklar.

[pcj9024]

Wenn man die Planungsdatei einfach ins Repository legt und die durch die Ausführung dieses Plans entstandenen Änderungen speichern lässt, bleibt der Kontext ziemlich gut erhalten.

[geekbini]

Das gilt nicht nur für Claude; es scheint sich allgemein auch auf andere CLI-basierte KI-Dienste anwenden zu lassen.

[GN⁺]

Hacker-News-Kommentare

• Der eigentliche Kern ist nicht „plant man oder nicht“, sondern Annahmen sichtbar zu machen, bevor das Modell sie in Code gießt
  LLMs scheitern weniger an Syntax als an unsichtbaren Prämissen wie Architektur oder Randbedingungen. Ein dokumentierter Plan schafft daher eine Oberfläche, auf der sich diese Prämissen debuggen lassen

  • In dieser Hinsicht ist eine Sub-Agenten-Struktur sehr hilfreich. Wenn einer plant, einer implementiert und ein weiterer reviewt, werden die Rollen klar. Das geht auch im Stil von Blue Team/Red Team. Letztlich geht es darum, dem LLM mit klareren Anweisungen zu helfen, richtig zu schlussfolgern
  • Wenn man den gesamten Use-Case-Ablauf in die Anweisungen aufnimmt, verhindert das, dass das Modell merkwürdige Dinge tut
  • Allerdings kann schon das Offenlegen solcher Annahmen selbst das Verhalten des Modells verändern. So wie ein einzelnes printf() einen Heisenbug verschwinden lassen kann
  • Kaum Syntaxfehler? Meine Erfahrung ist anders. Ich wollte in einem kleinen Rust-Projekt ein S3-Backend ergänzen, und Claude geriet in eine API-Halluzinationsschleife und verbrannte in 30 Minuten 20 Dollar. Und das wegen eines simplen Syntaxproblems
  • Ist dieser Beitrag vielleicht mit ChatGPT geschrieben worden?

• Es heißt, Claude lese nur dann nicht oberflächlich, wenn man Wörter wie „tiefgehend“ oder „detailliert“ benutzt, aber ehrlich gesagt ist intuitiv nicht nachvollziehbar, warum das so sein sollte

  • Das liegt am Attention-Mechanismus. LLMs wurden auf dem gesamten Internet trainiert, und Texte mit Formulierungen wie „achte auf die Details des Problems“ enthalten meist Antworten auf Expertenniveau. Solche Wörter führen also dazu, dass das Modell diese Daten stärker gewichtet. Deshalb funktionieren auch Prompts wie „verhalte dich wie ein MIT-Professor“
  • Diese Erklärung wirkt aber wie Aberglaube. Es gibt keine statistisch belastbare Evidenz dafür, und es fühlt sich fast nach magischem Denken an, als würde man dem Sonnengott Opfer darbringen. Wenn es wirklich wirkt, müsste man es als Optimierungsproblem nachweisen können, aber niemand veröffentlicht Daten dazu
  • Wir leben gerade in einer wirklich seltsamen Ära der Softwareentwicklung. Niemand weiß, warum LLMs sich so verhalten. Wir hoffen nur, dass Prompts die Wahrscheinlichkeiten in die richtige Richtung schieben. Früher war das Feld deterministisch, jetzt schreibt man Befehle fett in AGENTS.md-Dateien, als würde ein Elternteil mit einem Kind sprechen
  • Erstaunlich, dass Leute so etwas sehen und trotzdem noch ernst nehmen. Das ist fast Astrologie für Ingenieure
  • Wenn man den Latent Space des Modells als Landschaft versteht, wird es anschaulicher. Ein Prompt ist dann wie ein Ball, den man an einer bestimmten Stelle fallen lässt, und die Wortwahl bestimmt, in welches Tal er rollt. Formulierungen wie „tiefgehend“ halten den Ball eher in der gewünschten Region. Vielleicht keine perfekte Erklärung, aber mit diesem Bild hat es in der Praxis für mich gut funktioniert

• Ich nutze eine Struktur mit drei Dokumenttypen und zwei Skills
  Specs sind die statischen Designdokumente des Projekts, Plans sind die vom LLM erzeugten Ausführungspläne, und eine Working-memory-Datei verfolgt den Fortschritt.
  Mit dem Planner Skill von Gemini Pro erstelle ich neue Pläne, mit dem Implementer Skill von Codex führe ich sie aus.
  So bleibt der Kontext leichtgewichtig und fokussiert, was die Effizienz erhöht. Mit den 20-Dollar-Plänen von Codex/Gemini kommt man schon schnell genug voran

  • Ich verfolge einen ähnlichen Ansatz. Auf Basis von Papers erstelle ich Spec-Dateien und entwickle die Pläne im Austausch mit Claude weiter. Ich pflege Anforderungen–Tests–Definitionen wie in einem System-Engineering-Dokument im IEEE-Stil. Claude hält sich gut an Guardrails. Mir liegt Claude mehr als Codex
  • Guter Ansatz. Ich frage mich allerdings, ob ein Monorepo im AI-Zeitalter die bessere Wahl ist. Bei uns im Unternehmen sind mehrere Next.js-Apps auf verschiedene Repos verteilt, und wir überlegen, ob ein Zusammenlegen sinnvoller wäre

• Die Idee, direkt im Planungsdokument Kommentare zu hinterlassen, wirkt frisch. Mich würde interessieren, ob es eine Methode gibt, diese Kommentare separat zu speichern oder später für Reviews zu verwalten

• An diesem Ansatz gefallen mir einige Dinge nicht
  Erstens erzeugt der Big-Bang-Ansatz, bei dem aller Code auf einmal generiert wird, riesige Codeblöcke, die schwer zu verstehen sind. Ich halte es für besser, schrittweise zu planen und auszuführen.
  Zweitens finde ich es schade, dass man zwar Feedback gibt, aber die Wissensbasis nicht aktualisiert. Man sollte Fehlerursachen festhalten, damit sie sich beim nächsten Mal nicht wiederholen.
  Und schließlich fehlt jeder Hinweis auf Tests. Zumindest ein Teil von Test-driven Development (TDD) sollte enthalten sein. Es ist spannend, wie sich AI-unterstützte Entwicklung mit solchen Methoden verbinden wird

  • Ich habe Ähnliches erlebt. Ich teile PLAN.md in Phasen auf und formuliere die Prompts sorgfältig so, dass jeweils nur die aktuelle Phase ausgeführt wird. Tests sind ebenfalls Teil des Plans, ich füge sie bisher aber eher gegen Ende hinzu

• Dieser Workflow ist eigentlich die Standardmethode für Claude Code, die Anthropic empfiehlt. Der Nachteil ist allerdings, dass man von vorn anfangen muss, wenn der Plan nicht perfekt ist.
  Deshalb teile ich Design → Planung → Ausführung auf mehrere Batches auf. Wenn ein Planblock unter 1.500 Zeilen bleibt, lässt sich die Komplexität leichter beherrschen.
  Meine App mit 30.000 LOC hat 100.000 Zeilen Plan. Das kann man unmöglich auf einmal erzeugen

  • Ich habe dieselbe Erfahrung gemacht. Deshalb zerlege ich die Planung in kleinere Einheiten und verwalte Commits mit featurebezogenen Branches. Dank AI sind meine Entwicklungsgewohnheiten sogar besser geworden
  • Eigentlich ist es etwas peinlich, dass ein angeblich „radikal anderer“ Workflow am Ende nur der normale Plan-Modus ist
  • Ich glaube auch, dass schrittweise Ausführung die richtige Antwort ist. Ein riesiges Projekt in einem Zug fertigzustellen, ist immer noch bloße Illusion
  • Ein perfekter Plan ist gar nicht nötig. Man kann einfach die von der AI geänderten Teile zurückrollen und vom vorherigen Schritt aus erneut iterieren. Der Schlüssel ist, die Komplexität durch Änderungen in kleinen Einheiten zu senken
  • 100.000 Zeilen Plan sind fast eine Million Wörter. Allein das Lesen würde 66 Stunden dauern. Praktisch unmöglich

• Ich arbeite nicht mit plan.md, sondern mit ausführbaren Scaffolds und Validierungsschleifen im Zentrum des Prozesses
  Ich habe zusammen mit AI ein echtes Zahlungssystem namens Kolibri Tickets gebaut. Der Kern ist nicht, dass das Modell schnell Code tippt, sondern dass man Validierungsschleifen entwirft

  • früh ein lauffähiges Grundgerüst beibehalten
  • jeweils nur einen schmalen vertikalen Slice hinzufügen
  • prüfbare Artefakte wie Tests, Typen und Zustandsmaschinen erzwingen
  • Refactoring zur Routine machen
    So kommt man nicht nur zu einer „Geschwindigkeitsillusion“, sondern tatsächlich schneller zum Deployment. Ein Plan-Dokument ist eine Möglichkeit, einen gemeinsamen Zustand aufrechtzuerhalten, ein verifizierbarer Harness eine andere
  • Seit Code billiger geworden ist, peile ich ebenfalls 100 % Testabdeckung an. Ich führe statisches Typing in Python, Playwright-Tests und sogar Mutation Testing ein. Inzwischen lassen Agenten eine Stunde lang Schleifen laufen und liefern Code, der kaum noch nachgebessert werden muss

• Ich nutze Claude Code zur Vorbereitung von Vorlesungen
  Ich schreibe Vorlesungsnotizen in Quarto und lasse Claude sie in Slidev-Folien umwandeln. Danach gebe ich Feedback, indem ich in den Folien Kommentare wie „das in zwei Folien aufteilen“ oder „hier ein Bild hinzufügen“ hinterlasse.
  Solches kommentarbasiertes Feedback ist sehr mächtig. Es hilft stark bei Token-Distanz und beim Erhalt des Kontexts

  • Quarto selbst unterstützt doch schon viele Formate wie PowerPoint, PDF und HTML. Warum also Slidev? Könnte man Claude nicht einfach das Quarto-Dokument erneut erzeugen lassen?
  • Mich würde interessieren, ob das Feedback als Inline-Kommentare hinterlassen wird, also etwa so: # Diesen Teil in X ändern?
  • Weiß jemand, ob dieser Claude Skill als Open Source veröffentlicht wurde?

• Es gibt bereits Tools wie Amazons Kiro, Googles Antigravity, GitHubs Spec Kit und OpenSpec, die solche Funktionen bereitstellen

• Der teuerste Fehlschlag beim AI-unterstützten Programmieren ist nicht ein Syntaxfehler, sondern eine Implementierung, die teilweise funktioniert, aber das Gesamtsystem zerstört
  Deshalb füge ich früh eine brief.md hinzu, in der Problemdefinition, Zielmetriken und Abbruchkriterien für Features festgehalten werden. So lassen sich die Kosten verringern, die entstehen, wenn Business-Ziele und technische Umsetzung auseinanderlaufen