Setup minimo del proprio ambiente di vibe coding

L’ambiente di lavoro non è un dettaglio: è dove l’AI agisce. Senza struttura minima — tracciamento, separazione segreti, convenzioni base — anche un modello eccellente produce caos. Con la struttura, anche un modello medio produce risultati riproducibili.

Perché questa lezione conta

Chi lavora con AI senza setup minimo accumula problemi prevedibili: file persi (modifiche non committate, sovrascritte), segreti finiti in repo pubbliche, cronologia confusa fra mano e AI, conversazioni rilanciate da zero perché manca un AGENTS.md aggiornato, ambienti che funzionano “da me” e non altrove. Una mezza giornata di setup ne salva decine in seguito.

Obiettivo operativo

Alla fine devi avere:

1. ambiente locale completo (editor, terminale, git, runtime, gestore pacchetti);
2. progetto demo con struttura iniziale, file di regole, primo commit;
3. workflow per separare appunti, prompt, codice, segreti.

Nucleo della lezione

1. Componenti base dell’ambiente

Cinque blocchi minimi:

• Editor: VS Code, Cursor, Zed, Windsurf, Neovim. Scelta dipende da preferenza e da quanto integrato vuoi l’AI. Cursor/Windsurf nativi sull’AI; VS Code + Copilot/Continue per setup modulare.
• Terminale: integrato nell’editor o separato. zsh/bash/fish su macOS/Linux, PowerShell o WSL su Windows. Conoscere comandi base (cd, ls, grep, find, git) è prerequisito.
• Git: installato e configurato (user.name, user.email). Account su GitHub/GitLab/Bitbucket per backup remoto. SSH key configurata.
• Runtime/i: linguaggi che usi (Node.js, Python, Go, Rust). Gestiti con version manager (nvm/fnm/Volta per Node, pyenv/uv per Python, rustup per Rust). Evita installazioni globali.
• Gestore pacchetti: npm/pnpm/bun/yarn per Node; pip+uv/poetry per Python; etc. Uno per linguaggio, niente mix.

Aggiunge se serve: Docker per ambienti riproducibili, browser con DevTools, client database (TablePlus, DBeaver, psql).

2. Struttura di progetto iniziale

Cosa contiene una repo pulita prima ancora di scrivere codice di prodotto:

• README.md: cosa fa il progetto, come si avvia, comandi principali.
• AGENTS.md (o CLAUDE.md, .cursor/rules/, .windsurfrules): istruzioni per l’AI. Comandi build/test, convenzioni, vincoli, file vietati.
• .gitignore: cosa NON committare. Almeno node_modules/, .env*, dist/, .DS_Store, file IDE specifici (.idea/, .vscode/settings.json se personali).
• .env.example: template di variabili d’ambiente, senza valori reali. Versionato.
• .env: valori reali. NON versionato (gitignored).
• package.json / pyproject.toml / Cargo.toml: manifest dipendenze + script.
• src/ o equivalente: codice di prodotto.
• tests/ o convenzione affine: test.

Primo commit prima di chiedere all’AI qualunque cosa: git init, file sopra, git add ., git commit -m "chore: initial project structure". Da lì in poi ogni modifica AI è un diff confrontabile.

3. Separazione segreti e materiali sensibili

Cinque livelli, da non mescolare mai:

• Variabili pubbliche: NEXT_PUBLIC_*, VITE_*. Compaiono nel bundle client. Niente di sensibile qui.
• Configurazione server-side: URL servizi, feature flag. In .env, non in repo.
• Segreti di sviluppo: API key di test, credenziali di database locale. In .env.local o .env.development.
• Segreti di produzione: chiavi reali. MAI in repo. Solo in pannello hosting (Vercel, Netlify, Railway, Fly) o vault (1Password, Doppler, AWS Secrets Manager).
• Credenziali personali: SSH key, token GitHub. Nelle config dell’OS, mai in progetto.

Regola d’oro: se un segreto entra in repo, anche per un commit, considera quel segreto compromesso. Ruota subito.

Strumenti utili: git-secrets o gitleaks per pre-commit hook che blocca push di pattern sensibili. Vale la mezz’ora di setup.

Procedura pratica

Setup completo di un nuovo progetto in 30 minuti:

1. Crea cartella, cd dentro, git init.
2. Configura .gitignore (parti da template del linguaggio, github.com/github/gitignore).
3. Scrivi README.md scheletro: descrizione, prerequisiti, install, run.
4. Scrivi AGENTS.md (o CLAUDE.md): comandi, convenzioni, vincoli, file vietati.
5. Init manifest: npm init, uv init, equivalente. Installa dipendenze base.
6. Crea .env.example con chiavi vuote. Crea .env locale, popolalo, verifica gitignore.
7. Primo commit: tutto sopra.
8. Connetti remote: gh repo create o equivalente, git push.
9. Verifica push non contenga segreti (controlla file pushati).

Poi e solo poi inizia a chiedere all’AI di scrivere codice di prodotto.

Laboratorio guidato

Crea repo demo “vibe-coding-setup”:

• struttura completa secondo sequenza sopra;
• linguaggio a tua scelta (es. Node + TypeScript, Python, Go);
• AGENTS.md con almeno 10 regole reali per quel progetto;
• pre-commit hook per gitleaks (opzionale ma consigliato);
• primo commit;
• push su GitHub.

Verifica:

• node_modules/ (o equivalente) NON è nel commit;
• .env NON è nel commit;
• .env.example SÌ nel commit;
• comando di “run” funziona dopo clone + install su una macchina pulita (anche solo simulato in cartella nuova).

Output atteso

Un template di repo personale (puoi salvarlo come template GitHub) da clonare per ogni nuovo progetto. Contiene struttura, .gitignore, README scheletro, AGENTS.md base, .env.example. Ogni nuovo progetto parte da questo, non da zero.

Studio passo passo

Studia questa lezione in tre passaggi, senza correre subito al prompt o al codice.

1. Prima lettura: chiarisci l’obiettivo: preparare un ambiente semplice, tracciabile e sicuro per lavorare con AI senza perdere file, segreti o cronologia. Se non riesci a riscriverlo in una frase tua, rileggi il nucleo della lezione.
2. Seconda lettura: trasforma i contenuti in domande operative:

• Cartelle di progetto, editor, terminale, Git, gestore pacchetti e browser come base minima.
• Separazione tra appunti, prompt, codice, variabili d’ambiente e materiali sensibili.
• Primi file di progetto: README, regole per l’agente, checklist test, note sulle decisioni.

3. Applicazione: svolgi il laboratorio: creare una repo demo con struttura iniziale, file di regole, primo commit e comando di verifica. L’output da ottenere è: un ambiente pronto per i moduli successivi, con convenzioni esplicite e una piccola rete di sicurezza.

Prima di passare alla lezione successiva, controlla di avere un artefatto concreto: una tabella, un prompt, una checklist, un mini report, un diff commentato o una decisione scritta. Nel vibe coding la comprensione resta astratta finché non produce una traccia verificabile.

Checklist di verifica

• ho un editor configurato con AI di mia scelta;
• ho git con SSH key, account remoto, configurazione user;
• ho un version manager per il/i linguaggio/i che uso;
• ho una repo template personale per nuovi progetti;
• conosco la differenza fra .env, .env.local, .env.example;
• ho un sistema per non mai committare segreti (gitignore + idealmente pre-commit hook).

Errori comuni

Installare runtime globalmente. sudo apt install nodejs ti dà la versione di sistema. Domani usi un progetto che richiede altra versione e sei bloccato. Version manager risolve.

Mettere .env in repo “tanto è solo locale”. Quel “tanto” diventa public push. Sempre .env gitignored, sempre .env.example versionato.

Niente AGENTS.md per progetti piccoli. L’AI inventa convenzioni a ogni sessione. Anche 15 righe di regole salvano tempo.

Mescolare gestori pacchetti. Un progetto con package-lock.json + yarn.lock + pnpm-lock.yaml è un progetto rotto. Scegli uno.

Non avere remote. Repo locale + crash disco = lavoro perso. Push regolare anche su progetto personale.

Usare lo stesso .env su sviluppo e produzione. Un errore di test che cancella dati di produzione: già successo a tanti.

Prompt di lavoro

Sto impostando un nuovo progetto. Dammi un piano per setup minimo riproducibile.

Stack: [linguaggio + framework]
Tipo progetto: [web app / CLI / libreria / API / altro]
Sistema operativo: [macOS / Linux / Windows]
Esperienza con git: [base / intermedia / avanzata]

Voglio in output:
1. Lista comandi shell esatti per il setup (copiabili).
2. Contenuto base di .gitignore specifico per lo stack.
3. Scheletro AGENTS.md con sezioni: comandi, convenzioni, file vietati, dipendenze permesse, criteri di "fatto".
4. Esempio .env.example pertinente allo stack.
5. Nota su pre-commit hook anti-segreti (opzionale).

Niente prosa esplicativa lunga: solo comandi e file. Spiega solo i punti non ovvi.

Esercizio finale

Cancella idealmente la cartella di un progetto secondario, lascia solo la repo remota. Ricostruisci l’ambiente da zero seguendo solo README.md e AGENTS.md. Quante cose mancano nelle istruzioni? Quante sono nella tua testa e non documentate? Ogni “ah, manca…” è una riga da aggiungere al README. Un setup è davvero pronto quando un’altra persona (o tu fra 6 mesi) può riavviare il progetto leggendo solo i file in repo.