Concetti pratici per programmatori e vibe coder: naming, segreti, env, gitignore, commit e dipendenze spiegati con prompt di controllo.
best practice 01
Naming convention
Rischio: Nomi vaghi come data, stuff, thing o final2 rendono il progetto difficile da leggere e da far modificare a un agente.
Regola: Usa nomi che dicano cosa rappresenta una cosa e perché esiste: userProfileForm, submitPayment, buildSearchQuery.
Un errore concreto: handleData() può caricare, salvare o cancellare: il nome non lo dice.
Il controllo utile: Se la funzione salva il profilo, saveUserProfile() rende più chiaro l’effetto. Prima della rinomina cerca chiamanti, export e test.
Review naming in this code.
Look for:
- vague names
- misleading names
- inconsistent component/file names
- names that hide side effects
Do not rename yet. First propose a small rename plan with risks.
best practice 02
API key mai nel frontend
Rischio: Il frontend viene scaricato dal browser. Se metti una chiave lì dentro, chiunque può leggerla e usarla.
Regola: Le chiavi stanno nel backend o nelle variabili ambiente del servizio che esegue il backend. Il browser chiama solo il tuo endpoint.
Un errore concreto: VITE_API_KEY o PUBLIC_API_KEY diventano pubbliche se vengono incluse nel bundle del browser.
Il controllo utile: Il browser chiama un endpoint del tuo backend. La credenziale resta nel servizio che esegue la chiamata al provider.
Check whether this project exposes secrets.
Look for:
- API keys
- tokens
- connection strings
- private endpoints
- credentials in frontend code
- credentials in logs or config files
Do not modify code yet. Report where each risk is and how to move it safely.
best practice 03
.env e local settings fuori da git
Rischio: File locali come .env, local.settings.json o config private possono contenere segreti, URL interni e credenziali.
Regola: Versiona solo esempi senza segreti, tipo .env.example. I valori reali restano locali o nel provider cloud.
Un errore concreto: Rinominare .env in .env.example senza sostituire i valori pubblica gli stessi segreti con un nome diverso.
Il controllo utile: Usa placeholder evidenti, descrivi quali variabili servono e controlla il diff prima di aggiungere il file a Git.
Inspect git-tracked config files.
Find files that should probably stay local:
- .env
- local.settings.json
- secrets files
- service account files
- private certificates
Suggest a safe .gitignore update and an example file without secrets.
best practice 04
Perché .gitignore conta
Rischio: Senza .gitignore rischi di committare node_modules, build, cache, file temporanei, database locali e segreti.
Regola: Un buon .gitignore tiene il repo pulito e riduce incidenti. Va controllato quando aggiungi framework o tool nuovi.
Un errore concreto: Aggiungere .env a .gitignore non rimuove un file che Git sta già tracciando.
Il controllo utile: Controlla git ls-files per i file versionati e git check-ignore -v .env per la regola. Se è stata pubblicata una chiave, revocala: ignorare il file non cancella la cronologia.
Review the .gitignore for this project.
Check whether it excludes:
- dependencies
- build output
- local env files
- cache folders
- local databases
- OS/editor files
Propose only entries relevant to this repo.
best practice 05
Commit piccoli
Rischio: Un commit enorme rende difficile capire cosa ha rotto cosa, soprattutto quando lavora un agente.
Regola: Ogni commit dovrebbe raccontare una modifica coerente: una feature, un fix, una pulizia limitata.
Un errore concreto: Correzione del calcolo, aggiornamento dipendenze e restyling nello stesso commit rendono più difficile isolare una regressione.
Il controllo utile: Separa gli scopi quando sono indipendenti. Codice e test della stessa correzione restano insieme, così il commit può essere verificato.
Review local changes and suggest a commit split.
Group changes by purpose:
- feature
- bugfix
- styling
- docs/content
- cleanup
Do not stage or commit. Only propose groups and commit messages.
best practice 06
Dipendenze con criterio
Rischio: Installare pacchetti per ogni problema aumenta bundle, manutenzione e superficie di rischio.
Regola: Prima cerca se il progetto o il framework risolvono già il problema. Aggiungi librerie solo quando il valore è chiaro.
Un errore concreto: Una build può fallire prima di leggere il codice perché il runtime non soddisfa il requisito del framework.
Il controllo utile: Confronta node --version, engines in package.json e runtime della CI. Per aggiungere un pacchetto, verifica anche compatibilità, manutenzione e costo rispetto a una funzione locale.
Before adding a dependency, evaluate whether it is necessary.
Compare:
- existing project utilities
- framework built-ins
- small local implementation
- new dependency
Return the tradeoff and recommend the simplest maintainable option.