Claude-Code-Projekte strukturieren: der Workflow von Kickoff bis Deployment

Warum Struktur vor dem ersten Prompt entscheidet

Ein KI-Coding-Agent arbeitet mit dem Kontext, den er vorfindet. Fehlt eine dokumentierte Projektstruktur, rät er: Ordnerkonventionen, Namensgebung, Teststrategie, Architekturentscheidungen. Jede Session trifft dann leicht andere Annahmen – und nach zwei Wochen hast du ein Projekt, das aus fünf verschiedenen Handschriften besteht.

Struktur vor dem ersten Prompt heißt: Bevor Code entsteht, sind Projektziel, Stack, Konventionen und Grenzen schriftlich festgehalten. Das kostet am Anfang eine Stunde und spart später jede Session Erklärarbeit – denn der Agent liest die Regeln mit, statt sie zu erfinden.

CLAUDE.md als Projektregelwerk

Die CLAUDE.md ist die zentrale Regeldatei im Projektverzeichnis. Claude Code liest sie zu Beginn jeder Session – sie ist damit der Ort, an dem einmal definierte Regeln dauerhaft wirken, statt in jedem Prompt wiederholt zu werden.

Eine gute CLAUDE.md ist kurz und verbindlich: Was ist das Projekt, welcher Stack, welche Befehle für Build und Test, welche Konventionen gelten, was ist ausdrücklich verboten. Sie ist kein Handbuch, sondern ein Regelwerk – jede Zeile sollte eine Entscheidung dokumentieren, die der Agent sonst selbst treffen würde.

• Projektziel und Stack in wenigen Sätzen
• Build-, Test- und Lint-Befehle, die vor jedem Abschluss laufen müssen
• Code-Konventionen: Struktur, Benennung, bevorzugte Muster
• Verbote: was der Agent nie ändern oder committen darf (z. B. Secrets, Migrationsdateien, Konfigurationen)
• Definition of Done: wann eine Aufgabe als fertig gilt

Agentenrollen: Orchestrator, Builder, Reviewer, QA

Wer denselben Agenten planen, bauen und prüfen lässt, bekommt eine Prüfung ohne Distanz: Der Agent bewertet seine eigenen Annahmen mit denselben Annahmen. Rollentrennung löst das, indem jede Rolle eine eigene Perspektive und ein eigenes Mandat bekommt.

Der Orchestrator zerlegt die Aufgabe in Arbeitspakete und hält den Überblick. Der Builder setzt genau ein Paket um – nicht mehr. Der Reviewer prüft den entstandenen Code auf Korrektheit, Konventionen und Nebenwirkungen, ohne selbst zu bauen. QA testet gegen die Anforderungen: Läuft es, sind Randfälle abgedeckt, ist nichts anderes kaputtgegangen?

Der Effekt: Fehler werden dort gefunden, wo sie billig sind. Ein Reviewer mit eigenem Prompt-Mandat findet Probleme, die der Builder systematisch übersieht – nicht weil er klüger ist, sondern weil er nicht dieselben Annahmen im Kontext trägt.

Plan-Modus und Read-only-Regeln für sichere Sessions

Der teuerste Fehler in Agent-Sessions ist ungeprüftes Schreiben: Der Agent ändert zwanzig Dateien, bevor klar ist, ob der Ansatz überhaupt stimmt. Der Plan-Modus dreht die Reihenfolge um – erst lesen und planen, dann freigeben, dann ändern.

Praktisch heißt das: Jede nicht-triviale Aufgabe beginnt read-only. Der Agent analysiert den Code, legt einen Plan mit betroffenen Dateien und Schritten vor, und erst nach deiner Freigabe wird geschrieben. Für heikle Bereiche – Datenbank-Migrationen, Auth, Deployment-Konfiguration – gilt die Freigabepflicht dauerhaft, festgehalten in der CLAUDE.md.

Diese Regel ist toolneutral: Ob dein Werkzeug einen expliziten Plan-Modus hat oder du ihn per Anweisung erzwingst – das Prinzip „Plan vor Änderung, Freigabe vor Schreibzugriff“ funktioniert überall und veraltet nicht mit dem nächsten Release.

Die Review- und QA-Schleife vor jedem Merge

Kein KI-generierter Code geht ungeprüft in den Hauptbranch – das ist die wichtigste einzelne Regel im gesamten Workflow. Die Schleife dafür ist immer gleich: Builder liefert, Reviewer prüft, QA testet, dann erst wird gemergt.

Der Review prüft nicht nur, ob der Code funktioniert, sondern ob er ins Projekt passt: Konventionen eingehalten, keine ungewollten Änderungen an fremden Dateien, keine hart codierten Werte, keine stillen Abhängigkeitsänderungen. QA testet gegen die ursprüngliche Anforderung – inklusive der Frage, was der Change an bestehendem Verhalten verändert haben könnte.

Audit-Prompts und Checklisten machen diese Schleife wiederholbar: Statt jedes Mal frei zu prüfen, arbeitet der Reviewer eine feste Frageliste ab. Das dauert Minuten und fängt die Fehlerklassen ab, die in Agent-Projekten immer wieder auftreten.

Typische Anfängerfehler – und wie du sie vermeidest

Die häufigsten Probleme in Claude-Code-Projekten sind keine Modellfehler, sondern Prozessfehler. Drei tauchen fast überall auf.

Drauflos bauen: Ohne CLAUDE.md und ohne Plan-Phase produziert jede Session inkonsistenten Code. Die Lösung ist banal und wirksam – erst Regelwerk, dann Plan, dann Code.

Secrets im Repo: API-Keys oder Zugangsdaten landen im Code oder in Dateien, die der Agent liest und weiterverwendet. Secrets gehören in Umgebungsvariablen, die .gitignore muss stehen, bevor der erste Commit passiert, und die CLAUDE.md verbietet dem Agenten explizit, Credentials zu schreiben oder zu committen.

Kein Rollback-Plan: Wer ohne saubere Commit-Hygiene arbeitet, kann fehlerhafte Agent-Änderungen nicht rückgängig machen. Kleine, thematisch getrennte Commits und ein Branch pro Aufgabe sorgen dafür, dass jeder Schritt einzeln zurückrollbar ist – auch das eine Regel, die in die CLAUDE.md gehört.

• Kein Code ohne Regelwerk und Plan-Phase
• Secrets nie im Repo: Umgebungsvariablen plus .gitignore vor dem ersten Commit
• Ein Branch pro Aufgabe, kleine Commits, jeder Schritt einzeln zurückrollbar
• Review- und QA-Schleife vor jedem Merge – ohne Ausnahme

Der komplette Workflow als fertiges System

CLAUDE.md-Vorlage, die vier Agentenrollen, Plan-Modus-Regeln, Audit-Prompts und QA-Checkliste – all das lässt sich selbst aufbauen. Oder du startest mit einem fertigen System: Das Claude Code Projektstarter-Kit von AI-Agents.Tools enthält genau diese Bausteine, sofort einsetzbar in deinem nächsten Projekt. Einmalig 39 €, Sofort-Download.

Weiterlesen

• Was sind AI Workflow Kits?
• Claude Code Projektstarter-Kit ansehen