Gebruik deze checklist voor het exporteren van een AI-gegenereerde codebase om een project veilig over te dragen: env-vars, secrets, lokale setup, database-bootstrap, CI en een duidelijke run-README.
De meeste geëxporteerde projecten falen om een eenvoudige reden: ze draaiden prima binnen het originele platform, waar defaults, secrets, databasetoestand en build-stappen al aanwezig waren. Zodra de code die bubbel verlaat, moet de volgende ontwikkelaar raden wat er was verondersteld.
Een schone overdracht betekent dat het project gekloond, geconfigureerd en opgestart kan worden door iemand die het niet gebouwd heeft, op een verse machine, zonder veel heen-en-weer. Het vereist geen perfecte code. Het vereist dat de basis expliciet en herhaalbaar is.
Exports breken om dezelfde redenen steeds opnieuw: verborgen configuratie, onduidelijke omgang met secrets, vage stappen voor lokale setup, database verrassingen en CI die alleen in één omgeving werkt.
Daarom gaat een checklist voor het exporteren van een AI-gegenereerde codebase vooral over documentatie en reproduceerbaarheid, niet over het kopiëren van bestanden. Als je de app in een vibe-coding platform zoals Koder.ai hebt gebouwd en daarna de broncode hebt geëxporteerd, heeft het volgende team nog steeds een kaart nodig: wat in te stellen, wat te draaien en wat 'werkend' betekent.
Deze checklist richt zich op de overdracht-essentials: omgevingsvariabelen, secrets, lokale ontwikkelsetup, database-bootstrap, CI-setup en een praktische 'hoe te draaien' README. Het behandelt geen productbeslissingen, UX-polijstwerk of het herontwerpen van de architectuur.
Eigendom moet ook duidelijk zijn. De bouwer is verantwoordelijk voor het zichtbaar maken van aannames (docs, scripts, veilige defaults). De ontvanger is verantwoordelijk voor het aanpassen van het project aan hun omgeving (secrets manager, hosting, strengere CI-regels). Als beide partijen hun rol kennen, wordt de overdracht routine.
Een schone overdracht begint met een eenvoudige afspraak: wat betekent 'klaar' wanneer de code het platform verlaat. Zonder dat ruziën teams later over ontbrekende scripts, verrassende afhankelijkheden of welke versie de echte was.
Kies één stabiel tijdspunt en behandel dat als de bron van waarheid. Exporteren halverwege een wijziging is hoe teams bij een repo terechtkomen die bijna draait.
Een goed exportpunt is meestal een van de volgende:
Voeg één zin toe die uitlegt waarom dit het juiste exportpunt is. Voorbeeld: 'Alle kernflows slagen en het databaseschema is definitief voor deze mijlpaal.'
Schrijf een korte inventaris van wat de ontvanger mag verwachten. Wees expliciet over wat inclusief is en wat opzettelijk niet is inbegrepen.
Neem de basis op: sourcecode (apps, services, gedeelde packages), config-templates (voorbeeld env-bestanden), scripts (build, dev, test, migraties, seed) en deployment-notities. Voeg alleen sampledata toe als die opgeschoond en veilig is.
Bevries vervolgens versies zodat 'werkt op mijn machine' geen nieuwe baseline wordt. Leg runtime- en toolchain-versies vast (Node, Go, Flutter, package manager), plus de databaseversie (PostgreSQL major versie is belangrijk).
Noem ten slotte de vereisten die gedaan moeten zijn voordat iets gedraaid kan worden. Houd het kort en concreet: vereiste accounts, geïnstalleerde tools, vrije poorten en eventuele eenmalige setup-stappen.
De meeste 'het werkte op het platform' exports breken omdat belangrijke instellingen nooit zijn opgeschreven. Omgevingsvariabelen zijn de gebruikelijke boosdoener: ze leven buiten de repo, dus een nieuwe teamgenoot clonet het project en heeft geen idee welke waarden verwacht worden.
Behandel dit als verplicht voor een schone export: elke variabele moet vindbaar, uitgelegd en makkelijk in te stellen zijn zonder te gokken.
Maak één bron van waarheid in je handoff-README: een lijst van env-var namen, wat ze regelen en waar waarden vandaan komen. Houd de uitleg eenvoudig en benoem alles wat security-gerelateerd is.
Een eenvoudig format voor elke variabele:
Naast die documentatie, lever een .env.example bestand in de repo. Het moet elke variabele bevatten die mogelijk nodig is, met veilige placeholder-waarden zodat de app met minimale aanpassingen kan starten.
# 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
Een paar details voorkomen de meeste verwarring:
Maak 'verplicht versus optioneel' expliciet. Als een ontbrekende variabele een crash veroorzaakt, zeg dat. Als het een feature inschakelt (email, betalingen, bestandsopslag), benoem de feature en omschrijf wat er gebeurt wanneer het niet is ingesteld.
Noem wat per omgeving verandert. DATABASE_URL en PUBLIC_BASE_URL verschillen vaak tussen dev, staging en production, terwijl LOG_LEVEL overal hetzelfde kan zijn. Als je Koder.ai gebruikte om te exporteren en te deployen, controleer dan dat platform-defaults (poorten, basis-URL's, toegestane origins) zijn terug te vinden in de docs zodat het gedrag buiten het platform consistent blijft.
Tot slot: vermeld hoe env-vars lokaal geladen worden. Als het project een .env bestand verwacht, zeg waar het staat en of de app het automatisch leest of een commando/tool nodig heeft.
Secrets zijn waarden die schade veroorzaken als ze lekken: API-keys, databasewachtwoorden, auth-tokens, OAuth-clientsecrets, private keys, webhook-signing secrets en soortgelijke waarden.
Voor een export, hou het simpel: de repo bevat alleen placeholders, nooit echte secret-waarden. Als een secret vereist is om te starten, neem het op als duidelijk benoemde placeholder in .env.example en leg uit hoe je een echte genereert.
Een praktisch patroon is om drie dingen te scheiden: een samplebestand, een lokaal bestand en een CI of deployment secret store. Je geëxporteerde code moet de sample bevatten, het lokale bestand negeren, en documenteren hoe CI/hosting secrets ontvangt.
Kies per omgeving één aanpak en houd je eraan.
.env (gitignored) geladen door de app, of de lokale secrets manager van je teamVoorbeeld: de repo bevat PAYMENTS_API_KEY=replace_me. De ontvanger genereert hun eigen sleutel in het provider-dashboard en zet die in hun lokale .env en in CI. De code blijft hetzelfde.
Een overdracht is een goed moment om secrets te roteren, vooral als ze ooit in een gedeelde platformsessie zijn gebruikt.
.env bestanden.Als je exporteerde van Koder.ai, behandel de export als een nieuwe omgeving en genereer verse secrets voor het ontvangende team.
Een overdracht is geslaagd wanneer een nieuwe ontwikkelaar de repo kan clonen, een paar commando's kan uitvoeren en de app werkend ziet zonder giswerk. Streef naar voorspelbare vereisten, een duidelijke volgorde van commando's en een korte 'hoe te draaien' sectie die overeenkomt met de werkelijkheid.
Zet deze bovenaan je README zodat niemand ze uit foutmeldingen hoeft af te leiden:
Als het project op Koder.ai is gebouwd, houd lokale setup in lijn met wat je exporteerde (zelfde mappenstructuur, dezelfde startcommando's). Ga er niet van uit dat 'Postgres al draait' tenzij je dat zegt.
Zet de exacte commando's in de volgorde waarin een nieuwe collega ze moet uitvoeren. Maak ze copy-pastebaar:
# 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
Voeg een minimale test- en build-sectie direct eronder toe:
# Tests
cd server && go test ./...
cd web && npm test
# Build
cd web && npm run build
cd server && go build ./...
De meeste 'het draait niet' issues vallen in een paar categorieën:
Verkeerde versies (Node/Go). Symptomen: dependency- of compile-fouten. Oplossing: installeer de vastgelegde versies en voer installs opnieuw uit.
Ontbrekende env-waarden. Symptomen: 'undefined' config, auth-fouten, 500-fouten. Oplossing: vergelijk .env met .env.example en vul vereiste waarden in.
Database niet bereikbaar. Symptomen: connection refused, 'database does not exist.' Oplossing: start Postgres, controleer host/poort/user en voer de database-init stappen precies zoals beschreven uit.
Wanneer een project uit een platform wordt geëxporteerd, is de database vaak het eerste dat faalt op een nieuwe machine. Het doel is simpel: een collega moet van 'ik heb de repo gekloond' naar 'de app draait met echte data' kunnen gaan zonder te moeten raden.
Schrijf de minimale stappen voor een verse PostgreSQL-setup op en zet de commando's waar mogelijk in scripts. Je handoff moet vier vragen beantwoorden:
Als je al scripts hebt (Makefile-targets, shellscripts, task-runner commando's), gebruik die dan in plaats van omschrijvingen van handmatige stappen. Als je ze niet hebt, voeg er dan nu een kleine set aan toe.
Houd de flow consistent over omgevingen (lokaal, CI, staging). Een goed basisvoorbeeld ziet er zo uit:
# 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
Voor seeds hebben minimale werkende data de voorkeur boven een productie-achtige dump. Seeds moeten veilig meerdere keren te draaien zijn (idempotente inserts, of een duidelijke 'run only on empty DB' regel).
Voor resets wees expliciet over veiligheid. Een reset-commando moet standaard alleen lokale ontwikkeling targeten. Als je een destructief script levert, voeg een vangrail toe (bijv. vereisen dat CONFIRM_RESET=1 is of checken dat APP_ENV=development). Definieer ook wat 'reset' betekent: drop & recreate, tabellen wissen of herstellen vanaf een bekende snapshot.
Een overdracht gaat mis als de repo aanvoelt als een rommelbak. Iemand nieuw moet kunnen zien wat belangrijk is, wat gegenereerd is en waar instellingen te wijzigen zijn.
Commit de dingen die het project reproduceerbaar maken: lockfiles, migratiebestanden, kleine config-templates zoals .env.example en scripts die de app bootstrapten.
Houd persoonlijke, gegenereerde of gevoelige bestanden uit versiebeheer: lokale environment-bestanden, editor-instellingen, build-output, logs, caches en alles dat toegang verleent (API-keys, databasewachtwoorden, service account bestanden).
Een eenvoudige regel: als het wijzigen ervan iedereen beïnvloedt, commit het. Als het per machine of omgeving verandert, documenteer het en houd het uit de repo.
Als je een korte 'commit vs ignore' notitie toevoegt, houd het bondig:
README, lockfiles, migraties, seed-scripts, .env.example.env, secrets-bestanden, build-mappen, logs, lokale cachesVoeg een korte directory-map toe zodat de structuur duidelijk is zonder rond te klikken. Voorbeeld: '/backend' API-service, '/web' frontend, '/mobile' app, '/db' migraties en seeds, '/scripts' setup-helpers.
Als je exporteerde van Koder.ai, beschouw de export als het begin van deze opruimronde: verwijder gegenereerde rommel, controleer ignore-regels en schrijf de directory-map.
Een overdracht faalt stilletjes als CI bijna hetzelfde is als lokaal. Als iemand het project op zijn laptop kan draaien, moet CI dezelfde commando's draaien en hetzelfde resultaat geven.
Bepaal wat CI op elke pull request moet bewijzen. De meeste teams hebben maar een kleine set nodig:
Integratietests en deploy-stappen zijn prima, maar alleen als ze betrouwbaar en duidelijk afgebakend zijn.
Houd CI-stappen dicht bij lokale commando's om drift te voorkomen. Als lokaal make test is, moet CI ook make test draaien. Als je geen Makefile (of equivalent) hebt, overweeg er een toe te voegen en deze als gedeelde ingangsroute te gebruiken.
CI breekt meestal omdat het afhankelijk is van verborgen configuratie. Voeg een korte 'CI variables' sectie toe aan je README met de exacte namen die CI verwacht. Scheid publieke config van secrets.
Voorbeeldnamen (pas aan naar je stack): APP_ENV, DATABASE_URL, PORT, JWT_SECRET, S3_BUCKET, STRIPE_API_KEY. In CI moeten secrets uit de CI secret store komen, nooit uit gecommitte bestanden. Voor een Go + Postgres backend (veelvoorkomend in Koder.ai exports), vermeld ook of migraties automatisch draaien of een expliciete stap vereisen.
Bepaal welke checks verplicht zijn voor merge en schrijf ze op. 'lint + unit tests + build' is meestal voldoende. Als je optionele jobs toevoegt (bijv. mobile builds), houd ze niet-blockerend tenzij echt nodig.
Maak CI-fouten makkelijk te debuggen: print toolversies en laat duidelijke foutmeldingen zien. Voeg caching toe zodra de pijplijn stabiel is.
Maya krijgt een geëxporteerd project uit Koder.ai. Het is een typische setup: een React webapp, een Go API en een PostgreSQL database. Ze moet de repo kunnen clonen en zonder gokken een werkend scherm krijgen.
Haar eerste 30 minuten zouden er zo uit moeten zien:
.env.example naar .env (of zet dezelfde waarden in haar shell) voor zowel web als api.In een rommelige overdracht loopt ze meestal tegen drie blokkades aan.
Eerst: de app boot, en crasht daarna met een vage 'missing config' fout. De echte oorzaak is een ongedocumenteerde variabele zoals AUTH_JWT_SECRET of een vereist DATABASE_URL-format. Als de README elke vereiste variabele vermeldt, een veilig voorbeeld toont en uitlegt waar het gebruikt wordt, is dit snel opgelost.
Tweede: de API start, maar elke pagina toont 'geen data' of geeft 500-fouten. De database bestaat, maar heeft geen tabellen of seed-data. Een schone overdracht bevat één of twee betrouwbare commando's: voer migraties uit, seed minimale demo-data en een reset-commando voor als er iets misgaat.
Derde: alles draait, maar de frontend wijst naar de verkeerde poort. Maya opent localhost:3000, maar de API verwacht localhost:8080, of CORS blokkeert requests. Consistente defaults helpen hier: één plek om WEB_PORT, API_PORT en API_BASE_URL te zetten, met in de README de verwachte lokale URL's.
Een overdracht is pas klaar als iemand anders het project van een schone clone kan draaien zonder vragen te stellen. Toon dat het project buiten het platform overleeft.
Doe één laatste 'clean clone' test op een verse machine of een wegwercontainer. Hergebruik geen bestaande map, gecachte dependencies of lokale database. Volg exact je eigen README. Als je moet improviseren, verbeter dan de docs of scripts totdat dat niet meer nodig is.
Snelchecks die de meeste fouten vangen:
.env.example bestaat en elke vereiste variabele is uitgelegd met veilige voorbeeldwaarden.Veelvoorkomende valkuilen zijn saai, daarom worden ze gemist:
Volgende stappen: wijs één eigenaar aan om de export binnen 24–48 uur te valideren, niet weken later. Laat die persoon de clean clone test doen en hiaten rapporteren.
Als je bouwt op Koder.ai (Koder.ai), helpt het om deze checklist onderdeel van je normale workflow te maken: gebruik de planningmodus om het runpad op te schrijven, maak snapshots vóór grote wijzigingen en exporteer broncode regelmatig zodat het handoff-pakket actueel blijft.
Kies één stabiel punt en behandel dat als de bron van waarheid.
Minimaal opnemen:
.env.example en duidelijke documentatie van env-varsLaat alles wat gevoelig is en echte credentials weg.
Documenteer elke env-var op één plek (doorgaans de root README) en lever een .env.example mee.
Voor elke variabele, vermeld:
Commit geen secrets. Commit alleen placeholders.
Een eenvoudige opzet:
.env.example met replace_me placeholders.env (gitignored)Documenteer ook hoe je elk vereist secret genereert (bijvoorbeeld 'maak een willekeurige string van 32+ tekens voor ').
Roteer alles wat gedeeld of hergebruikt kan zijn.
Een praktische volgorde:
.env bijBehandel de export als een nieuwe omgeving en begin schoon.
Maak de eerste run 'copy, paste, run':
Als het project Docker of Make nodig heeft, vermeld dat expliciet—maak mensen het niet via foutmeldingen laten ontdekken.
Ja—PostgreSQL major versies en toolversies kunnen gedrag veranderen.
Noteer ten minste:
Pin versies waar mogelijk en print versies in CI zodat fouten makkelijker te debuggen zijn.
Bied een herhaalbaar 'from zero' pad:
Voeg beschermingen toe aan destructieve acties (bijv. vereis APP_ENV=development of een bevestigingsflag).
Houd CI dicht bij lokale commando's en maak configuratie expliciet.
Als migraties nodig zijn voor tests, vermeld of CI die automatisch uitvoert of dat het een expliciete stap is.
Voer een 'clean clone' test uit:
Als je één keer moet improviseren, pas de docs of scripts aan tot dat niet meer nodig is. Dat onthult snel verborgen aannames uit de originele buildomgeving (ook bij vibe-coding platforms zoals Koder.ai).
JWT_SECRET