Usa questa checklist per l'esportazione del codebase creata con AI per consegnare un progetto in modo sicuro: env var, segreti, setup locale, bootstrap DB, CI e una README pratica "come eseguire".
La maggior parte dei progetti esportati fallisce per una ragione semplice: funzionavano nella piattaforma originale, dove erano già presenti default, segreti, stato del database e passaggi di build. Appena il codice esce da quella bolla, il prossimo sviluppatore deve indovinare cosa era stato dato per scontato.
Un handoff pulito significa che il progetto può essere clonato, configurato e avviato da qualcuno che non l'ha costruito, su una macchina pulita, senza lunghe comunicazioni. Non serve codice perfetto. Serve che le cose di base siano esplicite e ripetibili.
Le esportazioni si rompono sempre per gli stessi problemi: configurazioni nascoste, gestione dei segreti poco chiara, passi di setup locale vaghi, sorprese sul database e CI che funziona solo in un ambiente.
Per questo una checklist per l'esportazione del codebase costruita con AI riguarda principalmente la documentazione e la riproducibilità, non il copia/incolla dei file. Se hai costruito l'app su una piattaforma vibe-coding come Koder.ai e poi hai esportato il sorgente, il prossimo team ha comunque bisogno di una mappa: cosa impostare, cosa eseguire e cosa significa “funzionante”.
Questa checklist si concentra sugli elementi essenziali per il handoff: variabili d'ambiente, segreti, setup per lo sviluppo locale, bootstrap del database, setup della CI e una README pratica “come eseguire”. Non copre decisioni di prodotto, rifiniture UX o riprogettazioni architetturali.
La responsabilità deve essere chiara. Chi costruisce deve rendere visibili le assunzioni (docs, script, default sicuri). Chi riceve deve adattare il progetto al proprio ambiente (segreti manager, hosting, regole CI più rigide). Quando entrambe le parti sanno cosa devono fare, il passaggio diventa routine.
Un handoff pulito parte da un accordo semplice: cosa significa “fatto” quando il codice lascia la piattaforma. Senza questo, i team discutono dopo su script mancanti, dipendenze a sorpresa o quale versione fosse quella reale.
Scegli un singolo punto stabile nel tempo e trattalo come fonte di verità. Esportare a metà cambiamento è il modo per ritrovarsi con un repo che quasi gira.
Un buon punto di export è di solito uno di questi:
Aggiungi una frase che spieghi perché questo è il punto giusto per esportare. Esempio: “Tutti i flussi core passano e lo schema del database è definitivo per questo milestone.”
Scrivi un inventario breve di cosa il ricevente deve aspettarsi. Sii esplicito su ciò che è incluso e su ciò che è volutamente escluso.
Includi le basi: codice sorgente (app, servizi, package condivisi), template di config (file env di esempio), script (build, dev, test, migrazioni, seed) e note sul deployment. Includi dati di esempio solo se sono stati anonimizzati e sono sicuri.
Congela le versioni così che “funziona sulla mia macchina” non diventi il nuovo standard. Registra runtime e toolchain (Node, Go, Flutter, package manager), oltre alla versione del database (la major di PostgreSQL conta).
Infine, elenca i prerequisiti che devono essere fatti prima di eseguire qualcosa. Mantienilo breve e concreto: account richiesti, tool da installare, porte che devono essere libere e qualsiasi step one-time.
La maggior parte degli export che funzionano solo nella piattaforma originale si rompe perché impostazioni chiave non sono mai state documentate. Le variabili d'ambiente sono il colpevole più comune: vivono fuori dal repo, quindi chi clona non ha idea di quali valori siano attesi.
Tratta questo come obbligatorio per un export pulito: ogni variabile deve essere discoverable, spiegata e facile da impostare senza indovinare.
Crea una singola fonte di verità nella README di handoff: una lista di nomi di env var, cosa controllano e da dove vengono i valori. Mantieni le spiegazioni in linguaggio semplice e segnala tutto ciò che è sensibile.
Un formato semplice per ogni variabile:
Insieme a quella documentazione, includi un file .env.example nel repo. Deve contenere ogni variabile che potrebbe servire, con valori placeholder sicuri così che l'app possa partire con poche modifiche.
# 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
Alcuni dettagli evitano la maggior parte delle confusioni:
Rendi esplicito “richiesta vs opzionale”. Se la mancanza di una variabile causa un crash, dillo. Se abilita una funzionalità (invio email, pagamenti, storage), nomina la funzionalità e descrivi cosa succede quando non è impostata.
Segnala cosa cambia per ambiente. DATABASE_URL e PUBLIC_BASE_URL spesso differiscono tra dev, staging e production, mentre LOG_LEVEL può essere lo stesso ovunque. Se hai usato Koder.ai per esportare e distribuire, ricontrolla che i default della piattaforma (porte, base URL, origini consentite) siano riflessi nella doc così il comportamento resta coerente fuori dalla piattaforma.
Infine, indica come vengono caricate le env var in locale. Se il progetto si aspetta un file .env, dì dove vive e se l'app lo legge automaticamente o richiede un comando/tool.
I segreti sono valori che causerebbero danni se venissero esposti: chiavi API, password del database, token di autenticazione, segreti OAuth, chiavi private, segreti di firma webhook e simili.
Per un export, mantieni le cose semplici: il repo deve contenere solo placeholder, mai valori segreti reali. Se un segreto è necessario per avviare, includilo come placeholder chiaramente nominato in .env.example e spiega come generarne uno reale.
Un pattern pratico è separare tre cose: un file di esempio, un file locale e lo store segreti per CI/deploy. Il codice esportato dovrebbe includere il campione, ignorare il file locale e documentare come CI/hosting ricevono i segreti.
Scegli un approccio per ambiente e mantienilo consistente.
.env (gitignored) caricato dall'app, o il secrets manager locale del teamEsempio: il repo include PAYMENTS_API_KEY=replace_me. Il ricevente genera la propria chiave nel pannello del provider e la imposta nel suo .env locale e in CI. Il codice rimane identico.
Un handoff è un buon momento per ruotare i segreti, specialmente se sono mai stati usati durante una sessione condivisa della piattaforma.
.env locali.Se hai esportato da Koder.ai, tratta l'export come un nuovo ambiente e genera segreti freschi per il team ricevente.
Un handoff ha successo quando un nuovo sviluppatore può clonare il repo, eseguire pochi comandi e vedere l'app funzionare senza indovinare. Punta a prerequisiti prevedibili, un ordine di comandi chiaro e un breve blocco “come eseguire” che corrisponda alla realtà.
Metti questi in cima alla README così nessuno deve dedurli dagli errori:
Se il progetto è stato costruito su Koder.ai, allinea il setup locale con ciò che hai esportato (stessa struttura cartelle, stessi comandi di avvio). Non dare per scontato “Postgres è già in esecuzione” a meno che tu non lo dica.
Metti i comandi esatti nell'ordine in cui un nuovo collega li deve eseguire. Devono essere copiabili:
# 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
Aggiungi una sezione minimale per test e build subito sotto:
# Tests
cd server && go test ./...
cd web && npm test
# Build
cd web && npm run build
cd server && go build ./...
La maggior parte dei problemi “non parte” rientra in poche categorie:
Versioni sbagliate (Node/Go). Sintomi: errori di dipendenze o di compilazione. Soluzione: installa le versioni necessarie e riesegui gli install.
Valori env mancanti. Sintomi: configurazioni “undefined”, fallimenti di autenticazione, errori 500. Soluzione: confronta .env con .env.example e riempi i valori richiesti.
Database non raggiungibile. Sintomi: connection refused, “database does not exist.” Soluzione: avvia Postgres, verifica host/porta/user e segui esattamente i passaggi di init del DB.
Quando un progetto è esportato da una piattaforma, il database è spesso la prima cosa che si rompe su una macchina nuova. L'obiettivo è semplice: un collega deve poter passare da “ho clonato il repo” a “l'app gira con dati reali” senza indovinare.
Scrivi i passaggi minimi per un setup PostgreSQL fresco e metti i comandi in script dove possibile. Il tuo handoff dovrebbe rispondere a quattro domande:
Se hai già script (target Makefile, shell script, task runner), usali invece di descrivere passaggi manuali. Se non li hai, aggiungine qualcuno ora.
Mantieni il flusso consistente tra ambienti (locale, CI, staging). Un buon baseline è:
# 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
Per i seed, preferisci dati minimi funzionanti invece di un dump simile alla produzione. I seed dovrebbero essere sicuri da eseguire più volte (inserimenti idempotenti, o una regola chiara “esegui solo su DB vuoto”).
Per i reset, sii esplicito sulla sicurezza. Un comando di reset dovrebbe mirare per default solo allo sviluppo locale. Se fornisci uno script distruttivo, aggiungi una protezione (per esempio richiedere CONFIRM_RESET=1, o controllare APP_ENV=development). Definisci anche cosa significa “reset”: droppare e ricreare, svuotare tabelle o ripristinare uno snapshot noto.
Un handoff va storto quando il repo sembra un cassetto di cose sparse. Chi arriva dopo deve capire cosa conta, cosa è generato e dove cambiare le impostazioni.
Commetti le cose che rendono il progetto ripetibile: lockfile, file di migrazione, piccoli template di configurazione come .env.example e qualsiasi script che bootstrappi l'app.
Tieni fuori dal controllo versione file personali, generati o sensibili: file di ambiente locali, impostazioni dell'editor, output di build, log, cache e qualsiasi cosa dia accesso (API key, password DB, file account di servizio).
Una regola semplice: se cambiarlo impatta tutti, committalo. Se cambia per macchina o ambiente, documentalo e tienilo fuori dal repo.
Se includi una breve nota “commit vs ignore”, mantienila sintetica:
README, lockfiles, migrazioni, script di seed, .env.example.env, file di segreti, cartelle di build, log, cache localiAggiungi una mappa breve delle directory così la struttura è ovvia senza cliccare troppo. Esempio: “/backend servizio API, /web frontend, /mobile app, /db migrazioni e seed, /scripts helper setup.”
Se hai esportato da Koder.ai, tratta l'export come l'inizio di questa pulizia: rimuovi il clutter generato, conferma le regole di ignore e scrivi la mappa delle cartelle.
Un handoff fallisce silenziosamente quando la CI è quasi uguale a locale. Se qualcuno può eseguire il progetto sul proprio laptop, CI dovrebbe eseguire gli stessi comandi e ottenere lo stesso risultato.
Decidi cosa la CI deve dimostrare a ogni pull request. La maggior parte dei team ha bisogno di un set piccolo:
Test di integrazione e step di deploy vanno bene, ma solo se sono affidabili e chiaramente limitati.
Mantieni i passaggi CI vicini ai comandi locali per evitare deriva. Se locale è make test, anche CI dovrebbe eseguire make test. Se non hai un Makefile (o un equivalente), considera di aggiungerne uno e usarlo come punto d'ingresso condiviso.
CI fallisce più spesso perché dipende da configurazioni nascoste. Aggiungi una breve sezione “variabili CI” nella README elencando i nomi esatti che CI si aspetta. Separa configurazione pubblica da segreti.
Esempi di nomi (adatta allo stack): APP_ENV, DATABASE_URL, PORT, JWT_SECRET, S3_BUCKET, STRIPE_API_KEY. In CI, i segreti devono venire dallo store segreti della CI, mai da file committati. Per un backend Go + Postgres (comune negli export Koder.ai), nota anche se le migrazioni vengono eseguite automaticamente o richiedono uno step esplicito.
Decidi quali check sono richiesti prima del merge e scrivili. “lint + unit tests + build” è spesso sufficiente. Se aggiungi job opzionali (come build mobile), mantienili non bloccanti a meno che non siano davvero necessari.
Rendi inoltre l'output CI facile da debuggare: stampa le versioni degli strumenti e fallisci con messaggi chiari. Aggiungi caching dopo che la pipeline è stabile.
Maya riceve un progetto esportato da Koder.ai. Ha una configurazione tipica: web React, API Go e database PostgreSQL. Dovrebbe poterlo clonare e arrivare a una schermata funzionante senza indovinare.
I suoi primi 30 minuti dovrebbero essere:
.env.example in .env (o impostare gli stessi valori nella shell) per web e api.In un handoff disordinato, incontra di solito tre blocchi.
Primo: l'app parte, poi crasha con un errore vago “missing config”. Il problema reale è una variabile non documentata come AUTH_JWT_SECRET o un formato DATABASE_URL richiesto. Se la README elenca ogni variabile richiesta, mostra un valore d'esempio sicuro e spiega dove è usata, la soluzione è rapida.
Secondo: l'API parte, ma tutte le pagine mostrano “no data” o falliscono con errori 500. Il database esiste, ma non ha tabelle o dati seed. Un handoff pulito include uno o due comandi affidabili: esegui migrazioni, seed di demo minimi e un comando di reset per quando qualcosa va storto.
Terzo: tutto è in esecuzione, ma il frontend punta alla porta sbagliata. Maya apre localhost:3000, ma l'API si aspetta localhost:8080, o CORS blocca le richieste. Qui servono default coerenti: un punto unico per impostare WEB_PORT, API_PORT e API_BASE_URL, con la README che dichiara gli URL locali attesi.
Un handoff è concluso solo quando qualcuno può eseguire il progetto da un clone pulito senza fare domande. Dimostra che il progetto sopravvive fuori dalla piattaforma.
Esegui un ultimo test di “clean clone” su una macchina fresca o in un container usa-e-getta. Non riutilizzare cartelle esistenti, dipendenze in cache o database locali. Segui la tua README esattamente. Se devi improvvisare, correggi docs o script finché non è più necessario.
Controlli rapidi che catturano la maggior parte dei fallimenti:
.env.example esiste e ogni variabile richiesta è spiegata con valori d'esempio sicuri.Le trappole comuni sono banali, ed è per questo che si trascurano:
Prossimi passi: assegna un owner che convalidi l'export entro 24–48 ore, non settimane dopo. Deve eseguire il test di clean clone e riportare le lacune.
Se stai costruendo su Koder.ai (Koder.ai), aiuta considerare questa checklist come parte del flusso di lavoro: usa la planning mode per scrivere il percorso di avvio, scatta snapshot prima di grandi cambi, ed esporta il sorgente regolarmente così il pacchetto di handoff resta aggiornato.
Scegli un singolo punto stabile e trattalo come fonte di verità.
Al minimo, includi:
.env.example e documentazione chiara sulle env varEscludi qualsiasi cosa sensibile e credenziali reali.
Documenta ogni env var in un unico posto (di solito la README radice) e fornisci un .env.example.
Per ogni variabile elenca:
Non committare segreti. Committa solo placeholder.
Una configurazione semplice:
.env.example con placeholder replace_me.env (ignorato da git)Documenta anche come generare ogni segreto richiesto (ad esempio: “genera una stringa casuale di 32+ caratteri per ”).
Ruota tutto ciò che potrebbe essere stato condiviso o riutilizzato.
Un ordine pratico per la rotazione:
.env localiTratta l'export come un nuovo ambiente e parti puliti.
Rendi la prima esecuzione “copia, incolla, esegui”:
Se serve Docker o Make, dì esplicitamente—non lasciare che lo scoprono dagli errori.
Sì—perché le major version di PostgreSQL e le versioni degli strumenti possono cambiare il comportamento.
Registra almeno:
Blocca le versioni quando puoi, e stampa le versioni in CI così gli errori sono più facili da debuggare.
Fornisci un percorso ripetibile “da zero”:
Aggiungi protezioni per azioni distruttive (ad esempio richiedere APP_ENV=development o un flag di conferma).
Mantieni CI vicino ai comandi locali e rendi la configurazione esplicita.
Se servono migrazioni per i test, documenta se la CI le esegue automaticamente o come step esplicito.
Esegui un “clean clone” test:
Se devi improvvisare anche una sola volta, correggi la doc o gli script finché non è più necessario. È il modo più veloce per trovare assunzioni nascoste dell'ambiente originale (incluse piattaforme vibe-coding come Koder.ai).
JWT_SECRET