Claude Code Greenfield-Workflow: Vom leeren Repo zur ersten Slice

Was du bei einem Greenfield-Start vermeiden willst

Vom leeren Repo zu starten fühlt sich wie Freiheit an, aber oft endet es in chaotischem Vorwärtsdrang: viele generierte Dateien, ein halb funktionierender Build und kein klarer Ort für die nächste Änderung. Der Sinn eines Claude Code Greenfield-Workflows ist, dieses Chaos der ersten Woche zu vermeiden.

Einige Fehler tauchen immer wieder auf:

• Code, der „auf meinem Rechner funktioniert“, weil die Einrichtung im Kopf von jemandem lebt und nicht in Skripten.
• Eine Ordnerstruktur, die die Reihenfolge widerspiegelt, in der Dinge erstellt wurden, statt wie die App wachsen sollte.
• Eine Schleife, in der jeder neue Prompt frühere Entscheidungen überschreibt, sodass nichts stabil wird.

Frühe Entscheidungen sind schmerzhaft rückgängig zu machen, weil alles auf ihnen aufbaut. Eine verwirrende Struktur verstärkt sich immer wieder. Ein manueller Build entwickelt sich zu zehn verschiedenen Setups. Wenn du keinen einfachen Dev-Befehl früh festlegst, kannst du nicht sagen, ob eine Änderung die App kaputt gemacht hat oder nur die Umgebung.

Wenn dieser Beitrag von „laufender App“ spricht, meint er etwas Konkretes: ein Befehl, der das Projekt startet, vorhersehbare Ausgabe druckt und laut fehlschlägt, wenn etwas fehlt. Du solltest deine lokale Installation löschen können, das Repo klonen, diesen Befehl ausführen und dasselbe Ergebnis sehen.

Eine „Vertical Slice“ ist das kleinste End-to-End-Feature, das beweist, dass deine App echt ist. Kein UI-Mock. Keine einzelne Datenbanktabelle. Es ist eine dünne Linie durch das ganze System, zum Beispiel eine Seite mit einem Formular, ein API-Endpunkt, der Daten speichert, ein Datenbank-Schreib- und Lesevorgang und ein sichtbares Ergebnis auf der Seite.

Wenn du die App mit einem Befehl starten und eine Vertical Slice ausliefern kannst, hast du eine Basis, auf der du ohne Rätselraten iterieren kannst.

Entscheide die erste Slice, bevor du irgendetwas generierst

Eine klare erste Slice hält dein Repo ordentlich und deine Prompts fokussiert. Dies ist der Moment, zu entscheiden, was du end-to-end demonstrieren willst, nicht was das volle Produkt werden könnte.

Wähle die kleinste Nutzerstory, die beweist, dass die App auf dem ganzen Pfad funktioniert. Eine gute Slice berührt UI, Daten und eine echte Aktion. Beispiel: „Als Nutzer kann ich eine Aufgabe hinzufügen und sie nach dem Neuladen in einer Liste sehen.“ Das ist winzig, erzwingt aber Routing, Validierung, Speicherung und einen einfachen Screen.

Wähle eine Zielplattform für Woche 1 und bleibe dabei. Wenn du mit Web beginnst, nur Web. Füge keine mobilen Screens „für den Fall" hinzu. Selbst wenn du planst, später eine Plattform wie Koder.ai zu nutzen, erzielst du bessere Ergebnisse, wenn die erste Slice in einer Spur bleibt (React Web, oder eine Go-API, oder Flutter).

Definiere, was „für Woche 1 fertig“ in klaren Worten bedeutet:

• Läuft lokal nach einem frischen Clone mit einem Befehl
• Ein funktionierendes Feature, das du end-to-end klicken kannst
• Fehler zeigen eine verständliche Nachricht (kein Stack-Trace)
• Daten werden irgendwo einfach gespeichert (auch eine lokale Datenbank)

Schreibe dann drei Non-Goals auf, die den Scope schützen. Zum Beispiel: kein Auth, kein Themesystem, keine Hintergrundjobs.

Sobald diese Entscheidungen aufgeschrieben sind, kann dein Generations-Prompt streng sein: Baue nur, was die Slice unterstützt, alles andere als TODO.

Einige Entscheidungen im Vorfeld, die Nacharbeit sparen

Bevor du Claude bittest, irgendetwas zu generieren, lege ein paar Defaults fest. Sie wirken klein, verhindern aber das „alles später umbenennen“-Chaos.

Zuerst: Entscheide die Form der App. Wenn du wirklich ein Browser-UI und ein Backend brauchst, starte mit zwei klaren Teilen (Frontend + API) und einem gemeinsamen Ort für Verträge (API-Typen oder ein einfaches Schema). Wenn die App serverseitig gerendert werden kann, behalte sie in einem Codebase, damit das lokale Entwickeln einfach bleibt.

Als Nächstes: Einigt euch auf Konfigurationsregeln. Nutze eine lokale env-Datei, halte sie aus Git heraus und committe eine Vorlage (zum Beispiel .env.example) mit sicheren Platzhaltern und kurzen Kommentaren. Das erleichtert Onboarding und reduziert das Risiko, Geheimnisse zu leaken.

Wähle Standard-Dev-Ports und halte sie stabil. Ports tauchen in Skripten, Docs und Fehlermeldungen auf, deshalb nervt es, sie später zu ändern. Gleiches gilt für Namensgebung: Ordner, Services und Packages sollten einer Konvention folgen. Konsistenz ist wichtiger als die „perfekte" Konvention.

Eine einfache Start-Auswahl:

• App-Form: Single App oder Frontend + API
• Konfig: .env lokal, .env.example committed
• Ports: einer für Web, einer für API, einer für DB (falls nötig)
• Namen: ein einheitlicher Namensstil für Ordner, konsistente Service-Namen
• Secrets: niemals committed, rotieren, wenn exponiert

Beispiel: du wählst web auf Port 3000 und api auf Port 8080. Dein Env-Template enthält API_URL=http://localhost:8080 und DATABASE_URL=.... Wenn Claude später Skripte und Docs generiert, passt alles zusammen statt zu driften.

Wie du Claude Code so promptest, dass es strukturiert bleibt

Fang damit an, um ein lauffähiges Gerüst zu bitten, nicht „die ganze App“. Der schnellste Weg zu chaotischem Output ist, Features zu verlangen, bevor es einen Ort gibt, sie abzulegen.

Sei explizit über die Struktur. Bitte um ein Ordner-Layout mit kurzen Kommentaren, die erklären, was wohin gehört und was nicht. Das zwingt Entscheidungen nach oben statt Dateien wild zu verstreuen.

Eine einfache Methode, um diszipliniert zu bleiben, ist, Regeln im Prompt zu setzen:

• Generiere zuerst das kleinste lauffähige Skelett (Hello-Page, Health-Endpoint oder ein Screen).
• Schlage eine Ordnerstruktur vor und erkläre jeden Ordner in einem Satz.
• Füge Skripte hinzu, die auf einer frischen Maschine funktionieren (install, dev, test, build) und nenne Voraussetzungen.
• Halte Änderungen in einem PR-großen Chunk und liste genau auf, welche Dateien erstellt oder geändert werden.
• Stoppe nach dem Scaffolding und sage mir, wie man es ausführt.

Hier ist ein Prompt, den du wiederverwenden und anpassen kannst:

You are working in an empty repo. Create a minimal runnable skeleton.

Constraints:
- Keep it small: no real features yet.
- Propose a clear folder structure and add brief comments in each folder’s README.
- Add scripts for: setup, dev, test, build. They must work on a fresh machine.
- Tell me exactly how to run it, and what output I should see.
- After generating, stop and wait for my “ran it” confirmation.

Output:
1) File tree
2) Key files (only)
3) Run instructions

Dann halte die Schleife klein. Frage nicht fünf Änderungen auf einmal. Generiere eine kleine Änderung, führe sie aus, füge den genauen Error (oder Erfolg) ein und bitte um einen minimalen Fix. Dieser Generate-Run-Adjust-Rhythmus macht das Projekt vorhersehbar und erschwert, dass die Struktur driftet.

Schritt für Schritt: vom leeren Repo zum lauffähigen Skelett

Beginne mit einem Versprechen: Jeder soll das Repo klonen und mit einem Befehl etwas Funktionierendes sehen können. Das gibt dir eine stabile Basis, bevor du eine KI bittest, echte Features hinzuzufügen.

Erstelle das Repo und schreibe ein kleines README, solange alles frisch ist. Halte es praktisch: Voraussetzungen, der eine Dev-Befehl und wie man Tests ausführt (auch wenn Tests zunächst leer sind).

Wähle nun ein Top-Level-Layout, das zur gewählten App-Form passt.

Wenn du mehrere deploybare Teile baust (z. B. Frontend + API), hilft ein Workspace-Layout:

/
  apps/
  packages/
  scripts/
  docs/
  README.md

Wenn du eine einzelne App baust, halte es einfacher und vermeide zusätzliche Ebenen, bis du sie brauchst.

Füge jetzt minimale Leitplanken hinzu, damit der Code konsistent bleibt. Wähle einen Formatter und einen Linter, akzeptiere deren Defaults und füge je eine Konfigurationsdatei hinzu. Ziel sind saubere Diffs, nicht perfekte Regeln am ersten Tag.

Mach die Entwicklererfahrung vorhersehbar mit einem Befehl, der immer vom Repo-Root funktioniert. Hier ist eine einfache Form:

{
  "scripts": {
    "dev": "echo \"start dev server here\"",
    "build": "echo \"build here\"",
    "test": "echo \"tests here\"",
    "lint": "echo \"lint here\""
  }
}

Bevor du etwas anderes generierst, führe diesen Dev-Befehl aus, bestätige, dass er sauber endet (oder einen Platzhalter-Server startet), und mache deinen ersten Commit nur mit dem Scaffolding. Wenn ein Kollege (oder dein zukünftiges Ich) das Setup reproduzieren kann, bist du bereit, die erste Slice zu bauen.

Eine Ordnerstruktur, die mitwachsen kann

Eine gute Greenfield-Struktur macht zwei Dinge: sie hilft, Code schnell zu finden, und sie gibt Claude weniger Raum, bei jeder Änderung neue Muster zu erfinden. Ziel ist nicht Perfektion, sondern Stabilität.

Wenn du in einer Single-App arbeitest (oder in einem apps/<name>/-Ordner), hält sich eine einfache interne Struktur meist gut:

• src/ App-Code (Features, Shared-Teile, Entry-Points)
• config/ nicht-geheime Konfiguration
• tests/ höherstufige Tests, die sich wie Nutzerverhalten lesen
• scripts/ Hilfsskripte (Dev-Setup, DB-Reset, Release-Tasks)
• docs/ kurze Notizen und Checklisten, die du wirklich pflegst

Innerhalb von src/ trenne Feature-Code von gemeinsam genutztem Code basierend auf Änderungsmustern. Feature-Code ändert sich oft und sollte nah beieinander leben. Shared-Code sollte langweilig und wiederverwendbar sein.

Eine praktische Regel: Lege UI-Screens, Handler und Feature-spezifische Logik unter src/features/<featureName>/... ab. Dinge wie Logging, API-Clients, Design-System-Komponenten und generische Utilities kommen unter src/shared/... Wenn ein Helfer nur für ein Feature Sinn macht, lass ihn in diesem Feature, auch wenn er wiederverwendbar aussieht. Verschiebe ihn später, wenn es eine zweite echte Nutzung gibt.

Ordnernamen sollten Zweck beschreiben, nicht Technik. „features“ und „shared“ bleiben sinnvoll, wenn sich dein Stack ändert. Vermeide Namen wie „misc“ oder „new”.

Halte docs/ klein. Ein guter Starter ist docs/checklists.md mit ein paar Zeilen: wie man startet, wie man testet, wie man einen neuen Feature-Ordner hinzufügt und was „done“ bedeutet.

Build-Skripte, die das Projekt vorhersehbar machen

Ein Repo wirkt echt, wenn jeder dieselben Befehle ausführen kann und dasselbe Ergebnis bekommt. Skripte sind Leitplanken: sie reduzieren Rätselraten, halten Änderungen klein und machen deutlich, wenn etwas kaputt ist.

Beginne mit einer kleinen Menge an Befehlen und halte sie langweilig. Wenn jemand Neues einsteigt (oder du nach zwei Wochen zurückkommst), sollten keine speziellen Flags oder versteckten Schritte nötig sein.

Hier ist eine einfache Basis, die du an jeden Stack anpassen kannst:

{
  "scripts": {
    "dev": "node ./scripts/dev.js",
    "build": "node ./scripts/build.js",
    "test": "node ./scripts/test.js",
    "test:quick": "node ./scripts/test.js --quick",
    "test:full": "node ./scripts/test.js --full",
    "format": "node ./scripts/format.js",
    "lint": "node ./scripts/lint.js",
    "smoke": "node ./scripts/smoke.js"
  }
}

Mach das dev-Skript zum Happy-Path. Es sollte die App starten, anzeigen, wo sie läuft, und Logs lesbar halten. Wenn der Server nicht starten kann, fail fast mit einer klaren Nachricht (fehlende Env-Variable, Port belegt, Datenbank nicht erreichbar).

Das Build-Skript sollte immer ein sauberes Output-Verzeichnis erzeugen. Lösche zuerst das alte Output und produziere dann frische Artefakte. Das vermeidet seltsame Bugs durch Dateien von gestern.

Für Tests, teile schnelle Checks von langsamen. Quick-Tests laufen bei jeder Änderung (Unit-Tests, Typprüfungen). Full-Tests beinhalten Integrationschecks und laufen vor dem Merge.

Halte den Stil mit einem Befehl konsistent. Eine einfache Regel: format behebt Dinge, lint meckert über Dinge.

Füge schließlich eine Smoke-Check hinzu, die die Basics validiert, bevor du Zeit mit Debugging verschwendest:

• Erforderliche Env-Variablen sind gesetzt (und nicht leer)
• Gewählte Ports sind frei
• App kann starten und auf eine einfache Anfrage antworten
• DB-Verbindung funktioniert (falls verwendet)
• Build-Output existiert nach build

Baue das erste Vertical-Slice-Feature

Deine erste Vertical Slice sollte beweisen, dass die App End-to-End funktioniert, nicht nur, dass das UI hübsch aussieht. Das bedeutet ein kleines Feature, das Screen, Logik und irgendeine Art von Speicherung berührt, selbst wenn die Speicherung temporär ist.

Wähle etwas langweiliges und nützliches, wie „Notiz hinzufügen“ oder „Aufgabe erstellen“. Halte es klein genug, um in einer Sitzung fertig zu werden, aber vollständig genug, dass du klicken und echten Zustandswechsel sehen kannst.

Eine gute Slice hat vier Teile: eine Route oder einen Screen, ein Formular, eine Save-Action und eine Anzeige. Beispiel: eine „Neue Aufgabe“-Seite mit Titel-Input, einem Speichern-Button, der eine Funktion aufruft, und einer Liste, die gespeicherte Aufgaben zeigt.

Beginne mit einem Platzhalter-Store, damit du schnell vorankommst. Ein In-Memory-Array, eine lokale JSON-Datei oder ein einfaches Stub-Interface ist okay. Wichtig ist, eine Grenze zu schaffen, die du später ersetzen kannst. Wenn dein Code heute taskRepository.save(task) aufruft, wird der Wechsel zu einer echten DB später eine kleine Änderung, kein Rewrite.

Halte das UI schlicht. Überspringe Design-System-Debatten, Empty States und Animationen.

Akzeptanzprüfungen, die du in zwei Minuten machen kannst:

• Seite öffnet ohne Fehler
• Du kannst einen Wert eingeben und auf Speichern drücken
• Das neue Element erscheint sofort
• Reload zeigt erwartetes Verhalten (persistiert bei echter Speicherung, reset bei Fake)
• Fehlerhafte Eingabe wird behandelt (leerer Titel zeigt eine Nachricht und wird nicht gespeichert)

Mach es stabil genug zum Iterieren

Nachdem du ein lauffähiges Skelett und eine Vertical Slice hast, verschiebt sich das Ziel: Mache Fehler offensichtlich und Fixes schnell. Hier scheitern viele Greenfield-Starts nicht wegen schwerer Features, sondern weil kleine Änderungen Überraschungen verursachen.

Setze eine kleine Stabilitäts-Mindestanforderung, die du bei jedem Slice erfüllst:

• Ein Smoke-Test, der beweist, dass die App bootet und die Haupt-Route/der Haupt-Screen rendert
• Ein Smoke-Test, der die Slice End-to-End trifft (auch wenn eine Testdatenbank verwendet wird)
• Klare Fehlermeldungen, die normale Nutzer verstehen (keine Stack-Traces)
• Dev-Logs, die erklären, was passiert ist, ohne Geheimnisse zu drucken
• Minimale Abhängigkeiten, Versionen festgenagelt, Upgrades bewusst durchgeführt

Konkretes Beispiel: Deine erste Slice lässt einen Nutzer ein „Project“ erstellen und in einer Liste sehen. Füge einen Test hinzu, der den Server startet, den Create-Endpoint aufruft und dann die Liste abruft und prüft, dass das neue Element erscheint. Wenn er fehlschlägt, soll er laut mit einer hilfreichen Nachricht fehlschlagen, z. B. „Create Project endpoint returned 500", und nicht mit einem Berg Output.

Beim Error-Handling bleib bei einer kleinen Menge konsistenter Antworten. Validierungsfehler geben eine kurze Nachricht zurück ("Name ist erforderlich") und ein Feld. Unerwartete Fehler geben "Etwas ist schiefgelaufen. Bitte versuche es erneut." Zur Detailtiefe für Logs.

Logging ist am nützlichsten, wenn es beantwortet: welche Anfrage, welcher Nutzer (oder anonym), was ist fehlgeschlagen und wo. In Dev, füge eine Request-ID und Timing hinzu, aber vermeide es, Tokens, Passwörter, API-Keys oder ganze Payloads standardmäßig auszugeben.

Füge eine kleine Health-Check hinzu. Im Web kann das ein /health-Endpunkt sein, der ok zurückgibt. Auf Mobile kann es ein „Connected“-Status sein, der auf „Offline" springt, wenn die App das Backend nicht erreicht. Es ist ein schnelles Signal, bevor du die falsche Sache debuggst.

Übliche Fallen beim Einsatz von KI für Greenfield-Projekte

Der schnellste Weg, einen Greenfield-Start zu verschwenden, ist, das Modell nach einer ganzen App zu fragen und sie erst später auszuführen. Große Generierungen verbergen kleine Fehler: fehlende Abhängigkeiten, falsche Importpfade, Skripte, die Tools voraussetzen, die du nicht hast. Behandle jeden Output so, dass du ihn innerhalb von Minuten ausführen kannst.

Eine andere Falle ist, die perfekte Architektur zu planen, bevor es ein Feature gibt. Über Folder-Namen zu diskutieren fühlt sich produktiv an, aber ohne eine echte Slice kann man nicht sagen, was unpraktisch ist. Eine einfache Struktur, die einen funktionierenden Pfad unterstützt, schlägt eine clevere, ungetestete Struktur.

Command-Drift ist ebenfalls üblich. Die KI fügt einen neuen Weg hinzu, den Server zu starten, du fügst einen weiteren für Tests hinzu, und bald weiß niemand mehr, welcher Befehl „der" ist. Wenn ein Kollege das Repo klont und fragt „Wie starte ich das?", zahlst du schon Zinsen.

Fehler, die die meiste Nacharbeit verursachen:

• Mehrere Services, Screens und Konfigurationen in einem Rutsch generieren statt zuerst einen lauffähigen Pfad zu bauen
• Auth, Payments, komplexes Styling und ein vollständiges Datenmodell einführen, bevor das erste Feature End-to-End funktioniert
• Setup-Anweisungen im Chat statt in Skripten (oder einem einzigen README) lassen
• Eine saubere Env-Vorlage vergessen, so dass die nächste Maschine ohne Raten starten muss

Ein einfaches Beispiel: Du generierst eine „komplette" App mit Login, Theming und Billing, aber der erste Lauf scheitert, weil ein Secret fehlt und keine .env.example vorhanden ist. Dann verbringst du eine Stunde mit Setup-Fixes statt herauszufinden, ob das Feature nützlich ist.

Sei ehrlich: ein lauffähiger Befehl, ein kleines Feature, eine Env-Vorlage, dann erweitern.

Schnelle Checkliste, bevor du zu iterieren beginnst

Bevor du „noch ein Feature" hinzufügst, sorge dafür, dass das Projekt morgen (oder jemand anderes) leicht aufzunehmen ist. Geschwindigkeit ist nicht das alleinige Ziel. Vorhersehbarkeit ist es.

• One-Command-Run: Ein neuer Dev kann eine Env-Vorlage kopieren, die wenigen Werte setzen und die App mit einem Befehl starten. Falls zusätzliche Schritte nötig sind (DB-Setup, Migrations, Seed-Daten), packe sie in ein Skript.
• Skripte decken Basics ab: klare Befehle für dev, test, build und ein schneller Smoke-Check.
• Offensichtliche Struktur: Layout erzählt eine Geschichte (App-Code, Config, Skripte, Tests), ohne das ganze Codebase lesen zu müssen.
• Vertical-Slice-Demo-Pfad: Du kannst die Demo in einem Satz beschreiben, z. B. „Element erstellen, in Liste sehen, Refresh, es ist noch da."
• Rollback-Punkt: Vor großen Änderungen gibt es einen sicheren Punkt zum Zurückkehren (ein sauberer Commit, ein Tag oder Snapshot/Rollback-Mechanismus).

Wenn ein Punkt fehlschlägt, repariere ihn jetzt. Skripte und Namensgebung zu straffen ist billig, wenn das Repo klein ist.

Nächste Schritte: Mach den Workflow wiederholbar

Ein Greenfield-Start zahlt sich nur aus, wenn du ihn wiederholen kannst. Nachdem deine erste Vertical Slice End-to-End läuft, friere die guten Teile in eine kleine Vorlage ein: dieselben Ordner-Muster, dieselben Skript-Namen und dieselbe Verkettung von UI, API und Daten.

Behandle deine erste Slice als Referenz-Implementierung. Wenn du Slice #2 startest, kopiere die Form, nicht den Code. Wenn Slice #1 eine Route, einen Handler, eine Data-Access-Schicht und einen Basis-Test hat, sollte Slice #2 denselben Weg folgen.

Halte die Planung leichtgewichtig. Eine einseitige Notiz reicht für die nächsten 2–3 Slices: das Ziel und die Nutzeraktion für jede Slice (ein Satz), die benötigten Daten, die „Done“-Checks und Risiken, die du früh testen solltest.

Mach dann Wartung zur Gewohnheit. Einmal pro Woche ein kurzer Cleanup-Pass: Skripte straffen, README mit neuen Setup-Schritten aktualisieren und die Env-Beispiel-Datei auffrischen, damit Onboarding einfach bleibt.

Wenn du einen Chat-first Build-Loop bevorzugst, ist Koder.ai (koder.ai) eine Option, die Planungsmodus plus Snapshots und Rollback unterstützt und Quellcode exportieren kann, wenn du das Projekt anderswohin mitnehmen willst.

Das Ziel ist ein Workflow, den du automatisch ausführen kannst: Plane 2–3 Slices, baue eine Slice, stabilisiere, wiederhole.