Verwenden Sie diese Checkliste für den Export einer KI-erstellten Codebase, um ein Projekt sicher zu übergeben: Env-Variablen, Secrets, lokales Setup, Datenbank-Bootstrap, CI und eine klare Run-README.
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.
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.
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:
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."
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.
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:
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 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.
Wählen Sie pro Umgebung einen Ansatz und bleiben Sie dabei.
.env (gitignored), geladen von der App, oder der lokale Secret-Manager des TeamsBeispiel: 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.
Eine Übergabe ist ein guter Zeitpunkt, Secrets zu rotieren, besonders wenn sie jemals in einer geteilten Plattform-Session verwendet wurden.
.env-Dateien.Wenn Sie aus Koder.ai exportiert haben, behandeln Sie den Export als neue Umgebung und erzeugen Sie frische Secrets für das empfangende Team.
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.
Stellen Sie diese an den Anfang der README, damit niemand sie aus Fehlermeldungen ableiten muss:
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.
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 ./...
Die meisten „läuft nicht“ Probleme fallen in ein paar Kategorien:
Falsche Versionen (Node/Go). Symptome: Abhängigkeits- oder Kompilierungsfehler. Lösung: installierte gepinnte Versionen nutzen und Installation wiederholen.
Fehlende Env-Werte. Symptome: „undefined“ Config, Auth-Fehler, 500er. Lösung: .env mit .env.example vergleichen und erforderliche Werte ergänzen.
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.
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.
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:
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.
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.
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:
README, Lockfiles, Migrationen, Seed-Skripte, .env.example.env, Secret-Dateien, Build-Ordner, Logs, lokale CachesFü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.
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:
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.
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.
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.
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:
.env.example nach .env kopieren (oder dieselben Werte in der Shell setzen) für web und api.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.
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:
.env.example existiert und jede erforderliche Variable ist mit sicheren Beispielwerten erklärt.Häufige Fallen sind unspektakulär, deshalb werden sie oft übersehen:
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.
Wählen Sie einen klaren, stabilen Zeitpunkt und behandeln Sie ihn als Quelle der Wahrheit.
Mindestens enthalten sein sollten:
.env.example und klare Dokumentation zu UmgebungsvariablenLassen Sie sensible Daten und echte Zugangsdaten weg.
Dokumentieren Sie jede Umgebungsvariable an einer Stelle (meist die Root-README) und liefern Sie eine .env.example mit.
Für jede Variable angeben:
Committen Sie keine Secrets. Nehmen Sie nur Platzhalter auf.
Ein einfacher Ansatz:
.env.example mit replace_me-Platzhaltern.env (gitignored)Dokumentieren Sie außerdem, wie jedes benötigte Secret erzeugt wird (z. B. „erzeuge einen zufälligen String mit 32+ Zeichen für “).
Rotieren Sie alles, was geteilt oder wiederverwendet worden sein könnte.
Praktische Reihenfolge:
.env-Dateien aktualisierenBehandeln Sie den Export wie eine neue Umgebung und beginnen Sie sauber.
Machen Sie den ersten Start zu einem „Kopieren, Einfügen, Ausführen":
Wenn Docker oder Make benötigt werden, sagen Sie das deutlich—lassen Sie es niemanden erst durch Fehlermeldungen herausfinden.
Ja—weil große Unterschiede bei PostgreSQL-Major-Versionen und Toolversionen Verhalten verändern können.
Notieren Sie mindestens:
Pinnen Sie Versionen, wenn möglich, und geben Sie in CI die Versionen aus, damit Fehler leichter zu debuggen sind.
Liefern Sie einen reproduzierbaren „von null“-Pfad:
Fügen Sie Sicherheitsmaßnahmen für destruktive Aktionen hinzu (z. B. Prüfung APP_ENV=development oder ein Bestätigungs-Flag).
Halten Sie CI nah an den lokalen Befehlen und machen Sie die Konfiguration explizit.
Wenn Tests Migrationen benötigen, dokumentieren Sie, ob CI sie automatisch ausführt oder ob es einen expliziten Schritt gibt.
Führen Sie einen „clean clone“-Test aus:
Wenn Sie einmal improvisieren müssen, beheben Sie die Dokumentation oder Skripte, bis das nicht mehr nötig ist. So finden Sie versteckte Annahmen aus der ursprünglichen Build-Umgebung (inkl. vibe-coding-Plattformen wie Koder.ai).
JWT_SECRET