Prompts du guide de style Claude Code pour des revues de code cohérentes

Pourquoi les violations du guide de style se propagent si vite

Les violations du guide de style n'apparaissent que rarement comme une grosse erreur isolée. Elles commencent par de petites décisions « suffisantes » qui semblent anodines dans une PR, puis s'accumulent jusqu'à ce que la base de code paraisse inégale et plus difficile à lire.

La dérive de style ressemble souvent à ça : un fichier utilise userID, un autre userId, un troisième uid. Un handler retourne { error: "..." }, un autre lance une exception, un troisième logge puis retourne null. Chaque changement est petit, mais ensemble ils créent un dépôt où les motifs ne sont plus prévisibles.

L'itération rapide et la multiplicité des contributeurs aggravent le phénomène. Les gens copient ce qu'ils voient, surtout sous pression temporelle. Si le code le plus récent dans le dépôt a utilisé un raccourci, ce raccourci devient le modèle pour la prochaine modification. Après quelques semaines, le « style par défaut » n'est plus votre guide écrit, c'est ce qui s'est passé en dernier.

C'est pourquoi l'objectif doit être des conventions cohérentes, pas des préférences personnelles. La question n'est pas « Est-ce que j'aime ce nom ? » mais « Cela correspond-il aux règles sur lesquelles nous nous sommes mis d'accord pour que la personne suivante puisse s'y conformer sans réfléchir ? »

Détecter les violations tôt revient à arrêter les mauvais motifs avant qu'ils n'alimentent le copier-coller. Concentrez-vous sur le code nouveau et modifié, corrigez la première apparition d'une nouvelle incohérence et bloquez les merges qui introduisent une nouvelle dérive. Quand vous signalez un problème, ajoutez un court exemple préféré que les gens pourront reproduire la prochaine fois.

Un exemple réaliste : un développeur ajoute un nouvel endpoint API et logge les bodies de requêtes « juste pour le debug ». Si ça est mergé, le prochain endpoint va copier, puis bientôt des données sensibles apparaissent dans les logs. Le détecter dès la première PR coûte peu. Le corriger après propagation est douloureux et risqué.

Transformer votre guide de style en règles claires et testables

Un guide de style ne fonctionne dans les revues que s'il se lit comme une checklist, pas comme un ensemble de préférences. Reformulez chaque ligne directrice en règle vérifiable sur une diff.

Organisez les règles en quatre catégories pour qu'elles soient difficiles à manquer : nommage, layering, gestion des erreurs et logging. Pour chaque catégorie, écrivez deux choses : ce qui doit être vrai et ce qui est interdit.

Décidez la force de chaque règle à l'avance :

• Obligatoire : défaut bloque la modification.
• Recommandée : corriger sauf raison claire pour ne pas le faire.
• Optionnelle : bon à avoir, jamais bloquante.

Définissez le périmètre pour que les revues ne tournent pas en refactorings sans fin. Une règle simple fonctionne bien : « le code nouveau et modifié doit être conforme ; le code existant non touché n'est pas réécrit sauf si ça bloque la correction ». Si vous voulez du nettoyage, limitez-le dans le temps comme tâche séparée.

Définissez aussi le résultat attendu d'une revue pour qu'il soit facile d'agir : un verdict pass/fail, une liste de violations avec fichiers et lignes, des corrections suggérées écrites comme modifications concrètes, et une brève note de risque quand quelque chose peut causer des bugs ou des fuites.

Exemple : si une PR logge des tokens utilisateur en clair, la revue doit échouer sous « logging : ne jamais logger des secrets » et proposer de logger un request ID à la place.

Structure de prompt qui impose des règles plutôt que des opinions

Les prompts de style échouent quand ils ressemblent à des préférences. Un bon prompt de revue se lit comme un contrat : non-négociables clairs, exceptions nommées, et une sortie prévisible.

Commencez par deux blocs courts : ce qui doit être vrai et ce qui peut être assoupli. Ajoutez ensuite une règle de décision : « Si incertain, marquer comme Needs Clarification. Ne pas deviner. »

Exigez des preuves. Quand l'outil signale une violation, obligez-le à citer l'identifiant exact et le chemin du fichier, pas une description vague. Cette contrainte réduit beaucoup d'aller-retour.

Gardez le périmètre serré : commentez uniquement les lignes modifiées et les chemins impactés directement. Si vous autorisez des refactors sans rapport, l'application du style devient « réécrire le fichier » et les gens cessent de faire confiance au feedback.

Voici une structure réutilisable :

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.

Exigez que le rapport conserve les mêmes sections à chaque fois, même si certaines sont « No issues found » : Naming, Layering, Error handling, Logging.

S'il indique « service layer leaking DB details », il doit citer quelque chose comme internal/orders/service/order_service.go et l'appel exact (par exemple db.QueryContext) pour que vous puissiez corriger la fuite sans débattre de son sens.

Étapes : construire un workflow de prompt pour les vérifications de style

Un guide de style s'installe quand le processus est répétable. L'objectif est de faire vérifier les règles par le modèle, pas de discuter du goût, et de le faire toujours de la même manière.

Utilisez un workflow simple en deux passes :

1. Collez vos standards comme une liste compacte et numérotée (10–25 lignes). Gardez chaque règle testable.
2. Ajoutez le contexte du changement : la diff, les fichiers touchés, et une phrase sur l'intention.
3. Demandez d'abord un rapport de violations. Exigez fichiers et lignes, une courte raison, et le numéro exact de la règle.
4. Ce n'est qu'après le rapport que vous demandez le patch le plus petit pour atteindre la conformité.
5. Relancez le même prompt exact sur le code mis à jour pour confirmer qu'il ne reste rien.

Exemple : une PR ajoute un nouvel endpoint. Passe 1 signale que le handler interroge PostgreSQL directement (layering), utilise un nommage mixte pour les structs de requête (naming), et logge des emails complets (logging). Passe 2 propose des corrections minimales : déplacer l'appel DB dans un service ou repository, renommer la struct, et masquer l'email dans les logs. Rien d'autre ne change.

Conventions de nommage : prompts pour attraper les petits détails

Les problèmes de nommage semblent mineurs, mais ils créent un vrai coût : on lit mal l'intention, la recherche devient plus difficile, et des noms « presque identiques » se multiplient.

Énoncez les règles de nommage que le relecteur doit faire respecter sur tout le changement : noms de fichiers, types exportés, fonctions, variables, constantes, et tests. Soyez explicite sur le casing (camelCase, PascalCase, snake_case) et choisissez une règle pour les acronymes (par exemple APIClient vs ApiClient). Exigez son application partout.

Standardisez aussi le vocabulaire partagé : types d'erreur, champs de logs et clés de config. Si les logs utilisent request_id, n'autorisez pas reqId dans un fichier et requestId dans un autre.

Une instruction pratique pour le relecteur :

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.

Demandez un rapport court : les trois noms les plus déroutants, les quasi-doublons et lequel garder, plus les noms de logs/config/erreurs qui ne respectent pas le standard.

Règles de layering : éviter le mélange des responsabilités

Les règles de layering sont plus efficaces en langage clair : les handlers s'occupent du HTTP, les services contiennent la logique métier, les repositories parlent à la base de données.

Verrouillez la direction des dépendances. Les handlers peuvent appeler les services. Les services peuvent appeler les repositories. Les repositories ne doivent pas appeler services ou handlers. Les handlers ne doivent pas importer de code base de données, d'aides SQL ou de modèles ORM. Si vous utilisez des paquets partagés (config, time, IDs), gardez-les sans logique applicative.

Attribuez les travaux transverses à un emplacement : la validation appartient en général à la frontière pour la forme de la requête et au service pour les règles métier. L'autorisation commence souvent dans le handler (identité, scopes), mais le service doit appliquer la décision finale. Le mapping se fait aux bords des couches : le handler mappe HTTP vers l'entrée domaine, le repository mappe les lignes DB en types domaine.

Collez ce bloc dans un prompt pour garder les revues concrètes :

Check layering: handler -\u003e service -\u003e 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.

Rendez le rapport explicite : nommez le fichier, la couche à laquelle il appartient, l'import ou l'appel qui viole la règle, et le changement minimal qui empêche la propagation du motif.

Conventions de gestion des erreurs : cohérence sous pression

Les débats sur le style montent souvent d'un cran quand quelque chose casse en production. Une politique claire de gestion des erreurs calme les correctifs car tout le monde sait à quoi ressemble le « bon » comportement.

Écrivez la philosophie et faites-la respecter. Par exemple : « Enrichir les erreurs pour ajouter du contexte ; créer une nouvelle erreur seulement lorsqu'on change le sens ou qu'il faut la mapper à un message utilisateur. Retourner les erreurs brutes seulement à la frontière système. » Cette phrase suffit à empêcher la propagation de motifs aléatoires.

Séparez le texte destiné à l'utilisateur du détail interne. Les messages utilisateurs doivent être courts et sûrs. Les erreurs internes peuvent inclure le nom de l'opération et des identifiants clés, mais pas de secrets.

En revue, vérifiez quelques échecs récurrents : erreurs étouffées (loggées mais pas retournées), retours ambigus (valeur nil avec erreur nil après un échec), et messages utilisateurs qui fuient des traces de pile, du texte de requête, des tokens ou des PII. Si vous supportez des retries ou des timeouts, exigez qu'ils soient explicites.

Exemple : un appel de checkout timeoute. L'utilisateur voit « Le service de paiement prend trop de temps. ». En interne, enrichissez le timeout et incluez op=checkout.charge et l'ID de commande pour que ce soit searchable et exploitable.

Conventions de logging : lisible, searchable et sûr

Les logs n'aident que si tout le monde les écrit de la même façon. Si chaque développeur choisit son libellé, son niveau et ses champs, la recherche devient du devinage.

Rendez les niveaux non négociables : debug pour le détail dev, info pour les jalons normaux, warn pour les situations inattendues mais gérées, error quand l'action côté utilisateur échoue ou demande une attention. Gardez « fatal » ou « panic » rares et liés à une politique de crash claire.

Les logs structurés comptent plus que des phrases parfaites. Exigez des noms de clés stables pour que tableaux de bord et alertes ne cassent pas. Décidez d'un petit jeu de champs centraux (par exemple event, component, action, status, duration_ms) et gardez-les constants.

Traitez les données sensibles comme un stop catégorique. Soyez explicite sur ce qu'il ne faut jamais logger : mots de passe, tokens d'auth, numéros de carte complets, secrets et données personnelles brutes. Signalez aussi ce qui paraît anodin mais ne l'est pas, comme les liens de reset de mot de passe, les session IDs, et les bodies complets de requêtes.

Les IDs de corrélation rendent le débogage possible à travers les couches. Exigez un request_id dans chaque ligne de log liée à une requête. Si vous loggez user_id, définissez quand c'est autorisé et comment représenter les utilisateurs anonymes ou manquants.

Un bloc de prompt réutilisable :

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.

Avant le merge, faites une « passe de sécurité » rapide : tout nouveau log lié à une requête doit contenir request_id, toute nouvelle clé qui change des noms existants (userId vs user_id) doit être signalée, tout log d'erreur doit préciser ce qui a échoué (opération, ressource, statut), signalez les logs à fort volume qui s'exécuteront à chaque requête, et toute possibilité que des secrets ou des PII apparaissent dans des champs ou messages.

Comment détecter les violations avant qu'elles ne se propagent

Traitez la dérive de style comme une rupture de build, pas comme une suggestion. Ajoutez une porte stricte qui s'exécute avant le merge et renvoie un pass ou fail clair. Si une règle obligatoire est violée (nommage, frontières de couche, sécurité des logs, gestion des erreurs), elle échoue et pointe les fichiers et lignes exacts.

Gardez la porte courte. Un truc pratique : exigez une checklist OUI/NON par règle, et refusez l'approbation si un item est NON.

Une checklist adaptée à la taille d'une PR qui attrape la plupart des problèmes :

• Naming : correspond au pattern approuvé pour fichiers, types et fonctions
• Layering : pas d'appels directs qui sautent des couches (par ex. handlers appelant la DB)
• Erreurs : retournées de façon cohérente avec du contexte, rien d'ignoré silencieusement
• Logging : champs cohérents, pas de secrets, niveau adapté à l'impact
• Tests/docs : mis à jour quand le comportement ou les API publiques changent

Quand l'outil propose des corrections, exigez un petit extrait conforme pour chaque règle touchée. Cela évite des feedbacks vagues comme « renommez pour plus de clarté ».

Pièges courants lors de l'utilisation de prompts pour l'application du style

La façon la plus rapide de faire échouer un guide de style est de laisser la place à l'interprétation. Si deux relecteurs lisent la même règle et arrivent à des conclusions différentes, l'outil appliquera le goût, pas les standards.

Le nommage est un exemple courant. « Utiliser des noms clairs » n'est pas testable. Serrez la règle en quelque chose que l'on peut vérifier : « les fonctions sont des verbes (ex. createInvoice), les booléens commencent par is/has/can, les types exportés sont en PascalCase. »

Autre piège : demander tout en une seule passe. Quand un prompt essaie de couvrir nommage, layering, erreurs, logs, tests et performance, le feedback devient superficiel. Séparez les revues en passes ciblées quand vous avez besoin de profondeur, ou limitez le prompt de porte aux règles obligatoires.

Les problèmes qui causent le plus souvent la dérive de l'application :

• Règles vagues : remplacez « propre » et « cohérent » par un langage mesurable.
• Mélanger corrections de style et refonte : ne laissez pas un prompt proposer une nouvelle architecture.
• Absence de preuves citées : exigez que chaque commentaire cite l'identifiant exact ou l'extrait.
• Exceptions silencieuses : si vous acceptez une exception, exigez une courte note expliquant pourquoi et quand la supprimer.

Si vous traitez les prompts comme des tests, vous obtenez une application prévisible. Si vous les traitez comme des conseils, les violations s'infiltrent et se multiplient.

Checklist rapide à exécuter sur chaque changement

Faites une passe rapide sur la diff (pas le dépôt entier) et confirmez :

• Naming : les nouveaux identifiants suivent votre pattern (casse, préfixes, suffixes). Un concept a un seul nom dans tous les fichiers.
• Layering : les dépendances vont uniquement dans la direction autorisée. Les couches inférieures n'importent jamais les couches supérieures.
• Erreurs : les échecs sont retournés avec du contexte. Rien n'est ignoré silencieusement.
• Logging : niveau correct, champs stables, pas de secrets ni de données personnelles.
• Passe finale : le relecteur déclare exactement : « no mandatory violations found », ou liste les violations qui doivent être corrigées avant le merge.

Gardez un petit template de prompt et collez-le avec chaque changement :

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

Exemple : une nouvelle fonction procUsr() dans un handler qui écrit directement dans PostgreSQL devrait échouer en naming et en layering même si la fonctionnalité marche. La détecter ici empêche la propagation par copier-coller.

Exemple : une revue réaliste qui corrige les problèmes tôt

Un coéquipier ajoute un nouvel endpoint : POST /v1/invoices/{id}/send. Il touche un handler, un service et le stockage.

À la première passe, vous voulez un rapport, pas une réécriture :

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.

Constats typiques : SendInvoiceNow() vs SendInvoice incohérence de nommage, le handler appelle db.QueryRow directement, retourne err brut sans contexte, et des logs bruyants comme log.Printf("sending invoice %v", invoice) qui dumpent des objets complets.

La seconde passe demande des changements minimaux et sûrs :

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.

Si une règle peut être contournée, dites-le clairement : « Les exceptions sont permises seulement si vous ajoutez un court commentaire expliquant pourquoi, et un ticket de suivi pour supprimer l'exception. »

Après correction, le handler devient un adaptateur mince, le service gère le workflow, le storage contient la requête, les erreurs deviennent fmt.Errorf("send invoice: %w", err), et les logs deviennent une ligne propre avec des champs sûrs (ID de facture, pas la facture complète).

Prochaines étapes : rendre cela routinier sans ralentir

Choisissez un prompt approuvé par l'équipe et traitez-le comme un outil partagé. Commencez par ce qui vous fait le plus mal dans les revues (dérive du nommage, fuites de couches, erreurs incohérentes, logs non sûrs). Mettez à jour le prompt seulement quand vous observez une violation réelle dans du vrai code.

Gardez un petit bloc de règles en haut du prompt et collez-le dans chaque revue sans le modifier. Si tout le monde édite les règles à chaque fois, vous n'avez pas une norme, vous avez un débat.

Une cadence simple aide : une personne collecte les principales erreurs de style de la semaine et vous ajoutez exactement une règle clarifiée ou un meilleur exemple.

Si vous travaillez dans un flux de build piloté par chat comme Koder.ai (koder.ai), il vaut la peine d'exécuter les mêmes vérifications de porte pendant les changements, pas seulement à la fin. Des fonctionnalités comme la planification, les snapshots et le rollback peuvent aider à garder les corrections de style petites et réversibles avant d'exporter le code source.