Esporta pulitamente il codice sorgente da una piattaforma vibe-coding

Cosa significa prendere possesso dopo l'export

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:

• Configurazioni che esistono solo in un'interfaccia della piattaforma
• Passaggi di build che avvengono “da qualche altra parte”
• Dipendenze assunte ma non documentate

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:

• Puoi eseguire l'app esportata in locale con passi prevedibili.
• Puoi distribuirla dal tuo repo usando CI, non clic manuali.
• I segreti sono gestiti in modo sicuro (niente chiavi in Git, niente indovinelli).
• Il repo è pronto per il passaggio di consegne, così una nuova persona può onboardare velocemente e fidarsi di quello che vede.

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.

Cosa aspettarsi in un progetto esportato

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.

La forma del progetto: cartelle, punti di ingresso e cosa avvia cosa

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:

• Web: un package.json e una cartella src/ (spesso con main.tsx o simili)
• Backend: go.mod e una cartella cmd/ o un main.go
• Mobile: pubspec.yaml di Flutter e lib/main.dart
• Un README top-level o un Makefile che descrive come avviare tutto
• Un docker-compose.yml se l'export è pensato per girare come insieme di servizi

Dipendenze, configurazione e pezzi di database

Le 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.

Passo dopo passo: esportare, commitare e avviare in locale

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.

Un primo commit pulito (così la storia parte leggibile)

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

Conferma che il database funzioni davvero (non solo “server avviato”)

Un server può avviarsi mentre l'app è ancora rotta. Conferma che possa leggere e scrivere dati.

Scegli controlli rapidi che si adattino al prodotto:

• Apri una pagina che dipende chiaramente dai dati (una lista, profilo, dashboard).
• Crea un record (signup, crea elemento, aggiungi nota), aggiorna e verifica che sia persistito.
• Esegui un aggiornamento e una cancellazione se l'interfaccia lo supporta.
• Controlla i log per errori di migrazione o "relation does not exist".

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.

Trasforma l'export in un repo pronto per il passaggio di consegne

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 job
• shared/ per tipi e utility condivise
• infra/ per template di deploy, script ed esempi d'ambiente
• docs/ per note architetturali e runbook

Poi aggiungi un piccolo set di file che riducono l'indovinare:

• README.md con prerequisiti e comandi esatti
• CONTRIBUTING.md con poche regole (branch, PR, niente segreti)
• .gitignore per tenere fuori da Git file di ambiente locali e output di build

Mantieni 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.

Setup di sviluppo locale che i nuovi possono seguire

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.

Un env minimo e sicuro

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.

Un comando per bootstrap

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.

Segreti e configurazione senza perdite

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:

• Locale: .env gestito dallo sviluppatore (non committato)
• CI: store dei segreti del provider CI
• Produzione: un secret manager dedicato o variabili d'ambiente dell'hosting

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.

Configura la CI per mantenere sano il repo

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:

• Web: installa, lint/typecheck, build, esegui test
• Backend: build, esegui test unitari, lint/format checks
• Mobile opzionale (Flutter): analizza, testa, builda
• Controllo DB opzionale: applica migrazioni in un ambiente usa-e-getta

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.

Errori comuni e come evitarli

Esportare il codice è solo metà del lavoro. L'altra metà è assicurarsi che il progetto si comporti allo stesso modo fuori dalla piattaforma.

Errore 1: Aspettarsi che funzioni senza setup

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.

Errore 2: Perdere segreti in Git

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.

Errore 3: Cambiare dipendenze troppo presto

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.

Errore 4: Non bloccare le versioni

"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.

Errore 5: Saltare la documentazione e poi pagare il conto

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 esempio realistico: da progetto su piattaforma a repo indipendente

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.

Controlli rapidi e prossimi passi

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:

• Il repo è leggibile: README chiaro, nomi di cartelle sensati e un modo per avviare l'app.
• Un run locale funziona da zero: clone, installa, configura, avvia e vedi l'app senza modifiche manuali.
• I test si eseguono (anche un test smoke o un health check è meglio di niente).
• La CI gira a ogni push: lint, test e build che falliscono rapidamente.
• I segreti sono separati: niente chiavi nel repo e un file config di esempio mostra le variabili richieste.
• I documenti coprono le basi: come eseguire, come distribuire e dove cambiare le impostazioni comuni.

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.