Que fait clean-code-guard ?
Vous examinez du code généré ou modifié avant sa livraison. Appliquez les règles ci-dessous comme un passage de garde après le premier passage d'implémentation — et une fois cette compétence active, continuez à l'appliquer à chaque modification de code ultérieure dans la même session, en réexécutant l'auto-vérification avant la livraison après chaque édition, plutôt que de revenir à une sortie non protégée parce que la compétence a été chargée plus tôt. Si l'utilisateur invoque explicitement cette compétence avant d'écrire du code, utilisez les mêmes règles pendant l'écriture et exécutez toujours l'auto-vérification avant la livraison.
Intégration avec l'équipe d'agents
Les règles du dépôt, les contrats acceptés, les permissions de rôle et la portée utilisateur prévalent sur ce guide et ses références. DEV utilise le passage de garde sur ses propres modifications ; CR utilise le mode révision en lecture seule et ne modifie pas l'implémentation. Traitez les limites numériques, les interdictions de nommage, les formes des arguments et les règles d'abstraction comme des signaux à investiguer, et non comme des modifications ou des blocages automatiques. Une constatation doit expliquer un coût concret de correction ou de maintenance dans son contexte ; ne divisez pas du code cohérent, ne cassez pas des interfaces et n'ajoutez pas de commentaires d'exception uniquement pour satisfaire un nombre. Examinez le code modifié et ses appelants directement affectés, et non la dette non liée.
Tous les conseils et listes de contrôle utilisés par ce paquet sont locaux. Les noms de publications externes sont uniquement attributifs ; utilisez les preuves du dépôt et les références fournies plutôt que de naviguer. Si cette tâche dépasse le cadre de la compétence, suivez le processus normal du dépôt ; aucune compétence sœur n'est requise.
Compatibilité
Il s'agit d'une compétence d'instruction portable. Elle ne nécessite pas de serveur MCP, d'accès réseau,
d'API, d'exécutable local, ou de script fourni. Elle peut être utilisée dans
n'importe quel environnement d'exécution prenant en charge SKILL.md ainsi que les fichiers references/ liés directement ; agents/openai.yaml est des métadonnées d'affichage légères.
Cette compétence ne remplace pas les linters, les formateurs, les vérificateurs de type ou les exécuteurs de tests du projet. Utilisez les outils du projet pour la vérification mécanique ; utilisez cette compétence pour la couche de jugement concernant la qualité du code et la révision.
Comment utiliser cette compétence
Cette compétence a trois modes — choisissez en fonction de la demande de l'utilisateur.
Mode garde-fou (recommandé) : après que le code a été généré, modifié, refactorisé ou corrigé, vérifiez le diff ou les fichiers cibles par rapport aux Impératifs toujours appliqués ci-dessous. Corrigez les violations avant de présenter, valider ou fusionner le travail.
Mode direct (explicite) : lorsque l'utilisateur invoque cette compétence avant une modification de code risquée, appliquez les mêmes impératifs pendant l'écriture, puis exécutez la liste de contrôle Auto-vérification avant la livraison. Si vous enfreignez une règle, corrigez-la avant de montrer le résultat à l'utilisateur.
Mode révision (déclenché lorsque l'utilisateur vous demande de réviser, auditer, critiquer ou noter du code) : parcourez references/review-checklist.md sur le(s) fichier(s) cible(s) et produisez un rapport structuré des constatations. Ne modifiez pas le code en mode révision sauf demande explicite.
Dans les trois modes, le corps des règles se trouve dans references/. Lisez le fichier de référence pertinent lorsque :
- Vous rencontrez une règle dont vous ne vous souvenez pas complètement du raisonnement.
- L'utilisateur conteste une règle et vous avez besoin de la citation source.
- Vous êtes en mode révision et avez besoin de la liste de contrôle complète.
- Le code examiné touche à un principe spécifique (par exemple, sous-classification → references/solid.md ; déduplication → references/dry-kiss-yagni.md).
Les fichiers de référence sont :
- references/naming-and-functions.md — noms, taille des fonctions, paramètres, séparation commande/requête.
- references/comments-and-formatting.md — quand commenter, quand supprimer, respect du style voisin.
- references/solid.md — SRP, OCP, LSP, ISP, DIP avec les formulations modernes et les signaux de détection.
- references/dry-kiss-yagni.md — duplication de connaissance vs code, règle de ré-inlining de Sandi Metz, complexité de McCabe, catégories de coût YAGNI de Fowler.
- references/ai-failure-modes.md — les 14 façons systématiques dont les LLM produisent du mauvais code. Lisez celui-ci en premier si vous êtes un agent IA lisant cette compétence. C'est le fichier à plus forte valeur ajoutée de la compétence.
- references/review-checklist.md — parcours structuré pour le mode révision.
- references/sources.md — bibliographie centrale pour les URL sources. Lisez-le uniquement lorsque vous avez besoin de vérifier ou de citer une source externe.
Exemples
- Un agent de codage implémente un point de terminaison : utilisez le mode garde-fou sur le diff avant que le travail soit présenté ou validé.
- L'utilisateur demande "réviser cette PR" ou "devrais-je fusionner ceci ?" : utilisez le mode révision et rapportez les constatations de references/review-checklist.md ; ne modifiez pas sauf demande explicite.
- L'utilisateur demande "implémenter ce point de terminaison en utilisant clean-code-guard" : utilisez le mode direct pendant l'écriture, puis exécutez l'auto-vérification avant la livraison.
- L'utilisateur demande "refactoriser cette fonction, même comportement" : préservez le comportement observable exactement et traitez toute correction de bogue comme une modification distincte.
Critères de succès
Cette compétence fonctionne lorsque les tâches d'écriture de code évitent les modes de défaillance listés, les tâches de révision de code produisent des constatations priorisées avec des preuves concrètes, et les refactorisations préservent le comportement sauf si l'utilisateur demande explicitement un changement de comportement. Elle doit rester silencieuse pour les tâches conceptuelles, d'IC, de workflow git, de prose, d'analyse de données et d'exécution de tests couvertes par les exclusions de l'en-tête.
Pourquoi cette compétence existe
Le code généré par LLM présente des modes de défaillance systématiques et mesurables que les instructions génériques "suivre le clean code" ne détectent pas. Exemples appuyés par des recherches publiées :
- La duplication de code a augmenté de 8x dans les bases de code suivies entre 2021 et 2024 (rapport GitClear 2025).
- Le taux d'hallucination de paquets est en moyenne de 19,6 % sur 16 modèles (Spracklen et al., USENIX Security '25).
- Les LLM encapsulent souvent les opérations risquées dans des gestionnaires génériques qui avalent les erreurs (Karpathy).
- Les agents IA "déclarent le succès malgré des échecs de tests" en renvoyant des valeurs de fixture codées en dur (Fowler, Patterns for Reducing Friction).
- La taille des fonctions est passée de 142 à 267 lignes de code, la complexité cyclomatique de 4,2 à 8,1 dans les commits assistés par IA (GitClear).
Les principes classiques (Clean Code, SOLID, DRY/KISS/YAGNI) restent le fondement — mais cette compétence ajoute la couche spécifique à l'IA que la plupart des ensembles de règles négligent.
Impératifs toujours appliqués
Ce sont les règles à suivre pour chaque modification de code. Elles sont impératives, pas des suggestions.
Fonctions et noms
- Les noms révèlent l'intention. N'utilisez jamais
data,data2,result,result_final,item,temp,value,obj,info,helper,manager,utils, ouhandle_*/process_*/do_*sans qualificatif. Un nom doit répondre à pourquoi il existe et ce qu'il fait. (Clean Code Ch. 2) - Les fonctions restent petites. Visez ≤20 lignes, un niveau d'abstraction, une chose. Si vous pouvez extraire une fonction avec un nom qui ne répète pas le corps, la fonction parent faisait plus d'une chose. (Clean Code Ch. 3)
- Quatre arguments est le plafond dur. À cinq, arrêtez-vous et introduisez un objet de requête/config (enregistrement, struct, DTO ou équivalent). N'utilisez jamais d'arguments booléens — divisez plutôt en deux fonctions.
- Pas d'arguments de sortie. Une fonction soit renvoie une valeur (requête), soit a un effet secondaire (commande). Jamais les deux. Les noms de commande utilisent des verbes ; les noms de requête utilisent des noms ou des noms de style getter. (CQS)
Commentaires et structure
- Les commentaires expliquent pourquoi, jamais quoi. Supprimez tout commentaire qui paraphrase la ligne en dessous. Supprimez les commentaires d'échafaudage de numérotation d'étape. Supprimez le code commenté — le contrôle de version existe. (Clean Code Ch. 4)
- Respectez le style existant du fichier. Lisez le fichier que vous modifiez et au moins un fichier voisin avant d'écrire. Miroir de la casse, de l'ordre des imports, de la gestion des erreurs, de la journalisation et des choix de client HTTP/BD. N'introduisez pas un second modèle.
SOLID
- Un acteur par module. Une classe doit répondre à un groupe de parties prenantes (Comptabilité, Authentification, Rapports). Si deux sous-systèmes non liés accèdent tous deux à la même classe, divisez-la. (SRP, Uncle Bob 2014)
- Extension via nouveau code, pas par modifications. Si l'ajout d'une nouvelle variante nécessite une autre branche de type dans une fonction existante, refactorisez d'abord vers un registre, une stratégie ou un dispatch polymorphe. (OCP)
- Aucune sous-classe ne refuse le contrat de sa classe mère. Ne remplacez jamais une méthode pour signaler "non implémenté" ou "opération non prise en charge." Ne renforcez jamais les préconditions et n'affaiblissez jamais les postconditions dans une substitution. Si vous devez faire cela, l'héritage est erroné. (LSP)
- Les abstractions vivent avec le client, pas avec l'implémentation. Lorsque vous introduisez une interface, un protocole ou un contrat abstrait, placez-le dans le paquet qui le consomme, pas à côté de la classe concrète. (DIP)
DRY, KISS, YAGNI
- Supprimez la connaissance dupliquée, pas le texte dupliqué. Deux fonctions qui se ressemblent mais encodent des règles différentes ne constituent pas une violation DRY. Une règle exprimée dans le code + la documentation + le schéma en est une. (Pragmatic Programmer, "DRY")
- La mauvaise abstraction est pire que la duplication. Si une abstraction a accumulé des branches pour le cas spécial de chaque appelant, ré-inlinez-la dans les appelants, puis supprimez les branches mortes avant de ré-abstraire. (Sandi Metz, "The Wrong Abstraction")
- Plafond de complexité : cyclomatique ≤10, profondeur d'imbrication ≤5. Refactorisez avant de dépasser. (McCabe 1976)
- Aucune spéculation. Pas de paramètre optionnel, de drapeau de configuration, de variable d'environnement, de bascule de fonctionnalité, d'interface, d'usine ou de classe de base sans appelant actuel. Si vous vous retrouvez à ajouter
enable_*,use_*_v2, ou*_mode, supprimez-le et livrez le comportement concret. (Fowler, "Yagni")
Garde-fous spécifiques à l'IA — la section à plus forte valeur ajoutée
- N'avalez jamais les erreurs avec une gestion générique large. Attrapez uniquement le type d'erreur spécifique dont vous pouvez vous remettre. Si vous ne pouvez pas vous en remettre, laissez l'erreur se propager. Renvoyer null/aucun/succès vide depuis un gestionnaire d'attrape est interdit sauf si le contrat de la fonction documente ce comportement. (Karpathy)
- Protégez la frontière ; faites confiance au contrat. À une frontière de confiance — entrée externe, charges utiles de requêtes/API, données désérialisées ou inter-processus, tout ce qui provient d'une source non fiable — validez, même si le chemin heureux semble correct. À l'intérieur de la frontière, n'ajoutez pas de vérifications nulles ou de vérifications de type à l'exécution pour des valeurs dont le type déclaré ou le contrat de l'appelant exclut déjà ce cas. Le test pour une protection n'est pas "pourrait-ce être théoriquement faux" mais "des données non fiables peuvent-elles arriver ici." (arXiv 2409.19182)
- Vérifiez chaque import et appel externe. Avant d'appeler une méthode sur une bibliothèque, confirmez qu'elle existe dans la version installée (lisez le paquet, vérifiez le fichier de verrouillage, ou importez et inspectez). Ne générez pas de code basé sur ce à quoi l'API "devrait" ressembler. (USENIX Security '25)
- Pas de retours "succès" codés en dur ou de fixtures simulées dans le code de production. Ne renvoyez jamais
{"status": "ok", ...}ou des données préfabriquées depuis une fonction dont la spécification dit qu'elle fait un vrai travail. Si vous ne pouvez pas implémenter, échouez explicitement avec le mécanisme non implémenté ou d'opération non prise en charge du langage et dites-le. Ne désactivez, ne sautez et n'affaiblissez jamais un test pour le faire passer. (Fowler, Claude Code issue #6984) - Re-dérivez, ne copiez pas à partir du similaire. Lorsque vous êtes tenté de copier une fonction et de la modifier, arrêtez-vous. Re-dérivez à partir de la spécification. Les bogues de décalage d'un et de sémantique nulle incorrecte entrent presque toujours par la copie à partir du similaire. (arXiv 2411.01414)
- Énumérez les cas limites avant de les écrire. Pour toute plage, décalage d'un, nul/vide/un/plusieurs, pair/impair, ou limite unicode/octet, écrivez d'abord la liste des cas dans un commentaire. Couvrez chaque cas dans le code avant de passer à autre chose.
- Supprimez le code mort avant la livraison. Exécutez un linter ou une passe grep pour les imports inutilisés, les symboles inutilisés, les branches inaccessibles et les exportations "juste au cas où." Supprimez-les. Une fonction que rien n'appelle aujourd'hui ne peut pas vivre pour "un jour."
- Lisez avant d'écrire. Avant d'écrire dans un dépôt inconnu, lisez le fichier que vous allez modifier, un fichier voisin, et tout fichier de règles du projet (CLAUDE.md, AGENTS.md, section "conventions" du README). Utilisez les assistances, les types d'erreur et la journalisation existants du projet.
- Pas de nouvelle dépendance pour ce que quelques lignes couvrent. Avant d'ajouter un paquet, vérifiez la bibliothèque standard, les dépendances déjà installées, et si quelques lignes de code local suffisent. Une nouvelle dépendance est une maintenance permanente et une surface de chaîne d'approvisionnement ; n'en ajoutez une que lorsqu'elle possède une complexité réelle que vous ne devriez pas réimplémenter (cryptographie, analyse, fuseaux horaires — illustratif, non exhaustif), jamais pour économiser dix lignes. Voir references/dry-kiss-yagni.md.
Le plancher — ne supprimez jamais ces éléments pour la simplicité
La règle 16 fait confiance au contrat à l'intérieur de la frontière ; les éléments ci-dessous restent même si vous supprimez la spéculation (14), les protections défensives (16) et le code mort (21). En supprimer un est un changement de comportement, pas un nettoyage — conservez-le, ou signalez-le et demandez.
- Validation et assainissement à chaque frontière de confiance — entrée externe, charges utiles de requêtes/API, données désérialisées ou inter-processus.
- Gestion des erreurs qui empêche la perte de données.
- Mesures de sécurité — autorisation, échappement de sortie, requêtes paramétrées, gestion des secrets.
- Comportement demandé explicitement par l'utilisateur. Mentionné en passant ≠ demandé, mais ne supprimez pas ce qui a été demandé.
Discipline de refactorisation
- Préservez le comportement observable lors de la refactorisation. Lorsque l'utilisateur vous demande de nettoyer, simplifier ou refactoriser du code existant, ne modifiez pas le contrat — mêmes entrées produisent les mêmes sorties, mêmes exceptions levées, mêmes effets secondaires, mêmes garanties d'ordre. Si vous repérez un bogue pendant la refactorisation, signalez-le séparément et demandez avant de le modifier. La refactorisation est définie comme "un changement apporté à la structure interne d'un logiciel pour le rendre plus facile à comprendre et moins coûteux à modifier sans changer son comportement observable" (Fowler, Refactoring). Les corrections de bogues et les refactorisations sont deux opérations — ne les regroupez jamais dans un seul changement.
Auto-vérification avant la livraison
Avant de montrer le résultat à l'utilisateur (que ce soit une implémentation, une modification ou une suggestion), passez en revue la liste de contrôle suivante. Si vous enfreignez l'un de ces éléments, corrigez-le d'abord.
- Y a-t-il des imports ou des appels externes non vérifiés ? (Règle 17)
- Y a-t-il un gestionnaire d'attrape générique qui avale des erreurs ? (Règle 15)
- Y a-t-il des noms de type
data,result,temp? (Règle 1) - Y a-t-il des arguments booléens ou plus de quatre paramètres ? (Règles 3, 4)
- Y a-t-il du code mort (commenté, impossible à atteindre, importé mais inutilisé) ? (Règle 21)
- Y a-t-il une duplication de connaissance (pas seulement de texte) ? (Règle 11)
- La fonction fait-elle plus d'une chose ? Faites-vous plus d'une chose dans la même modification ? (Règles 2, 24)
- Cette modification introduit-elle une abstraction spéculative ? (Règle 14)
- Cette modification viole-t-elle un invariant de type ou la contrainte d'une classe de base ? (Règle 9)
- Les cas limites (plages, limites, conditions nul/vide/un/plusieurs) sont-ils explicitement gérés ? (Règle 20)
Si les réponses à toutes ces questions sont "non" ou "N/A", la modification est prête à être présentée ou validée. Sinon, corrigez d'abord.
Licence
Aucune restriction explicite ; conçu pour être inclus dans les instructions du système ou les dossiers du projet en tant que fichier SKILL.md.