Scopri come esportare il codice sorgente da una piattaforma vibe-coding e prendere possesso pulito: esegui in locale, configura CI, gestisci i segreti e prepara un repo pronto per il passaggio di consegne.
Possedere il codice è più che ricevere uno zip da una piattaforma. Significa poter buildare, eseguire, modificare e distribuire l'app senza dipendere dall'workspace originale, da pulsanti speciali o da impostazioni nascoste. Un progetto che possiedi davvero si comporta come un repo normale: un nuovo collega può clonarlo, avviarlo su un laptop e distribuirlo con una pipeline standard.
La maggior parte delle ansie da lock-in nasce da pochi buchi ricorrenti:
Un'altra sorpresa comune è che l'app funzioni sulla versione hostata ma non in locale perché variabili d'ambiente, setup del database o segreti non sono mai stati resi espliciti.
Un export pulito da una piattaforma vibe-coding dovrebbe portare a quattro risultati:
Questo è importante anche se non pensi mai di abbandonare la piattaforma. Una solida postura di ownership è una forma di assicurazione: riduce i rischi, facilita audit e semplifica negoziazioni se assumi un'agenzia, raccogli finanziamenti o cambi team.
Se hai usato Koder.ai, l'export può includere stack comuni come una web app React, un backend Go, PostgreSQL o una mobile app Flutter. Lo stack importa meno del principio: tutto ciò che serve per eseguire dovrebbe essere visibile nel repository, non intrappolato in un ambiente hostato.
Immagina un founder che consegna un'app a un contractor. “Ecco il repo” dovrebbe essere sufficiente. Il contractor non dovrebbe aver bisogno di accesso al progetto originale sulla piattaforma per trovare l'API base URL, creare lo schema del database o imparare a buildare il frontend.
Dopo l'export dovresti avere un repository normale che puoi aprire in un editor, eseguire sul tuo laptop e consegnare a un altro team senza dipendere dalla piattaforma originale.
Negli export da Koder.ai i progetti spesso corrispondono a strutture familiari: una web app React, un backend Go e (se presente) una mobile app Flutter. I nomi delle cartelle variano, ma il repo dovrebbe rendere ovvio dove vive ogni parte e come si collegano.
Comincia localizzando i punti di ingresso e il flusso previsto. Ti serve il primo file che avvia ogni app, più gli script che mostrano come sviluppare ed eseguire l'app.
Segnali tipici:
package.json e una cartella src/ (spesso con main.tsx o simili)go.mod e una cartella cmd/ o un main.gopubspec.yaml di Flutter e lib/main.dartREADME top-level o un Makefile che descrive come avviare tuttodocker-compose.yml se l'export è pensato per girare come insieme di serviziLe dipendenze dovrebbero essere bloccate. Per JavaScript questo significa un lockfile (package-lock.json, yarn.lock o pnpm-lock.yaml). Per Go significa go.mod e go.sum. L'assenza di pin non rende impossibile eseguire il progetto, ma rende le build ripetibili più difficili.
La configurazione dovrebbe stare separata dal codice. Cerca file di esempio come .env.example o config.example.yaml. Non dovresti trovare segreti reali (API key, password di produzione) committati nell'export. Se li trovi, trattali come una perdita e ruotali.
Per il lavoro su database, trova una cartella di migrazioni (migrations/, db/migrations/) o file SQL con timestamp. In un'app Go + PostgreSQL potresti anche trovare un piccolo runner di migrazioni o uno script che le applica.
Un controllo rapido: localizza prima i comandi di build e run (npm run dev, go run, make e simili). Se uno script dipende da un comando disponibile solo sulla piattaforma, sostituiscilo con strumenti standard prima di dichiarare il repo indipendente.
Tratta l'export come un artifact di release. Prima di eseguire qualsiasi cosa, fai un rapido controllo “è tutto qui?”. I pezzi mancanti sono più facili da trovare ora che dopo aver iniziato a cambiare il codice.
Un controllo pratico di completezza è cercare le “radici” di ogni parte: un package.json per una web app React, un go.mod per un backend Go e file di migrazione/seed per PostgreSQL.
Crea un nuovo repository Git dalla cartella esportata, poi committa esattamente quello che hai ricevuto prima di correggere qualsiasi cosa. Questo ti dà una baseline pulita e rende le modifiche successive facili da revisionare.
git init
# Optional: set default branch name
# git branch -M main
git add -A
git commit -m "Initial export"
Ora esegui in locale in passi piccoli e verificabili. Installa le dipendenze, crea la configurazione locale, avvia prima il database, poi il backend, poi il frontend. Mentre procedi, annota ogni comando che usi davvero. Quelle note diventano il tuo README.
Ecco una semplice sequenza di comandi che puoi adattare alla struttura esportata:
# Frontend
cd web
npm install
npm run dev
# Backend
cd ../server
go mod download
go run ./cmd/server
Un server può avviarsi mentre l'app è ancora rotta. Conferma che possa leggere e scrivere dati.
Scegli controlli rapidi che si adattino al prodotto:
Una volta che hai un run locale funzionante, trasforma le note in un vero README.md con comandi copy‑paste: dove eseguire i comandi, l'ordine per avviare i servizi e quali variabili d'ambiente sono richieste.
Un export può anche partire, ma dare ancora la sensazione di essere "generato" anziché posseduto. Un repo pronto per il handoff rende ovvio dove stanno le cose, come eseguire il progetto e come mantenerlo coerente.
Inizia con un layout chiaro a livello top. I nomi contano meno della coerenza.
apps/ per frontend rivolti agli utenti (web, mobile)services/ per API backend, worker e jobshared/ per tipi e utility condiviseinfra/ per template di deploy, script ed esempi d'ambientedocs/ per note architetturali e runbookPoi aggiungi un piccolo set di file che riducono l'indovinare:
README.md con prerequisiti e comandi esattiCONTRIBUTING.md con poche regole (branch, PR, niente segreti).gitignore per tenere fuori da Git file di ambiente locali e output di buildMantieni il README pratico. Se il repo include più parti (frontend React, API Go, PostgreSQL), spiega chiaramente l'ordine in cui avviarle e dove si trova la configurazione (per esempio, "copia .env.example in .env").
Esegui un controllo da macchina fresca: clona in una cartella nuova e segui il tuo README. Se hai esportato da Koder.ai, tratta l'export come il primo commit di un nuovo progetto indipendente e solo allora invita altri a collaborare.
Un buon setup locale risponde a una domanda rapidamente: un nuovo utente riesce a far partire l'app in meno di 15 minuti senza indovinare?
Scegli un approccio locale predefinito e sii esplicito. Le installazioni native sono veloci per chi ha già gli strumenti giusti. I container sono più consistenti tra macchine ma aggiungono overhead. Se supporti entrambi, indica uno come predefinito e l'altro come opzionale.
Un pattern semplice che funziona: una pagina README, un file env di esempio e un comando di bootstrap.
Committa un file di esempio con valori finti così le persone sanno cosa impostare senza esporre segreti.
# .env.example (valori di esempio)
APP_ENV=local
PORT=8080
DATABASE_URL=postgres://app_user:app_pass@localhost:5432/app_db?sslmode=disable
JWT_SECRET=change-me
API_BASE_URL=http://localhost:8080
Nel README, spiega dove mettere il file reale (per esempio, "copia in .env") e quali variabili sono obbligatorie o opzionali.
Aggiungi un piccolo script che esegua i passi noiosi nell'ordine giusto. Mantienilo leggibile.
#!/usr/bin/env bash
set -euo pipefail
cp -n .env.example .env || true
# Backend deps
cd backend
go mod download
# Database: create, migrate, seed
./scripts/db_create.sh
./scripts/db_migrate.sh
./scripts/db_seed.sh
# Frontend deps
cd ../web
npm install
Per il piano database, documenta tre cose: come creare il DB, come vengono eseguite le migrazioni e come ottenere dati seed per un avvio realistico.
Infine, aggiungi un rapido health check così le persone possono confermare che l'app funziona prima di esplorare l'interfaccia. Un endpoint piccolo come GET /health che ritorna "ok" (e verifica la connettività al DB) è spesso sufficiente.
Quando esporti un progetto, il codice può essere tuo, ma i segreti devono restare privati. Assumi che il repo verrà condiviso con nuovi membri del team.
Inizia elencando cosa serve all'app per funzionare. Non azzardare: scorri il codice per trovare letture di configurazione (variabili d'ambiente, file di config) e verifica le integrazioni che hai abilitato.
Un inventario base dei segreti include solitamente credenziali del DB, chiavi di terze parti, impostazioni di auth (OAuth o JWT), credenziali di storage e segreti specifici dell'app come chiavi di cifratura o signing.
Decidi dove vive ogni segreto per ogni ambiente. Una regola semplice:
.env gestito dallo sviluppatore (non committato)Se hai esportato da una piattaforma come Koder.ai, considera che qualunque cosa mostrata in chat, log o pannelli di impostazioni potrebbe essere stata copiata in giro. Sposta i segreti fuori dal repository immediatamente.
Un approccio pratico è committare un template sicuro (come .env.example), tenere i valori reali fuori da Git (aggiungere .env a .gitignore) e iniettare i segreti di produzione al momento del deploy.
Se c'è la minima possibilità che segreti siano stati esposti durante l'export, ruotali: priorità a password DB, segreti client OAuth e chiavi di firma webhook.
Aggiungi alcune guardie per evitare il problema in futuro: un pre-commit che cerca pattern ovvi di segreti, uno scan dei segreti in CI, caricamento di config che fallisce rapidamente se mancano variabili obbligatorie e credenziali separate per ogni ambiente.
Un breve SECRETS.md aiuta nei passaggi di consegna. Mantienilo semplice: variabili richieste, dove sono conservate per ambiente e chi può ruotarle.
Una volta che prendi possesso, la CI diventa la tua rete di sicurezza. Mantieni la prima versione piccola. Ogni push dovrebbe dimostrare che il progetto si builda, che i controlli base passano e che i test (se ci sono) vengono eseguiti.
La CI dovrebbe rispondere a una domanda velocemente: "Questa modifica è sicura da mergiare?" Per la maggior parte dei repo ciò significa installare dipendenze, buildare, lintare ed eseguire test unitari.
Dividi i job per parte dell'app così i fail sono chiari:
Usa caching, ma non lasciare che il cache nasconda problemi. Quando la cache manca, la CI deve comunque funzionare, solo più lenta.
Preferisci un singolo comando per passo (make test, npm run test, ecc.) così lo stesso comando funziona in locale e in CI. Riduce confusione e mantiene i log più leggibili.
Esempio di struttura (adatta i nomi al tuo repo):
jobs:
web:
steps:
- run: npm ci
- run: npm run lint
- run: npm run build
api:
steps:
- run: go test ./...
- run: go build ./...
Dopo che le basi sono stabili, aggiungi un semplice flusso di release: tagga le release, costruisci artifact e salvali come artefatti CI. Anche se continui a distribuire da una piattaforma oggi, gli artifact ripetibili rendono più semplice cambiare host in futuro.
Esportare il codice è solo metà del lavoro. L'altra metà è assicurarsi che il progetto si comporti allo stesso modo fuori dalla piattaforma.
Gli export spesso dipendono da variabili d'ambiente, migrazioni, dati seed e passaggi di build che la piattaforma gestiva per te. Uno schermo vuoto o un errore DB al primo avvio è normale.
Fai prima una run di baseline prima di cambiare tutto: installa dipendenze, imposta le var d'ambiente, applica le migrazioni e avvia i servizi nell'ordine giusto. Correggi solo ciò che serve per ottenere il setup previsto.
L'incidente più comune è committare chiavi reali o password, spesso tramite un .env copiato o una config generata. Commetti solo template. Tieni i valori reali nell'ambiente locale o in uno store di segreti.
Aggiornare pacchetti o riorganizzare cartelle subito rende difficile capire se i problemi derivano dall'export o dalle tue modifiche.
Ottieni prima un run funzionante, poi migliora in piccoli commit separati.
"Funziona sulla mia macchina" spesso deriva da versioni non bloccate di strumenti (Node, Go, Flutter, persino package manager).
Blocca le versioni runtime in un posto chiaro (file o README), conserva i lockfile (package-lock, go.sum, pubspec.lock) e verifica l'installazione su una seconda macchina o in un container pulito.
I passaggi di consegna falliscono perché nessuno si ricorda quell'unico step strano necessario per avviare l'app. Scrivilo mentre è fresco: variabili env richieste, come eseguire migrazioni, dove vanno i log e come resettare lo stato locale.
Un team di tre persone costruisce un customer portal in Koder.ai: una web app React, un'API Go e un database PostgreSQL. Quando devono consegnarlo a un team esterno, vogliono che l'export sembri un repo normale che qualcuno può eseguire dal giorno uno.
Giorno 1: esportano, creano un nuovo repo Git e provano in locale. Il frontend parte, ma l'API fallisce perché mancano variabili d'ambiente. Non indovinano: leggono il codice, identificano le chiavi esatte usate e creano un .env.example con segnaposto. I valori reali restano in un password manager e nei .env locali.
Notano anche che porte e impostazioni CORS andavano bene sulla piattaforma ma hanno bisogno di default locali. Impostano valori prevedibili (per esempio API su 8080 e web su 3000) così nuove macchine si comportano allo stesso modo.
Giorno 2: aggiungono migrazioni e uno script di seed che crea un utente demo e alcune righe. Poi scrivono un README breve che copre prerequisiti, comandi per avviare e come verificarne il funzionamento (un health endpoint per l'API e un login di esempio per l'interfaccia).
Giorno 3: aggiungono una workflow CI base che esegue test, linting e build per entrambi i servizi a ogni pull request. Per lo staging, documentano un piano semplice: buildare container, impostare segreti nell'ambiente, eseguire migrazioni al deploy e mantenere un'opzione di rollback.
Un buon handoff di solito include un repo che si avvia in locale da un clone fresco, .env.example con note su dove stanno i segreti, migrazioni e dati seed, controlli CI che falliscono rapidamente e una breve nota di deploy per staging e rollback.
Prima di considerare l'export finito, dimostra che il progetto può vivere fuori dalla piattaforma. Se un altro sviluppatore può eseguirlo senza indovinare, sei in buona forma.
Usa questa checklist finale:
Dopo il controllo tecnico, rendi esplicita la proprietà. Decidi chi è responsabile degli aggiornamenti delle dipendenze, dei cambiamenti infrastrutturali (database, code, DNS) e delle release. Se nessuno si occupa di queste cose, il repo marcirà lentamente anche se oggi l'app funziona.
Pianifica una breve finestra di stabilizzazione prima di iniziare lavoro di feature importante. Due-cinque giorni utili sono spesso sufficienti per sistemare gli spigoli dell'export, rafforzare il README e rimuovere i problemi da “funziona sulla mia macchina”.
Se stai usando Koder.ai (koder.ai), export e funzionalità come snapshot e rollback rendono più semplice iterare mentre rafforzi il repo. Una volta stabile, mantieni Git come fonte di verità e considera i futuri export dalla piattaforma come checkpoint, non come la storia principale.
Definisci il prossimo milestone per il passaggio in termini chiari: "Qualsiasi sviluppatore può eseguirlo in 30 minuti." Poi verifica chiedendo a una persona nuova di seguire il README su una macchina pulita. Le sue domande diventano la tua lista finale di cose da fare.
Considera l'ownership come indipendenza: puoi buildare, eseguire, modificare e distribuire l'app da un repository normale senza aver bisogno del progetto originale sulla piattaforma, di impostazioni UI speciali o di step di build nascosti.
Un buon test è: un nuovo collega può clonare il repo e farlo partire usando solo il README?
Inizia con un controllo di completezza rapido:
package.json, go.mod, pubspec.yaml).package-lock.json, yarn.lock, pnpm-lock.yaml, go.sum).migrations/ o simili).docker-compose.yml).Se qualcosa necessario per eseguire è descritto solo in un'interfaccia o in chat, trasferiscilo nel repo.
Procedi in piccoli passi verificabili:
.env.example → .env.Non rifattorizzare subito: prima dimostra che funziona così com'è, poi migliora in commit separati.
Perché l'ambiente host spesso conteneva cose non rese esplicite:
Rendi la configurazione visibile: .env.example, script di migrazione e un README con i comandi esatti.
Un server che “parte” non è sufficiente: verifica il flusso reale dei dati:
Se non riesci a riprodurre modifiche ai dati localmente, la configurazione o le migrazioni sono incomplete.
Approccio standard:
.env.example con valori fittizi..env a .gitignore.Se trovi chiavi reali nel repo, assumile compromesse e ruotale subito. Prioritizza credenziali del database, segreti OAuth e chiavi di firma webhook.
Mantieni la CI iniziale semplice e coerente con i comandi locali:
go test ./... e builda il backend.Fai sì che la CI chiami gli stessi script che gli sviluppatori usano localmente (per esempio make test o ). Riduce i problemi “funziona in locale ma non in CI”.
Sì—se vuoi un passaggio di consegne prevedibile. Un buon default è:
README.md top-level con comandi copiabili..env.example che descrive variabili richieste e opzionali.Punta a far partire un nuovo sviluppatore in 15–30 minuti senza indovinare.
Struttura comune:
apps/ per frontend (web, mobile).services/ per API e worker.shared/ per tipi e utility condivise.infra/ per template di deploy ed esempi d'ambiente.I nomi esatti contano meno della chiarezza su cosa viene eseguito dove e come i pezzi si collegano.
Sequenza pratica:
Quando è stabile, tratta Git come sorgente di verità e considera eventuali export futuri dalla piattaforma come checkpoint, non come storia principale.
npm run build