Export-Checkliste für KI-erstellte Codebasen für eine saubere Übergabe

Warum exportierte Projekte nach der Übergabe scheitern

Die meisten exportierten Projekte scheitern aus einem einfachen Grund: sie liefen innerhalb der ursprünglichen Plattform problemlos, wo Defaults, Secrets, Datenbankzustand und Build-Schritte bereits vorhanden waren. Sobald der Code diese Blase verlässt, muss der nächste Entwickler raten, was vorausgesetzt wurde.

Eine saubere Übergabe bedeutet, dass das Projekt von jemandem, der es nicht gebaut hat, auf einer frischen Maschine geklont, konfiguriert und gestartet werden kann, ohne lange Rückfragen. Es braucht keinen perfekten Code. Es braucht, dass die Basics explizit und reproduzierbar sind.

Exports scheitern immer wieder an denselben Punkten: versteckte Konfiguration, unklare Behandlung von Secrets, vage lokale Setup-Schritte, Datenbank-Überraschungen und CI, das nur in einer Umgebung funktioniert.

Deshalb geht es bei einer KI-erstellten Codebase-Export-Checkliste meist um Dokumentation und Reproduzierbarkeit, nicht ums Kopieren von Dateien. Wenn Sie die App in einer vibe-coding-Plattform wie Koder.ai gebaut und anschließend den Quellcode exportiert haben, braucht das nächste Team trotzdem eine Karte: was gesetzt werden muss, was ausgeführt werden soll und wie „funktionierend“ aussieht.

Diese Checkliste konzentriert sich auf die Handover-Essentials: Umgebungsvariablen, Secrets, lokales Setup, Datenbank-Bootstrap, CI-Setup und ein praxisnahes „How to run“-README. Produktentscheidungen, UX-Feinschliff oder Architektur-Umbau sind nicht Teil davon.

Die Zuständigkeiten sollten ebenfalls klar sein. Der Erbauer ist dafür verantwortlich, Annahmen sichtbar zu machen (Docs, Skripte, sichere Defaults). Der Empfänger ist dafür verantwortlich, das Projekt an seine Umgebung anzupassen (Secret-Manager, Hosting, strengere CI-Regeln). Wenn beide Seiten ihre Rolle kennen, wird die Übergabe Routine.

Vor dem Export: den Handoff-Vertrag festlegen

Eine saubere Übergabe beginnt mit einer einfachen Vereinbarung: was bedeutet „fertig“, wenn der Code die Plattform verlässt. Ohne diese Vereinbarung streiten Teams später über fehlende Skripte, überraschende Abhängigkeiten oder welche Version die richtige war.

Den Exportzeitpunkt wählen

Wählen Sie einen einzigen stabilen Zeitpunkt und behandeln Sie ihn als Quelle der Wahrheit. Ein Export während einer Änderung ist der Grund, warum Teams ein Repo haben, das fast läuft.

Ein guter Exportzeitpunkt ist meist einer der folgenden:

• Ein stabiler Commit mit kurzer Release-Notiz (was sich geändert hat, was getestet werden sollte)
• Ein getaggtes Release (selbst wenn es nur v0.1.0 ist)
• Ein Plattform-Snapshot (z. B. ein Koder.ai-Snapshot, zu dem Sie bei Bedarf zurückkehren können)

Fügen Sie einen Satz hinzu, der erklärt, warum dies der richtige Exportpunkt ist. Beispiel: „Alle Kernflüsse laufen und das Datenbankschema ist für diesen Meilenstein final."

Entscheiden, was die Übergabe umfasst

Schreiben Sie ein kurzes Inventar dessen, was der Empfänger erwarten soll. Seien Sie explizit, was enthalten ist und was bewusst ausgeschlossen wurde.

Beziehen Sie die Basics ein: Quellcode (Apps, Services, geteilte Packages), Konfig-Vorlagen (Beispiel-env-Dateien), Skripte (build, dev, test, migrations, seed) und Deployment-Hinweise. Beigefügte Beispieldaten nur, wenn sie bereinigt und sicher sind.

Frieren Sie Versionen ein, damit „bei mir läuft’s“ nicht zum neuen Standard wird. Erfassen Sie Laufzeit- und Toolchain-Versionen (Node, Go, Flutter, Paketmanager) sowie die Datenbank-Version (PostgreSQL-Major-Version ist wichtig).

Listen Sie schließlich Voraussetzungen auf, die vor dem Start erledigt sein müssen. Halten Sie es kurz und konkret: benötigte Accounts, installierte Tools, freie Ports und einmalige Setup-Schritte.

Umgebungsvariablen: dokumentieren, damit nichts verborgen bleibt

Die meisten „auf der Plattform lief’s“-Exports scheitern, weil zentrale Einstellungen nie niedergeschrieben wurden. Umgebungsvariablen sind der übliche Schuldige: sie leben außerhalb des Repos, also klont ein neuer Entwickler das Projekt und hat keine Ahnung, welche Werte erwartet werden.

Behandeln Sie das als Pflicht für einen sauberen Export: jede Variable sollte auffindbar, erklärt und leicht zu setzen sein, ohne zu raten.

Erstellen Sie eine Single Source of Truth in Ihrer Handover-README: eine Liste von Env-Variablen-Namen, was sie steuern und woher Werte kommen. Halten Sie die Erklärungen in einfacher Sprache und kennzeichnen Sie sicherheitsrelevante Einträge.

Ein einfaches Format für jede Variable:

• Name: exakter Schlüssel (copy/paste-tauglich)
• Bedeutung: was es in der App ändert
• Erforderlich?: Pflicht oder optional (und was passiert, wenn es fehlt)
• Beispiel: sicheres Beispiel (niemals ein echtes Secret)
• Wo es sich unterscheidet: dev vs staging vs production

Begleitet von dieser Dokumentation sollte eine .env.example im Repo liegen. Sie sollte jede potenziell benötigte Variable enthalten, mit sicheren Platzhaltern, sodass die App mit minimalen Änderungen starten kann.

# Required
APP_ENV=development
PORT=3000
DATABASE_URL=postgres://user:password@localhost:5432/app_dev

# Optional
LOG_LEVEL=info
CORS_ORIGINS=http://localhost:5173

# Environment specific
PUBLIC_BASE_URL=http://localhost:3000

Ein paar Details verhindern die meisten Missverständnisse:

Machen Sie „erforderlich vs optional“ explizit. Wenn eine fehlende Variable einen Crash verursacht, sagen Sie es. Wenn sie ein Feature aktiviert (E-Mail-Versand, Zahlungen, Dateispeicher), benennen Sie das Feature und beschreiben Sie, was passiert, wenn es nicht gesetzt ist.

Heben Sie hervor, was sich pro Umgebung ändert. DATABASE_URL und PUBLIC_BASE_URL unterscheiden sich oft zwischen dev, staging und production, während LOG_LEVEL überall gleich sein kann. Wenn Sie Koder.ai zum Export und Deployment verwendet haben, prüfen Sie, ob Plattform-Defaults (Ports, Base-URLs, erlaubte Origins) in der Dokumentation reflektiert sind, damit das Verhalten außerhalb der Plattform konsistent bleibt.

Geben Sie schließlich an, wie Env-Variablen lokal geladen werden. Erwartet das Projekt eine .env-Datei? Sagen Sie, wo sie liegt und ob die App sie automatisch liest oder ein Kommando/Tool benötigt.

Secrets: außerhalb des Repos halten und leicht setzbar machen

Secrets sind Werte, deren Leckage Schaden anrichten würde: API-Keys, Datenbankpasswörter, Auth-Tokens, OAuth-Client-Secrets, private Keys, Webhook-Signing-Secrets und Ähnliches.

Für einen Export halten Sie es einfach: das Repo sollte nur Platzhalter enthalten, niemals echte Secret-Werte. Wenn ein Secret nötig ist, um zu starten, nehmen Sie es als klar benannten Platzhalter in .env.example auf und erklären Sie, wie man ein echtes erzeugt.

Ein praktisches Muster ist, drei Dinge zu trennen: eine Beispiel-Datei, eine lokale Datei und einen Secret-Store für CI/Deployment. Ihr exportierter Code sollte die Beispiel-Datei enthalten, die lokale Datei ignorieren und dokumentieren, wie CI/Hosting Secrets erhält.

Wo Secrets liegen sollten

Wählen Sie pro Umgebung einen Ansatz und bleiben Sie dabei.

• Lokale Entwicklung: .env (gitignored), geladen von der App, oder der lokale Secret-Manager des Teams
• CI: verschlüsselte Secret-Variablen des CI-Anbieters
• Deployment/Hosting: Secrets im Hosting-Environment gespeichert und zur Laufzeit injiziert

Beispiel: das Repo enthält PAYMENTS_API_KEY=replace_me. Der Empfänger erzeugt seinen eigenen Key im Provider-Dashboard und setzt ihn in seiner lokalen .env und in CI. Der Code bleibt unverändert.

Einen Rotationsschritt hinzufügen

Eine Übergabe ist ein guter Zeitpunkt, Secrets zu rotieren, besonders wenn sie jemals in einer geteilten Plattform-Session verwendet wurden.

• Neue Schlüssel für externe Dienste ausstellen und alte widerrufen.
• Datenbankpasswörter und Admin-Tokens zurücksetzen.
• CI- und Hosting-Secrets zuerst aktualisieren, dann lokale .env-Dateien.
• Bestätigen, dass die App startet, Tests laufen und alte Keys nicht mehr funktionieren.

Wenn Sie aus Koder.ai exportiert haben, behandeln Sie den Export als neue Umgebung und erzeugen Sie frische Secrets für das empfangende Team.

Lokales Entwicklung-Setup: den ersten Start langweilig machen

Eine Übergabe ist erfolgreich, wenn ein neuer Entwickler das Repo klonen, ein paar Befehle ausführen und die App ohne Rätsel sehen kann. Ziel: vorhersehbare Voraussetzungen, klare Befehlsfolge und ein kurzes „how to run“-Block, der der Realität entspricht.

Voraussetzungen (explizit)

Stellen Sie diese an den Anfang der README, damit niemand sie aus Fehlermeldungen ableiten muss:

• OS-Hinweise: „Getestet auf macOS und Ubuntu“ (Windows-Nachweise nur bei Tests)
• Laufzeit-Versionen: Node.js (für React), Go (für die API), PostgreSQL (für die DB)
• Tools: npm/pnpm/yarn, Make (falls verwendet), Docker (nur wenn notwendig)

Wenn das Projekt in Koder.ai gebaut wurde, stimmen Sie das lokale Setup mit dem Export ab (gleiche Ordnerstruktur, gleiche Startbefehle). Gehen Sie nicht davon aus, dass „Postgres schon läuft“, außer Sie sagen es explizit.

Installation und Dev-Befehle (ein Befehl pro Zeile)

Geben Sie die exakten Befehle in der Reihenfolge an, in der ein neuer Kollege sie ausführen soll. Kopierbar:

# 1) Install dependencies
cd web
npm ci

cd ../server
go mod download

# 2) Create your env file
cp .env.example .env

# 3) Start dependencies (if needed)
# e.g., start Postgres locally or via docker compose

# 4) Run the app
cd server
go run ./cmd/api

cd ../web
npm run dev

Fügen Sie direkt darunter einen minimalen Test- und Build-Abschnitt hinzu:

# Tests
cd server && go test ./...
cd web && npm test

# Build
cd web && npm run build
cd server && go build ./...

Troubleshooting: die häufigsten Erstläufe-Fehler

Die meisten „läuft nicht“ Probleme fallen in ein paar Kategorien:

1. Falsche Versionen (Node/Go). Symptome: Abhängigkeits- oder Kompilierungsfehler. Lösung: installierte gepinnte Versionen nutzen und Installation wiederholen.

2. Fehlende Env-Werte. Symptome: „undefined“ Config, Auth-Fehler, 500er. Lösung: .env mit .env.example vergleichen und erforderliche Werte ergänzen.

3. Datenbank nicht erreichbar. Symptome: connection refused, „database does not exist“. Lösung: Postgres starten, Host/Port/User prüfen und die Datenbank-Init-Schritte genau wie beschrieben ausführen.

Datenbank-Bootstrap: Migrationen, Seeds und Resets

Beim Export aus einer Plattform ist die Datenbank oft das erste, was auf einer neuen Maschine kaputt geht. Ziel: ein Kollege sollte vom Klonen des Repos bis zur lauffähigen App mit echten Daten kommen, ohne zu raten.

Was dokumentiert und im Repo bleiben sollte

Schreiben Sie die minimalen Schritte für ein frisches PostgreSQL-Setup und packen Sie Befehle nach Möglichkeit in Skripte. Ihre Übergabe sollte vier Fragen beantworten:

• Wie erstelle ich die Datenbank und Rolle (Name, Rechte und woher das Passwort kommt)?
• Wie führe ich Migrationen von null bis zur neuesten Version aus?
• Wie lade ich Seed-Daten, die die App für eine Demo nutzbar machen?
• Wie setze ich die Datenbank sicher während der Entwicklung zurück?

Wenn schon Skripte existieren (Makefile-Targets, Shell-Skripte, Task-Runner-Befehle), verwenden Sie diese statt manueller Anweisungen. Wenn nicht, fügen Sie jetzt ein kleines Set hinzu.

Ein langweiliger Bootstrap-Flow, der funktioniert

Halten Sie den Flow konsistent über Umgebungen (lokal, CI, staging). Eine gute Basis sieht so aus:

# 1) Create role + database (example names)
createuser app_user --pwprompt
createdb app_db --owner=app_user

# 2) Apply migrations
# Replace with your repo's migration command
./scripts/migrate up

# 3) Seed minimal demo data
./scripts/seed

Bei Seeds bevorzugen Sie minimale, funktionale Daten statt eines produktionsähnlichen Dumps. Seeds sollten mehrfach sicher ausführbar sein (idempotente Inserts oder klare Regel „nur auf leerer DB ausführen").

Für Resets: seien Sie explizit bezüglich der Sicherheit. Ein Reset-Befehl sollte standardmäßig nur die lokale Entwicklung betreffen. Wenn Sie ein destruktives Skript anbieten, bauen Sie Schutzmechanismen ein (z. B. erfordern CONFIRM_RESET=1 oder prüfen APP_ENV=development). Definieren Sie außerdem klar, was „reset“ bedeutet: drop & recreate, Tabellen leeren oder einen bekannten Snapshot wiederherstellen.

Repo-Hygiene: was ins Source gehört und was nicht

Eine Übergabe geht schief, wenn das Repo wie eine Schublade voller Kleinkram wirkt. Ein neuer Entwickler sollte erkennen, was wichtig ist, was generiert wird und wo Einstellungen zu ändern sind.

Committen Sie Dinge, die das Projekt reproduzierbar machen: Lockfiles, Migrationsdateien, kleine Konfig-Vorlagen wie .env.example und Skripte, die die App bootstrappen.

Halten Sie persönliche, generierte oder sensible Dateien aus der Versionskontrolle: lokale Env-Dateien, Editor-Einstellungen, Build-Ausgaben, Logs, Caches und alles, was Zugang gewährt (API-Keys, DB-Passwörter, Service-Account-Dateien).

Eine einfache Regel: wenn eine Änderung alle betrifft, committen Sie sie. Wenn sie pro Maschine oder Umgebung variiert, dokumentieren Sie sie und halten sie aus dem Repo raus.

Wenn Sie eine kurze „Commit vs Ignore“-Notiz aufnehmen, halten Sie sie knapp:

• Commit: README, Lockfiles, Migrationen, Seed-Skripte, .env.example
• Ignore: .env, Secret-Dateien, Build-Ordner, Logs, lokale Caches

Fügen Sie eine kurze Verzeichnis-Übersicht hinzu, damit die Struktur ohne Herumklicken offensichtlich ist. Beispiel: „/backend API-Service, /web Frontend, /mobile App, /db Migrationen und Seeds, /scripts Setup-Helper.”

Wenn Sie aus Koder.ai exportiert haben, betrachten Sie den Export als Beginn dieser Aufräumrunde: entfernen Sie generierten Müll, prüfen Sie .gitignore und schreiben Sie die Verzeichnis-Übersicht.

CI-Setup: die Pipeline reproduzierbar machen

Eine Übergabe scheitert stillschweigend, wenn CI fast genauso wie lokal ist. Wenn jemand das Projekt auf dem Laptop ausführen kann, sollte CI dieselben Befehle ausführen und dasselbe Ergebnis liefern.

Definieren Sie, was CI bei jedem Pull Request beweisen muss. Die meisten Teams brauchen nur wenig:

• Lint/Format
• Unit-Tests
• Build (Web und Server kompilieren sauber)

Integrationstests und Deploy-Schritte sind ok, aber nur wenn sie zuverlässig und klar abgegrenzt sind.

Halten Sie CI-Schritte nah an lokalen Befehlen, um Drift zu vermeiden. Wenn lokal make test ist, sollte CI auch make test ausführen. Falls kein Makefile vorhanden ist, überlegen Sie, eines hinzuzufügen und es als gemeinsamen Einstiegspunkt zu benutzen.

Env-Variablen und Secrets explizit machen

CI bricht häufig, weil es von versteckter Konfiguration abhängt. Fügen Sie eine kurze „CI variables“-Sektion in die README ein, die die exakten Namen aufführt, die CI erwartet. Trennen Sie öffentliche Konfiguration von Secrets.

Beispielnamen (an Ihr Stack anpassen): APP_ENV, DATABASE_URL, PORT, JWT_SECRET, S3_BUCKET, STRIPE_API_KEY. In CI gehören Secrets in den Secret-Store des CI-Anbieters, niemals in Commit-Dateien. Für einen Go + Postgres-Backend-Fall (häufig bei Koder.ai-Exports) notieren Sie außerdem, ob Migrationen automatisch laufen oder ein eigener Schritt nötig ist.

Merge-Schutz mit Status-Checks

Entscheiden Sie, welche Checks vor dem Merge erforderlich sind und dokumentieren Sie sie. „lint + unit tests + build“ reicht meist aus. Optionale Jobs (z. B. mobile Builds) sollten nicht blockierend sein, es sei denn, sie sind wirklich notwendig.

Machen Sie CI-Outputs leicht debugbar: geben Sie Tool-Versionen aus und sorgen Sie für klare Fehlermeldungen. Fügen Sie Caching hinzu, sobald die Pipeline stabil ist.

Beispiel-Handoff-Szenario: vom Klonen zur laufenden App

Maya erhält ein exportiertes Projekt aus Koder.ai. Typisches Setup: React-Webapp, Go-API und PostgreSQL. Sie sollte das Repo klonen und ohne Rätselbildschirm zu sehen bekommen.

Ihre ersten 30 Minuten sollten so aussehen:

1. Repo klonen und die Root-README öffnen.
2. .env.example nach .env kopieren (oder dieselben Werte in der Shell setzen) für web und api.
3. PostgreSQL starten (lokal oder via Docker) und eine leere DB anlegen.
4. Migrationen und Seeds ausführen, um einen bekannten Start-Datensatz zu bekommen.
5. Backend starten, dann Frontend, und die App im Browser laden.

Bei einer unordentlichen Übergabe trifft sie meist drei Blocker.

Erstens: App bootet und crasht mit einer vagen „missing config“-Fehlermeldung. Das Problem ist oft eine undokumentierte Variable wie AUTH_JWT_SECRET oder ein benötigtes DATABASE_URL-Format. Wenn die README jede erforderliche Variable listet, ein sicheres Beispiel zeigt und erklärt, wo sie genutzt wird, ist das schnell behoben.

Zweitens: Die API startet, aber alle Seiten zeigen „keine Daten“ oder liefern 500er. Die DB existiert, hat aber keine Tabellen oder Seed-Daten. Eine saubere Übergabe enthält ein oder zwei verlässliche Befehle: Migrationen ausführen, minimale Demo-Daten seed-en und einen Reset-Befehl für den Notfall.

Drittens: Alles läuft, aber das Frontend zeigt auf den falschen Port. Maya öffnet localhost:3000, aber die API erwartet localhost:8080, oder CORS blockiert Requests. Konsistente Defaults helfen hier: ein zentraler Ort für WEB_PORT, API_PORT und API_BASE_URL und eine README, die die erwarteten lokalen URLs nennt.

Abschluss-Checkliste, häufige Fallen und nächste Schritte

Eine Übergabe ist erst dann abgeschlossen, wenn jemand anderes das Projekt aus einem sauberen Clone ohne Nachfragen starten kann. Beweisen Sie, dass das Projekt außerhalb der Plattform überlebt.

Führen Sie einen finalen „clean clone“-Test auf einer frischen Maschine oder in einem Wegwerf-Container durch. Nutzen Sie nicht Ihren bestehenden Ordner, zwischengespeicherte Abhängigkeiten oder lokale Datenbanken. Folgen Sie exakt Ihrer README. Wenn Sie improvisieren müssen, verbessern Sie Docs oder Skripte, bis das nicht mehr nötig ist.

Schnelle Prüfungen, die die meisten Fehler auffangen:

• Die README enthält einen einzigen, copy-paste-fähigen „how to run“-Pfad für lokale Entwicklung und eine kurze „how to test“-Sektion.
• .env.example existiert und jede erforderliche Variable ist mit sicheren Beispielwerten erklärt.
• Datenbank-Bootstrap funktioniert Ende-zu-Ende: DB anlegen, Migrationen, optional Seed und ein Reset-Befehl.
• CI läuft auf einem sauberen Runner und entspricht den lokalen Befehlen.
• Ein neuer Entwickler kann eine kleine Änderung vornehmen, Tests ausführen und die Änderung in der App sehen.

Häufige Fallen sind unspektakulär, deshalb werden sie oft übersehen:

• Einmalige Schritte, die nie in die Docs kamen
• Eine README, die zur älteren Ordnerstruktur oder alten Befehlen passt
• Hartkodierte Werte (API-URLs, Feature-Flags, Keys) im Code statt in der Konfiguration
• Secrets, die informell geteilt wurden, ohne klaren, sicheren Setup-Pfad
• CI, das nur dank gecachter Artefakte oder lokaler Dienste grün läuft

Nächste Schritte: Bestimmen Sie einen Owner, der den Export innerhalb von 24–48 Stunden validiert, nicht erst Wochen später. Dieser führt den Clean-Clone-Test durch und meldet Lücken.

Wenn Sie auf Koder.ai bauen (Koder.ai), hilft es, diese Checkliste als Teil Ihres normalen Workflows zu behandeln: nutzen Sie Planning Mode, um den Run-Pfad niederzuschreiben, machen Sie Snapshots vor größeren Änderungen und exportieren Sie den Quellcode regelmäßig, damit das Handoff-Paket aktuell bleibt.