clean-code-audit
Skill0 starsChanged 3 months agoMITView on GitHub
Audite la qualité du code TypeScript contre les standards de clean code Caudron — nommage, taille des fonctions, gestion d'erreurs, typage strict (any, enums, assertions), commentaires, code smells. Utiliser quand on demande un audit de clean code, une revue de qualité, ou une chasse à la dette technique.
In this repository3 other files it gives its agents.
- architecture-auditSkill
- design-auditSkill
- diff-auditSkill
The file
Files
SKILL.md
Skill: Clean Code Audit
Analyse le code source pour détecter les écarts avec les standards de clean code documentés.
Objectif
Comparer l'implémentation réelle du codebase avec les règles définies dans ${CLAUDE_PLUGIN_ROOT}/blueprints/clean-code/ et identifier les violations.
Prérequis
Lire les blueprints de référence embarqués dans le plugin :
${CLAUDE_PLUGIN_ROOT}/blueprints/clean-code/naming.md${CLAUDE_PLUGIN_ROOT}/blueprints/clean-code/functions.md${CLAUDE_PLUGIN_ROOT}/blueprints/clean-code/error-handling.md${CLAUDE_PLUGIN_ROOT}/blueprints/clean-code/typescript.md${CLAUDE_PLUGIN_ROOT}/blueprints/clean-code/comments.md${CLAUDE_PLUGIN_ROOT}/blueprints/clean-code/principles.md${CLAUDE_PLUGIN_ROOT}/blueprints/clean-code/code-smells.md
Les chemins de code audités (src/, netlify/) sont relatifs à la racine du projet analysé.
Exécution
Sur un projet de taille non triviale, déléguer à l'agent clean-code-auditor (read-only) plutôt que de tout lire soi-même. Il peut tourner en parallèle de architecture-auditor et design-auditor si un audit complet est demandé.
Règles d'Audit
Nommage (NM-*)
| ID | Règle | Sévérité | Pattern de Détection |
| NM-001 | Noms descriptifs, pas d'abréviations | MEDIUM | Chercher variables 1-2 lettres (hors i, x, y, err, e) dans src/, netlify/ |
| NM-002 | Vocabulaire cohérent (get/create/update/delete) | LOW | Chercher mélange fetch/retrieve/load vs get dans les hooks et services |
| NM-003 | Booléens avec préfixe is/has/can/should | MEDIUM | Chercher const [a-z]+ assigné à un booléen sans préfixe is/has/can/should/was |
| NM-004 | Handlers handle*, callbacks on* | LOW | Chercher handlers nommés autrement que handle* dans les composants |
| NM-005 | Fichiers nommés comme leur export | MEDIUM | Comparer nom fichier vs export principal dans src/components/, src/hooks/ |
| NM-006 | Pas de fichiers génériques (utils.ts, helpers.ts) | MEDIUM | Chercher fichiers nommés utils.ts, helpers.ts, misc.ts, common.ts |
| NM-007 | Types/interfaces PascalCase sans préfixe I/T | LOW | Chercher interface I[A-Z] ou type T[A-Z] |
| NM-008 | Pas d'enum, utiliser as const | MEDIUM | Chercher enum dans les fichiers TS |
Fonctions (FN-*)
| ID | Règle | Sévérité | Pattern de Détection |
| FN-001 | Fonctions courtes (max ~30 lignes) | MEDIUM | Compter les lignes des fonctions dans src/, netlify/ |
| FN-002 | Max 3 paramètres | MEDIUM | Chercher fonctions avec 4+ paramètres (hors objet d'options) |
| FN-003 | Pas de paramètres booléens | LOW | Chercher (param: boolean) dans les signatures de fonctions |
| FN-004 | Retours anticipés, pas d'imbrication profonde | HIGH | Chercher 4+ niveaux d'imbrication (if dans if dans if dans if) |
| FN-005 | Pas d'effets de bord dans les fonctions pures | MEDIUM | Chercher mutation de variables externes dans des fonctions de calcul |
| FN-006 | Pas de patterns async mélangés | LOW | Chercher .then( dans des fonctions async |
| FN-007 | Préférer les patterns fonctionnels | LOW | Chercher boucles for qui pourraient être map/filter/reduce |
Gestion d'erreurs (EH-*)
| ID | Règle | Sévérité | Pattern de Détection |
| EH-001 | Pas d'erreurs avalées silencieusement | HIGH | Chercher catch avec bloc vide ou seul console.log |
| EH-002 | Pas d'exceptions pour le flux de contrôle | MEDIUM | Chercher try/catch autour d'opérations non-async simples |
| EH-003 | Validation aux frontières seulement | MEDIUM | Chercher validation manuelle (if (!param) throw) hors handlers |
| EH-004 | Logging structuré avec contexte | LOW | Chercher logger.error avec seulement un string (pas d'objet contexte) |
| EH-005 | Error boundaries dans les pages | MEDIUM | Vérifier gestion de error et isLoading dans les composants qui fetch |
| EH-006 | Nettoyage dans finally | LOW | Chercher try avec opérations de ressource sans finally |
TypeScript (TS-*)
| ID | Règle | Sévérité | Pattern de Détection |
| TS-001 | Pas de any | HIGH | Chercher : any, as any, <any> |
| TS-002 | Pas d'enums, utiliser as const | MEDIUM | Chercher enum |
| TS-003 | Pas d'annotations redondantes | LOW | Chercher const x: string = '...', const x: number = 0, const x: boolean = true/false |
| TS-004 | Unions discriminées pour les états | MEDIUM | Chercher interfaces avec data? + error? + isLoading (devrait être union) |
| TS-005 | Pas d'assertion non-null (!) hors tests | HIGH | Chercher ! non-null assertion hors **/*.test.* et **/*.spec.* |
| TS-006 | Pas d'assertions as — préférer validation | MEDIUM | Chercher as [A-Z] (hors as const, as unknown) |
| TS-007 | Utiliser readonly pour les configs | LOW | Chercher interfaces de config sans readonly |
Commentaires (CM-*)
| ID | Règle | Sévérité | Pattern de Détection |
| CM-001 | Pas de commentaires "what" | LOW | Chercher commentaires qui décrivent ce que fait le code (heuristique) |
| CM-002 | Pas de code commenté | MEDIUM | Chercher blocs de code commentés (// const, // function, // if, // return) |
| CM-003 | TODO avec contexte | LOW | Chercher // TODO sans référence de ticket ou explication |
| CM-004 | Pas de JSDoc redondant sur fonctions internes | LOW | Chercher /** @param sur fonctions non exportées ou internes |
Principes (PR-*)
| ID | Règle | Sévérité | Pattern de Détection |
| PR-001 | Pas de God files (max ~200 lignes par fichier) | MEDIUM | Compter les lignes des fichiers dans src/, netlify/ |
| PR-002 | Pas de duplication de logique métier frontend/backend | HIGH | Chercher schémas Zod ou validation dupliqués entre src/ et netlify/ |
| PR-003 | Immutabilité — pas de mutation des entrées | MEDIUM | Chercher param.prop = ou .push( sur des paramètres de fonction |
Code smells (CS-*)
| ID | Règle | Sévérité | Pattern de Détection |
| CS-001 | Pas d'imbrication 4+ niveaux | HIGH | Compter les niveaux d'indentation dans les fonctions |
| CS-002 | Pas de nombres/chaînes magiques | MEDIUM | Chercher des littéraux numériques (hors 0, 1, -1) dans les conditions |
| CS-003 | Pas de prop drilling 3+ niveaux | MEDIUM | Chercher même prop passée sur 3+ composants imbriqués |
| CS-004 | Composants max ~150 lignes | MEDIUM | Compter les lignes des composants React |
| CS-005 | Requêtes Drizzle ORM, pas SQL brut | HIGH | Chercher db.execute(sql pour des requêtes simples |
Commandes de Détection
TS-001: Pas d'any
grep -rE "(: any|as any|<any>)" src/ netlify/ --include="*.ts" --include="*.tsx"TS-002 / NM-008: Pas d'enums
grep -rE "^(export )?enum " src/ netlify/ --include="*.ts" --include="*.tsx"TS-005: Assertions non-null hors tests
grep -rE "\w+!" src/ netlify/ --include="*.ts" --include="*.tsx" | grep -v "\.test\." | grep -v "\.spec\."TS-006: Assertions as Type
grep -rE " as [A-Z]" src/ netlify/ --include="*.ts" --include="*.tsx" | grep -v "as const" | grep -v "as unknown"EH-001: Erreurs avalées
grep -rE "catch.*\{" src/ netlify/ --include="*.ts" --include="*.tsx" -A 2 | grep -E "^\s*\}|console\.log"CM-002: Code commenté
grep -rE "^\s*//" src/ netlify/ --include="*.ts" --include="*.tsx" | grep -E "(const |let |function |return |if \(|import )"CM-003: TODO sans contexte
grep -rE "// TODO[^(]" src/ netlify/ --include="*.ts" --include="*.tsx" | grep -v "#\|ADV-\|JIRA-\|FIX-"FN-006: Patterns async mélangés
grep -rE "async.*\{" src/ netlify/ --include="*.ts" --include="*.tsx" -A 20 | grep "\.then("NM-006: Fichiers génériques
find src/ netlify/ -name "utils.ts" -o -name "helpers.ts" -o -name "misc.ts" -o -name "common.ts"CS-005: SQL brut pour requêtes simples
grep -rE "db\.execute\(sql" netlify/ --include="*.ts"PR-001: Fichiers trop longs
find src/ netlify/ -name "*.ts" -o -name "*.tsx" | xargs wc -l | sort -rn | head -20Classification des Sévérités
| Sévérité | Critères |
| HIGH | Perte de type safety, bugs silencieux, maintenabilité fortement dégradée |
| MEDIUM | Dette technique, lisibilité dégradée, violation de convention |
| LOW | Style, opportunité d'amélioration, cohérence |
Format de Rapport
Le rapport généré doit inclure :
- Résumé — Totaux par sévérité
- Violations par catégorie — NM-, FN-, EH-, TS-, CM-, PR-, CS-* avec fichier, ligne, description
- Tâches recommandées — Actions de remédiation priorisées
- Couverture des règles — Status PASS/FAIL par règle
Principes
- Non-destructif : Ne jamais modifier le code source
- Basé sur preuves : Chaque violation cite fichier et ligne
- Actionnable : Chaque violation a une action de remédiation claire
- Priorisé : Focus sur violations à fort impact
- Déterministe : Même codebase = même rapport
Exceptions Connues
Certains patterns sont intentionnels :
- Les assertions
!sont acceptées dans les fichiers de test (*.test.ts,*.spec.ts) as constetas unknownne sont pas des violations de TS-006- Les fichiers de migration Drizzle peuvent utiliser du SQL brut
- Les fichiers
index.tsde barrel exports peuvent dépasser 200 lignes - Les schémas Zod de validation ne comptent pas comme "God files"
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.