Personnalisation
Préférences personnelles (optionnelles) : ${AGENT_SKILLS_CONFIG:-~/.config/agent-skills}/CodeQuality/PREFERENCES.md.
Si ce fichier existe, lisez-le et appliquez-le ; sinon, utilisez les valeurs par défaut de la compétence. Préférences personnelles uniquement : tout ce qui est un fait concernant un dépôt ou un produit appartient à ce dépôt (son .claude/workflow-profile.sh ou ses configurations d'outils), jamais ici.
Que fait CodeQuality ?
Une boucle, deux perspectives. La boucle est toujours : détecter → choisir un élément → corriger derrière des tests → vérifier → répéter. La perspective outil corrige ce que les scanners signalent, par ordre de priorité, avec les tests existants comme filet de sécurité. La perspective principe corrige ce qui rend le code difficile à modifier (classes god, duplication, cœurs non testables), un principe SOLID / Clean Code à la fois, et n'applique jamais un changement de conception sans le montrer d'abord. Les deux perspectives lisent le même manifeste d'outils, écrivent dans le même répertoire de rapports et se terminent par le même Rapport d'Amélioration de la Qualité.
Deux perspectives
| Perspective outil | Perspective principe | |
|---|---|---|
| Pilote | sortie du scanner (summary.md) | odeurs de conception mappées vers Principles.md (smell-inventory.md, roadmap.md) |
| Unité de travail | un constat : une règle à un fichier:ligne | un principe sur un hotspot délimité : une extraction, une scission de classe, une inversion de dépendance |
| Ordre | P0 sécurité → P1 exactitude → P2 maintenabilité | échelle de levier (ci-dessous), ajustée par dépôt |
| Autonomie | corriger, puis montrer le diff | proposer → confirmer → appliquer ; rien n'est modifié avant approbation |
| Filet de sécurité | les tests existants restent verts | les tests de caractérisation sont écrits d'abord lorsque la cible n'est pas testée |
| Métrique | moins de constats, outil relancé propre | % de duplication, complexité cyclomatique, longueur de fonction, fan-in/out, « maintenant testable unitairement » |
| À choisir quand | dette de lint/type/sécurité, CI rouge, « rendre les scanners heureux » | code qui résiste au changement ; le volet structurel d'un sprint de remédiation |
La boucle
SCANNER → SÉLECTIONNER → FILET DE SÉCURITÉ → [PROPOSER → CONFIRMER] → CORRIGER → VÉRIFIER → RAPPORTER → RÉPÉTER
└─ obligatoire en mode principe, ignoré en mode outil ─┘
Routage des workflows
| Déclencheur | Workflow | Produit |
|---|---|---|
| « installer les outils de qualité », « configurer la qualité du code » | Workflows/Install.md | outils du manifeste installés et vérifiés |
| « scanner », « baseline », « analyser la qualité du code », « rapport d'odeurs », « par où commencer », « feuille de route de refactorisation » | Workflows/Scan.md | summary.md (A), smell-inventory.md (B), roadmap.md (C) |
| « améliorer la qualité du code », « corriger le lint », « boucle qualité », « corriger [constat] » | Workflows/Loop.md en mode outil | corrections, session-log.md, rapport |
| « refactoriser », « appliquer SOLID », « nettoyer ceci », « démarrer la boucle » | Workflows/Loop.md en mode principe | corrections, session-log.md, rapport |
| « nettoyer ce dépôt » sans qualificatif | Scan A + B + C, puis Loop en mode principe | tout ce qui précède |
| « sprint de remédiation », « cycle de remédiation » | IssueFlow Remediation gère la branche, la PR et la fusion ; Scan cadre le cycle, Loop l'exécute | une PR par cycle |
La boucle choisit son mode automatiquement quand aucun n'est donné : outil quand aucun roadmap.md n'existe pour le dépôt, principe quand il en existe un. L'utilisateur peut forcer l'un ou l'autre.
Le manifeste
Tools/tools.tsv est la seule liste d'outils de cette compétence. Séparé par des tabulations, une ligne par outil et langage : langage catégorie priorité outil install exécuter notes, avec langage en js | python | yaml, catégorie en lint | format | types | security | deadcode | duplication | complexity | deps | coverage, priorité en P0 | P1 | P2. Les deux scripts le lisent ; les workflows ne listent jamais d'outils en dur. Pour ajouter ou supprimer un outil, modifiez une ligne.
| Script | Lit depuis le manifeste | Fait |
|---|---|---|
Tools/install-quality-tools.sh [--dry-run] [lang ...] | cellules install des langages choisis | détecte les langages (package.json → js ; pyproject.toml, requirements.txt ou *.py → python ; *.yaml/*.yml → yaml) ; installe les outils js comme devDependencies avec le gestionnaire de paquets du dépôt (lockfile → npm/pnpm/bun), les outils python et yaml avec uv pip install ou pip ; les préfixes npm:/pip: surchargent le canal, - n'installe rien |
Tools/run-quality-baseline.sh [--dry-run] [lang ...] | cellules run | exécute chaque outil dans reports/codequality/<YYYY-MM-DD>-<HHMMSS>/, en substituant $OUT (répertoire de rapport), $SRC (QUALITY_SRC_DIRS, par défaut src si existe sinon .), $PM et $NPX ; un outil non installé est MANQUANT, un outil qui plante est EN ÉCHEC, aucun n'arrête l'exécution ; écrit summary.md avec le statut par outil, le nombre de problèmes analysés et les totaux P0/P1/P2 ; affiche le chemin du rapport |
Les lignes dont run est - (outils de couverture) sont installées mais pas exécutées par la baseline : la couverture est mesurée dans la Loop, limitée à la cible. Chaque outil est gratuit et s'exécute localement ; npm audit, pip-audit et checkov accèdent au réseau uniquement pour leurs bases de données de vulnérabilités.
Échelle de levier (ordre par défaut de la perspective principe)
- Noms — un code que vous ne pouvez pas lire, vous ne pouvez pas le modifier en toute sécurité. Peu coûteux, débloque tout.
- DRY / duplication — supprime le plus de code au risque le plus faible ; expose les abstractions cachées.
- Petites fonctions — Longue Méthode → Extraire ; un niveau d'abstraction par fonction.
- SRP — scinder les classes et modules qui changent pour plus d'une raison.
- OCP / DIP — inverser les dépendances, ajouter des points de couture ; impact élevé, risque plus élevé, filet de sécurité d'abord.
- ISP / LSP — interfaces grosses et substitutivité brisée ; nécessite les points de couture de l'étape 5.
La partie C du Scan ajuste cet ordre à l'inventaire réel (levier = impact ÷ risque ; voir Principles.md Partie 3).
Non-négociables
- Un élément par itération. Un constat, ou un principe sur une cible délimitée. Diffs petits et révisables.
- Conservation du comportement. La structure change, le comportement non. Si le comportement doit changer, arrêtez-vous et signalez-le : c'est une fonctionnalité, pas une correction.
- Du vert au vert. Les tests passent avant et après. Rouge après un changement signifie annuler, jamais corriger en avant.
- Tests de caractérisation d'abord lorsque les lignes à toucher ne sont pas testées. Pas de filet, pas de refactorisation.
- Proposer avant d'appliquer tout changement de conception (mode principe). Le mode outil peut corriger directement, puis montre le diff.
- P0 → P1 → P2 pour les constats d'outil, tous langages confondus, jamais par langage.
- Ne jamais affaiblir un test ou une règle de lint pour obtenir du vert. Les tests obsolètes évoluent vers le nouveau comportement correct ; les règles sont satisfaites dans le code.
- Boy Scout, limité. Laissez les fichiers touchés plus propres, mais n'élargissez pas le périmètre au-delà de l'élément en cours.
- Preuve, pas opinion. Nommez la règle ou le principe, et une métrique lorsqu'elle existe.
Artefacts produits
Tous sous reports/codequality/ (ignoré par git) :
| Fichier | Écrit par |
|---|---|
<YYYY-MM-DD>-<HHMMSS>/summary.md + sortie brute des outils | run-quality-baseline.sh (Scan A) |
<YYYY-MM-DD>/smell-inventory.md | Scan B |
<YYYY-MM-DD>/roadmap.md | Scan C |
<YYYY-MM-DD>/session-log.md | Loop, une entrée par itération |
<YYYY-MM-DD>/quality-report.md | Loop, à la fin de la session (ci-dessous) |
Rapport d'Amélioration de la Qualité (obligatoire)
Chaque session Loop se termine par ce rapport, quel que soit le mode. Il est le livrable accompagnant la modification du code, et le corps de la PR ou du commentaire de suivi lorsque le travail est livré via IssueFlow.
| Section | Contenu |
|---|---|
| Tableau récapitulatif | lignes ajoutées / supprimées / net ; problèmes avant → après par priorité ; hotspots de code mort supprimés ; tests avant → après (nombre, tous verts) |
| Code supprimé | fichier, quoi, lignes, risque |
| Code ajouté ou modifié | fichier, quoi, lignes, objectif |
| Bogues corrigés | sévérité, description, cause racine (uniquement si des bogues sont apparus) |
| Delta de complexité | complexité cyclomatique max et moyenne avant → après, avec une barre ASCII par hotspot |
| Différé | éléments vus mais hors périmètre, et pourquoi |