Prompt della guida di stile di Claude Code per revisioni del codice coerenti

Perché le violazioni della guida di stile si diffondono così in fretta

Le violazioni della guida di stile raramente appaiono come un unico grande errore. Iniziano come piccole scelte “abbastanza corrette” che sembrano innocue in una pull request, poi si accumulano finché il codebase non sembra disomogeneo e più difficile da leggere.

La deriva dello stile spesso assomiglia a questo: un file usa userID, un altro usa userId, un terzo usa uid. Un handler restituisce { error: "..." }, un altro lancia un'eccezione, un altro registra e restituisce null. Ogni modifica è piccola, ma insieme creano un repo in cui i pattern smettono di essere prevedibili.

Un ciclo di sviluppo veloce e più contributori peggiora la situazione. Le persone copiano ciò che vedono, specialmente sotto pressione di tempo. Se l'ultimo codice nel repository ha usato una scorciatoia, quella scorciatoia diventa il modello per la prossima modifica. Dopo qualche settimana, lo “stile predefinito” non è la guida scritta: è qualunque cosa sia successa per ultima.

Per questo lo scopo deve essere avere convenzioni coerenti, non preferenze personali. La domanda non è “Mi piace questo nome?” ma “Questo corrisponde alle regole su cui abbiamo concordato così che la prossima persona lo segua senza pensarci?”

Individuare le violazioni presto significa fermare i pattern sbagliati prima che diventino materiale da copia-incolla. Concentrati sul codice nuovo e modificato, correggi la prima apparizione di una nuova incongruenza e blocca le merge che introducono nuova deriva. Quando segnali un problema, aggiungi un breve esempio preferito che le persone possano imitare la prossima volta.

Un esempio realistico: uno sviluppatore aggiunge un nuovo endpoint API e registra i body delle richieste “solo per il debug”. Se ciò entra nel repository, il prossimo endpoint lo copia, e presto dati sensibili finiscono nei log. Bloccarlo nella prima PR costa poco. Bloccarlo dopo che si è diffuso è doloroso e rischioso.

Trasforma la guida di stile in regole chiare e verificabili

Una guida di stile funziona nelle revisioni solo se si legge come una checklist, non come una serie di preferenze. Riscrivi ogni linea guida come una regola che può essere verificata su una diff.

Organizza le regole in quattro gruppi così sono difficili da tralasciare: naming, layering, gestione degli errori e logging. Per ogni gruppo scrivi due cose: cosa deve essere vero e cosa è proibito.

Decidi la severità di ogni regola in anticipo:

• Mandatory: il mancato rispetto blocca la modifica.
• Recommended: correggila a meno che non ci sia un motivo chiaro per non farlo.
• Optional: bello averlo, mai bloccante.

Imposta l'ambito così le revisioni non diventano refactor infiniti. Una regola semplice funziona bene: “il codice nuovo e modificato deve rispettare le regole; il codice esistente non toccato non viene riscritto a meno che non blocchi la correzione.” Se vuoi fare pulizie, fissale in un task separato con un tempo limitato.

Definisci anche l'output che vuoi da una revisione così è facile agire: un verdetto pass/fail, una lista di violazioni con file e riferimenti di riga, correzioni suggerite scritte come modifiche concrete e una breve nota sul rischio quando qualcosa potrebbe causare bug o fughe di dati.

Esempio: se una PR registra token utente grezzi, la revisione dovrebbe fallire sotto “logging: mai loggare segreti” e suggerire di registrare un request ID al loro posto.

Struttura del prompt che applica regole invece di opinioni

I prompt di stile falliscono quando suonano come preferenze. Un buon prompt di revisione si legge come un contratto: non negoziabili chiari, eccezioni chiaramente nominate e un output prevedibile.

Inizia con due blocchi corti: cosa deve essere vero e cosa può essere flessibile. Poi aggiungi una regola decisionale: “Se non chiaro, marca come Needs Clarification. Non indovinare.”

Richiedi evidenze. Quando lo strumento segnala una violazione, richiedi che citi l'esatto identificatore e il percorso del file, non una descrizione vaga. Questa singola restrizione elimina molta comunicazione inutile.

Mantieni l'ambito limitato: commenta solo sulle righe modificate e sui percorsi di codice direttamente impattati. Se permetti refactor non correlati, l'applicazione dello stile si trasforma in “riscrivi il file” e le persone smettono di fidarsi del feedback.

Ecco una struttura riutilizzabile:

Role: strict style guide reviewer.
Input: diff (or files changed) + style guide rules.
Non-negotiables: [list].
Allowed exceptions: [list].
Scope: ONLY comment on changed lines and directly impacted code paths. No unrelated refactors.
Evidence: Every finding MUST include (a) file path, (b) exact identifier(s), (c) short quote.
Output: structured compliance report with pass/fail per category + minimal fixes.

Richiedi che il report mantenga le stesse sezioni ogni volta, anche se alcune sono “No issues found”: Naming, Layering, Error handling, Logging.

Se segnala “service layer leaking DB details”, deve citare qualcosa come internal/orders/service/order_service.go e la chiamata esatta (per esempio db.QueryContext) così puoi correggere la perdita senza discutere sul significato.

Passo dopo passo: costruire un workflow di prompt per il controllo stile

Una guida di stile resta efficace quando il processo è ripetibile. L'obiettivo è far controllare le regole al modello, non discutere di gusti, e farlo sempre nello stesso modo.

Usa un workflow semplice in due passaggi:

1. Incolla i tuoi standard come una lista compatta numerata (10-25 righe). Mantieni ogni regola verificabile.
2. Aggiungi il contesto della modifica: la diff, i file toccati e una frase sull'intento.
3. Chiedi prima un report di violazioni. Richiedi file e riferimenti di riga, una breve ragione e il numero esatto della regola.
4. Solo dopo il report, chiedi la patch minima per raggiungere la conformità.
5. Riesegui lo stesso prompt sul codice aggiornato per confermare che non rimane nulla.

Esempio: una PR aggiunge un nuovo endpoint. Pass 1 segnala che l'handler parla direttamente con PostgreSQL (layering), usa naming misto per le struct di richiesta (naming) e registra email intere (logging). Pass 2 applica correzioni minime: sposta la chiamata DB in un servizio o repository, rinomina la struct e maschera l'email nei log. Nient'altro cambia.

Convenzioni di naming: prompt che individuano i dettagli piccoli

I problemi di naming sembrano minori, ma creano costi reali: le persone fraintendono l'intento, la ricerca diventa più difficile e i nomi quasi uguali si moltiplicano.

Dichiara le regole di naming che il revisore deve applicare su tutta la modifica: nomi file, tipi esportati, funzioni, variabili, costanti e test. Sii esplicito sullo stile di casing (camelCase, PascalCase, snake_case) e scegli una regola per le acronimi (per esempio APIClient vs ApiClient). Poi richiedi che venga applicata ovunque.

Standardizza anche il vocabolario condiviso: tipi di errore, campi dei log e chiavi di configurazione. Se i log usano request_id, non permettere reqId in un file e requestId in un altro.

Un'istruzione pratica per il revisore:

Check every new or renamed identifier. Enforce casing + acronym rules.
Flag vague names (data, info, handler), near-duplicates (userId vs userID), and names that contradict behavior.
Prefer domain language: business terms over generic tech words.

Chiedi un breve report: i tre nomi più fuorvianti, eventuali near-duplicate e quale mantenere, più qualsiasi nome in log/config/errore che non corrisponde allo standard.

Regole di layering: evita di mescolare responsabilità

Le regole di layering funzionano meglio in linguaggio semplice: gli handler gestiscono HTTP, i service contengono le regole di business, i repository parlano con il database.

Blocca la direzione delle dipendenze. Gli handler possono chiamare i service. I service possono chiamare i repository. I repository non dovrebbero chiamare service o handler. Gli handler non dovrebbero importare codice database, helper SQL o modelli ORM. Se usi pacchetti condivisi (config, time, IDs), mantienili privi di logica applicativa.

Assegna i compiti cross-cutting a una casa precisa. La validazione appartiene generalmente al boundary per la forma della richiesta e al service per le regole di business. L'autorizzazione spesso inizia nell'handler (identità, scope), ma il service deve far rispettare la decisione finale. Il mapping appartiene ai bordi dei layer: l'handler mappa HTTP a input di dominio, il repository mappa righe DB a tipi di dominio.

Incolla questo in un prompt per mantenere le revisioni concrete:

Check layering: handler -> service -> repository only.
Report any leaks:
- DB types/queries in handlers or services
- HTTP request/response types inside services or repositories
- repository returning DB models instead of domain objects
- auth/validation mixed into repository
For each leak, propose the smallest fix: move function, add interface, or rename package.

Rendi il report esplicito: indica il file, il layer a cui appartiene, l'import o la chiamata che viola la regola e il cambiamento minimo che impedisce al pattern di diffondersi.

Convenzioni per la gestione degli errori: coerenza sotto pressione

La maggior parte delle discussioni sullo stile diventano rumorose quando qualcosa si rompe in produzione. Una politica chiara per gli errori mantiene le correzioni calme perché tutti sanno cosa significa “bene”.

Scrivi la filosofia e applicala. Per esempio: “Avvolgi gli errori per aggiungere contesto; crea un nuovo errore solo quando cambia il significato o si effettua il mapping a un messaggio utente. Restituisci errori raw solo al boundary di sistema.” Quella frase impedisce a pattern casuali di diffondersi.

Separa il testo rivolto all'utente dai dettagli interni. I messaggi utente devono essere brevi e sicuri. Gli errori interni possono includere il nome dell'operazione e identificatori chiave, ma non segreti.

Nelle revisioni, verifica alcune falle ricorrenti: errori inghiottiti (loggati ma non restituiti), ritorni ambigui (valore nil con errore nil dopo un fallimento) e messaggi per l'utente che perdono stack trace, testo di query, token o PII. Se supporti retry o timeout, richiedi che siano espliciti.

Esempio: una chiamata di checkout scade. L'utente vede “Payment service is taking too long.” Internamente, avvolgi il timeout e includi op=checkout.charge e l'ID dell'ordine così è ricercabile e azionabile.

Convenzioni di logging: leggibile, ricercabile e sicuro

I log aiutano solo se tutti li scrivono nello stesso modo. Se ogni sviluppatore sceglie wording, level e campi, la ricerca diventa un gioco di indovinelli.

Rendi i livelli di log non negoziabili: debug per dettagli di sviluppo, info per milestone normali, warn per situazioni inaspettate ma gestite ed error quando l'azione visibile all'utente fallisce o richiede attenzione. Mantieni “fatal” o “panic” rari e legati a una chiara policy di crash.

I log strutturati contano più di frasi perfette. Richiedi nomi di chiavi stabili così dashboard e alert non si rompono. Decidi un piccolo set core (per esempio event, component, action, status, duration_ms) e mantienilo coerente.

Considera i dati sensibili come stop totale. Sii esplicito su cosa non deve mai essere loggato: password, token di autenticazione, numeri di carta completi, segreti e dati personali grezzi. Segnala cose che sembrano innocue ma non lo sono, come link di reset password, ID di sessione e body di richiesta completi.

Gli ID di correlazione rendono il debug possibile across i layer. Richiedi un request_id in ogni riga di log relativa a una richiesta. Se logghi user_id, definisci quando è permesso e come rappresentare utenti anonimi o mancanti.

Un blocco prompt riutilizzabile:

Review the changes for logging conventions:
- Check level usage (debug/info/warn/error). Flag any level that does not match impact.
- Verify structured fields: require stable keys and avoid free-form context in the message.
- Confirm correlation identifiers: request_id on all request-bound logs; user_id only when allowed.
- Flag any sensitive data risk (tokens, secrets, personal data, request/response bodies).
- Identify noisy logs (in loops, per-item logs, repeated success messages) and missing context.
Return: (1) violations with file/line, (2) suggested rewrite examples, (3) what to add or remove.

Prima di fare merge, fai una rapida “safety pass”: qualsiasi nuovo log relativo a una richiesta senza request_id, nuove chiavi che cambiano nomi esistenti (userId vs user_id), error log senza indicare cosa è fallito (operazione, risorsa, stato), log ad alto volume che scatteranno su ogni richiesta e qualsiasi possibilità che segreti o dati personali finiscano in campi o messaggi.

Come catturare le violazioni prima che si diffondano

Tratta la deriva di stile come un build break, non come un suggerimento. Aggiungi un gate rigoroso che viene eseguito prima del merge e ritorna un chiaro pass o fail. Se una regola mandatory è infranta (naming, confini di layer, sicurezza dei log, gestione errori), il gate fallisce e indica file e righe esatte.

Mantieni il gate breve. Un trucco pratico è richiedere una checklist SI/NO per ogni regola e rifiutare l'approvazione se c'è almeno un NO.

Una checklist per PR che cattura la maggior parte dei problemi:

• Naming: rispetta il pattern approvato per file, tipi e funzioni
• Layering: nessuna chiamata diretta che salti i layer (per esempio handler che chiamano il DB)
• Errori: restituiti con contesto, niente ignorato silenziosamente
• Logging: campi coerenti, niente segreti e livello adeguato
• Test/docs: aggiornati quando comportamento o API pubbliche cambiano

Quando lo strumento suggerisce correzioni, richiedi uno snippet conforme e piccolo per ogni regola toccata. Questo evita feedback vaghi come “rinomina per chiarezza.”

Trappole comuni quando si usano prompt per l'enforcement dello stile

Il modo più rapido per fallire con una guida di stile è lasciare spazio all'interpretazione. Se due revisori leggono la stessa regola e arrivano a conclusioni diverse, lo strumento finirà per far rispettare il gusto personale, non gli standard.

Naming è un esempio comune. “Usa nomi chiari” non è verificabile. Restringilo in qualcosa che puoi controllare: “le funzioni sono verbi (es. createInvoice), i booleani iniziano con is/has/can, i tipi esportati sono PascalCase.”

Un'altra trappola è chiedere tutto in una volta. Quando un prompt cerca di coprire naming, layering, errori, logging, test e performance, il feedback diventa superficiale. Se hai bisogno di profondità, dividi le revisioni in passaggi focalizzati, o mantieni il gate limitato alle regole mandatory.

I problemi che più spesso causano deriva nell'enforcement:

• Vague rules: sostituisci “pulito” e “coerente” con linguaggio misurabile.
• Mixing style fixes with redesign: non permettere a un prompt di proporre una nuova architettura.
• No quoted evidence: richiedi che ogni commento citi l'identificatore esatto o uno snippet.
• Silent exceptions: se permetti un'eccezione, richiedi una breve nota che spieghi perché e quando andrà rimossa.

Se tratti i prompt come test, ottieni enforcement prevedibile. Se li tratti come consigli, le violazioni si insinuano e si moltiplicano.

Checklist rapida da eseguire su ogni modifica

Esegui una passata veloce sulla diff (non sull'intero repo) e conferma:

• Naming: i nuovi identificatori seguono il pattern (case, prefissi, suffissi). Un concetto ha un unico nome in tutti i file.
• Layering: le dipendenze vanno solo nella direzione consentita. I layer inferiori non importano layer superiori.
• Errori: i fallimenti sono restituiti con contesto. Niente è silenziosamente ignorato.
• Logging: livello corretto, campi stabili e niente segreti o dati personali.
• Passata finale: il revisore dichiara esattamente: “no mandatory violations found”, oppure elenca le violazioni che devono essere corrette prima del merge.

Tieni un prompt template piccolo e incollalo in ogni revisione:

Review ONLY the changed code against our rules for naming, layering, errors, and logging.
List mandatory violations first (with file + line if available). Then list optional suggestions.
End with either: “no mandatory violations found” or “mandatory violations found”.

Esempio: una nuova funzione procUsr() in un handler che scrive direttamente su PostgreSQL dovrebbe fallare per naming e layering anche se la feature funziona. Catturarlo qui previene che l'errore si diffonda via copy-paste.

Esempio: una revisione realistica che corregge i problemi presto

Un collega aggiunge un nuovo endpoint: POST /v1/invoices/{id}/send. Tocca un handler, un service e lo storage.

Al primo passaggio vuoi un report, non una riscrittura:

Pass 1 (report only)
You are a strict style checker. Read the patch.
Rules: naming must match our guide, handlers call services only, services call storage only, no SQL in handlers,
errors must be wrapped with context, logs must be structured and not leak PII.
Output: a numbered list of violations with file:line, rule name, and one-sentence impact. Do not propose fixes.
If a rule might be intentionally broken, ask one clarification question.

Tipiche rilevazioni: SendInvoiceNow() vs SendInvoice mismatch di naming, l'handler che chiama db.QueryRow direttamente, restituzione di err grezzo senza contesto e log rumorosi come log.Printf("sending invoice %v", invoice) che stampano l'intero oggetto.

Il secondo passaggio chiede le minime modifiche sicure:

Pass 2 (minimal fix suggestions)
Using the violations list, propose the smallest code edits to comply.
Constraints: keep behavior the same, no refactors beyond what is needed, show suggested function names and where code should move.
For each fix, include 1-2 lines of example code.

Se rompere una regola è permesso, dirlo esplicitamente: “Le eccezioni sono permesse solo se aggiungi un breve commento che spieghi perché e aggiungi un task di follow-up per rimuovere l'eccezione.”

Dopo la correzione, l'handler diventa un adattatore sottile, il service possiede il workflow, lo storage la query, gli errori diventano fmt.Errorf("send invoice: %w", err) e i log diventano una linea pulita con campi sicuri (ID fattura, non la fattura completa).

Prossimi passi: rendilo routine senza rallentare

Scegli un prompt approvato dal team e trattalo come uno strumento condiviso. Inizia con ciò che ti crea più problemi nelle revisioni (deriva di naming, leak di layer, errori incoerenti, log non sicuri). Aggiorna il prompt solo quando vedi una violazione reale in codice reale.

Mantieni un piccolo blocco di regole in cima al prompt e incollalo in ogni revisione senza modifiche. Se tutti editano le regole ogni volta, non hai uno standard. Hai un dibattito.

Una cadenza semplice aiuta: una persona raccoglie i principali errori di stile della settimana e aggiunge esattamente una regola più chiara o un esempio migliore.

Se lavori in un flusso build-driven in chat come Koder.ai (koder.ai), vale la pena eseguire gli stessi gate di controllo durante le modifiche, non solo alla fine. Funzionalità come planning, snapshot e rollback possono aiutare a mantenere le correzioni di stile piccole e reversibili prima di esportare il codice sorgente.