Découverte de la Dette Technique
Analyse la base de code pour détecter la dette technique et transformer les résultats en issues GitHub exploitables. L'analyse est en lecture seule : ne jamais modifier le code pendant l'exécution de ce skill.
Options
Les analyser à partir de la requête de l'utilisateur ou des arguments de commande :
- Chemins ciblés : répertoires ou fichiers à analyser (par exemple
src/services lib/). - --full : analyser l'ensemble du dépôt, en excluant les répertoires de dépendances, de construction et de VCS (
node_modules,vendor,.git,dist,build,target,tmp,log, environnements virtuels, code généré). - --dry-run : signaler les résultats sans créer d'issues.
- --all : lever la limite de 20 issues.
- --force : créer des issues même lorsqu'une issue similaire existe déjà.
- --yes : sauter l'invite de confirmation (uniquement lorsque l'utilisateur le passe explicitement).
- --categories=X,Y : exécuter uniquement ces catégories :
dead-code,duplication,architecture,deferred-work,patterns,tests.
Modèle d'exécution
Chaque catégorie est analysée indépendamment. Si votre agent peut engendrer des sous-agents parallèles, donnez à chaque catégorie son propre sous-agent avec le périmètre, la pile détectée et la liste de contrôle de la catégorie depuis references/categories.md, et demandez à chacun de retourner le format JSON ci-dessous. Sinon, exécutez les catégories séquentiellement, une par une, pour rester dans les limites de contexte.
Une exécution séquentielle complète des six catégories prend environ 15 à 30 minutes sur une base de code de taille moyenne. Pour des résultats plus rapides, suggérez --categories ou un périmètre plus restreint.
Étape 1 : Déterminer le périmètre
- Si des chemins ont été donnés, les utiliser.
- Si
--fulla été donné, analyser le dépôt avec les exclusions ci-dessus. - Sinon, détecter automatiquement les principaux répertoires source et de test qui existent (les plus courants :
src/,app/,lib/,pkg/,internal/,cmd/,test/,tests/,spec/). Afficher :Périmètre auto-détecté : [répertoires]. Environ X fichiers. Continuer ? (utilisez --full pour une analyse complète)
Compter les fichiers source dans le périmètre avec les extensions réellement utilisées par le dépôt (par exemple git ls-files -- <scope> | grep -E '\.(rb|py|ts|tsx|js|go|java|kt|rs|php|cs)$' | wc -l).
- Plus de 1 000 fichiers : avertir que l'exécution sera longue et suggérer
--categories. - Plus de 5 000 fichiers : recommander fortement d'exécuter une catégorie à la fois et donner une durée approximative par catégorie.
Étape 2 : Vérifications préalables à l'analyse
Sauf si --dry-run, vérifier la CLI GitHub :
gh auth status
Si elle échoue, définir gh_available=false et dire : "CLI gh non trouvée ou non authentifiée. Les résultats seront signalés sans création d'issues. Exécutez gh auth login pour activer la création d'issues."
Si disponible, récupérer ce qui sera nécessaire plus tard :
gh issue list --state open --limit 200 --json number,title,body,labels
gh label list --limit 200 --json name,description
Conserver la liste des issues pour la détection des doublons et la liste des labels pour l'étiquetage.
Étape 3 : Détecter la pile
Détecter le langage, le framework et le runner de test du dépôt au lieu d'en supposer un. Indicateurs typiques :
| Indicateur | Pile |
|---|---|
Gemfile avec rails, ou config/application.rb | Ruby on Rails |
manage.py ou django dans les requirements / pyproject.toml | Django |
pyproject.toml / requirements.txt avec fastapi ou flask | Python web |
package.json avec next, react, vue, svelte, express, nestjs | Framework JS/TS |
go.mod | Go |
Cargo.toml | Rust |
pom.xml / build.gradle* | JVM (Spring si présent) |
composer.json avec laravel/framework | Laravel |
*.csproj | .NET |
Détecter également le framework de test (RSpec, Minitest, pytest, unittest, Jest, Vitest, Mocha, Go testing, JUnit, PHPUnit, etc.) et les répertoires de test.
Lire les conventions propres au projet avant de juger quoi que ce soit : README, CONTRIBUTING, fichiers d'instructions pour agents (AGENTS.md, CLAUDE.md, GEMINI.md), configurations de linter et toute documentation d'architecture. Un motif que le projet a délibérément choisi n'est pas une dette.
Signaler : Pile détectée : [langage / framework / runner de test]. Règles d'analyse ajustées en conséquence.
Étape 4 : Exécuter les analyses par catégorie
Pour chaque catégorie activée (les six par défaut) :
- Annoncer
Analyse de [Catégorie]... (X sur N). - Appliquer la liste de contrôle pour cette catégorie dans
references/categories.md, adaptée à la pile détectée. - Collecter les résultats au format JSON ci-dessous.
- Signaler
[Catégorie] terminée : X résultats.
Si une catégorie prend beaucoup plus de temps que les autres (environ 5 minutes d'analyse active), l'arrêter et la marquer Incomplète (tronquée) dans le rapport plutôt que de bloquer l'exécution.
Format des résultats
Chaque catégorie retourne :
{
"category": "Code Mort",
"findings": [
{
"type": "Import inutilisé",
"severity": "P3",
"location": "src/utils/format.ts:5",
"line_number": 5,
"description": "L'import 'date-fns' n'est jamais utilisé dans ce fichier",
"evidence": "import { format } from 'date-fns'",
"remediation": "Supprimer l'import inutilisé",
"complexity": "simple"
}
]
}
Pour la duplication, placer chaque emplacement dans location, séparé par , . Pour les défauts d'architecture, mettre les métriques dans description (par exemple "567 lignes, 23 méthodes publiques").
Référence de sévérité
| Motif | Sévérité | Catégorie |
|---|---|---|
| Tests qui cachent des problèmes de sécurité | P0 | Qualité des tests |
| Absence de vérification d'autorisation sur l'accès aux ressources | P1 | Violations de patrons |
| God classes (>500 lignes ou >20 méthodes publiques) | P1 | Architecture |
| Dépendances circulaires | P1 | Architecture |
| Code inaccessible | P1 | Code mort |
| Tests qui ne font que moquer (le test moque ce qu'il teste) | P1 | Qualité des tests |
| Stub du sujet puis assertion sur celui-ci | P1 | Qualité des tests |
| Tests tautologiques | P1 | Qualité des tests |
| Corps de test vides | P1 | Qualité des tests |
| Mocking excessif (>50% du test est la configuration) | P1 | Qualité des tests |
| Stub de chaque instance d'une classe | P1 | Qualité des tests |
| État mutable partagé entre les tests | P1 | Qualité des tests |
| Fonctions longues (>50 lignes) | P2 | Architecture |
| Couplage élevé (>10 imports de projet) | P2 | Architecture |
| Doublons exacts ou quasi-identiques | P2 | Duplication |
| Avis de dépréciation | P2 | Travail différé |
| Marqueurs temporaires ou de contournement | P2 | Travail différé |
| Anti-patrons de framework | P2 | Violations de patrons |
| Tests couplés à l'implémentation | P2 | Qualité des tests |
| Tests qui ne vérifient que "ne lève pas d'exception" | P2 | Qualité des tests |
| Fonctions non référencées, branches mortes, fichiers orphelins | P2 | Code mort |
| Imbrication profonde (>4 niveaux) | P3 | Architecture |
| Imports inutilisés | P3 | Code mort |
| Commentaires TODO / FIXME | P3 | Travail différé |
| Code commenté | P3 | Travail différé |
| Violations de conventions | P3 | Violations de patrons |
| Assertions de test fragiles | P3 | Qualité des tests |
| TODOs qui référencent un ticket | P4 | Travail différé |
Guide de complexité
- simple : moins de 10 lignes, un fichier, correction évidente (supprimer un import inutilisé).
- moderate : 10 à 50 lignes, 2 ou 3 fichiers, refactoring simple (extraire une fonction).
- complex : plus de 50 lignes, nécessite une décision architecturale, ou touche à plusieurs endroits de la base de code (diviser une god class). Mentionner dans la remédiation qu'il faudra probablement une conception ou une proposition avant la mise en œuvre.
Étape 5 : Collecter et dédupliquer
- Regrouper les résultats par catégorie + fichier + ligne (à moins de 10 lignes près). Dans chaque groupe, conserver le résultat avec les preuves les plus détaillées, à la sévérité la plus élevée du groupe.
- Entre catégories : si Code mort et Architecture signalent la même classe, conserver le résultat d'Architecture. Si plusieurs catégories signalent la même ligne, les fusionner et conserver la sévérité la plus élevée.
- Trier P0 en premier, puis P1 à P4.
Étape 6 : Vérifier les issues existantes
Ignorer cette étape uniquement si --force est défini. Pour chaque résultat, rechercher une issue ouverte qui :
- mentionne le même chemin de fichier dans son titre ou son corps, ET
- couvre le même type de problème, ou une ligne à moins de 20 lignes de celle-ci.
Privilégier les issues intitulées [TechDebt] ou portant un label de dette technique, mais faire correspondre toute issue ouverte qui suit clairement le même problème. En cas de correspondance, marquer le résultat comme déjà suivi comme #N et ne pas le soumettre. Les différents types de problèmes dans le même fichier sont des résultats distincts.
Étape 7 : Confirmer, puis créer les issues
Ignorer la création si --dry-run ou gh_available=false ; passer directement au rapport.
Limite : au maximum 20 issues sauf --all. Remplir les emplacements dans l'ordre : tous les P0 et P1, puis P2 (préférer répartir entre plusieurs fichiers plutôt que plusieurs issues dans un seul fichier), puis P3, puis P4. Avec --all et plus de 50 issues, avertir que cela prendra du temps.
Labels : utiliser uniquement les labels qui existent déjà dans gh label list. Choisir la correspondance la plus proche pour la dette technique (par exemple tech-debt, technical-debt, debt, refactor, chore) et, si le dépôt en a, un label de priorité correspondant à la sévérité et un label de type (par exemple testing). Ne jamais créer de labels sans demander. Si aucun label approprié n'existe, le signaler et soit soumettre sans label, soit demander à l'utilisateur s'il faut créer tech-debt.
Confirmation (obligatoire) : avant de créer quoi que ce soit, afficher la liste complète et attendre la réponse de l'utilisateur. Ne jamais soumettre d'issues sans cela, sauf si l'utilisateur a passé --yes.
Va créer X issues (labels : tech-debt, P2) :
1. [P1] [TechDebt] Architecture : Diviser OrderService (612 lignes, 27 méthodes publiques)
2. [P1] [TechDebt] Qualité des tests : Corriger le test de mock uniquement dans payment_test.py:45
3. [P2] [TechDebt] Duplication : Extraire la validation d'adresse (user.ts:40, account.ts:88)
...
Déjà suivi (ignoré) : 3. Au-dessus de la limite (non soumis) : 12.
Continuer ? Vous pouvez également supprimer des éléments par numéro ou modifier les labels.
Appliquer toutes les modifications faites par l'utilisateur, puis créer chaque issue. Chaque corps doit être autonome, lisible par quelqu'un qui n'a pas vu ce rapport :
gh issue create \
--title "[TechDebt] <Catégorie> : <Brève description>" \
--label "<label-existant>" \
--body "$(cat <<'EOF'
**Catégorie :** <Catégorie>
**Sévérité :** P<N>
**Emplacement :** <fichier:ligne>
## Problème
<description>
## Preuve
```
<preuve>
```
## Correction suggérée
<remédiation>
**Complexité :** <simple|moderate|complex>
## Critères d'acceptation
- <vérification observable que la dette est résolue>
- La suite de tests complète du projet passe
EOF
)"
Exemples de titres :
[TechDebt] Code mort : Supprimer les imports inutilisés dans format.ts:5-12[TechDebt] Architecture : Diviser OrdersController (567 lignes, 23 actions)[TechDebt] Qualité des tests : Corriger le test de mock uniquement dans payment_service_test.go:45
Si un appel gh issue create échoue, enregistrer l'erreur et la commande, continuer avec le reste, et signaler Créées : X issues, Y en échec à la fin.
Si le dépôt suit le travail sur un tableau de projet GitHub (la section Issue tracking de ses instructions pour agent indique Mode: project, ou il n'y a pas de telle section et gh repo view --json projectsV2 montre un tableau lié), proposer d'exécuter le skill place-issues sur les nouvelles issues.
Étape 8 : Rapport de synthèse
=== Rapport de Découverte de la Dette Technique ===
Périmètre : [chemins analysés]
Fichiers analysés : [nombre]
Pile : [langage / framework / runner de test]
Durée : [temps écoulé]
## Résumé
- Résultats totaux : X | Issues créées : Y | Déjà suivis : Z | Au-dessus de la limite : W
- Par sévérité : P0 : A, P1 : B, P2 : C, P3 : D, P4 : E
## Résultats par Catégorie
### Code mort (X)
- [ ] #N : Supprimer les imports inutilisés dans format.ts:5-12 (P3)
### Duplication (X)
- [ ] #N : Extraire la validation d'adresse (user.ts:40, account.ts:88) (P2)
### Architecture (X)
- [ ] #N : Diviser OrderService (612 lignes, 27 méthodes publiques) (P1)
### Travail différé (X)
- [ ] #N : Résoudre TODO dans billing.py:123 (P3)
### Violations de patrons (X)
- [ ] #N : Corriger le risque de requête N+1 dans OrdersController#index (P2)
### Qualité des tests (X)
- [ ] #N : Corriger le test de mock uniquement dans payment_test.py:45 (P1)
## Déjà Suivis
- billing.py:100 TODO → #N
## Résultats Supplémentaires (au-dessus de la limite, non soumis)
[liste]
Exécutez avec --all pour soumettre les X résultats restants.
## Ignorés (faux positif ou intentionnel)
- tests/fixtures/** : fixtures exclues
- TODO(#42) dans conftest.py : a un ticket lié (P4)
## Statut de l'Analyse
- Code mort : Terminé
- ...
- Qualité des tests : Incomplète (tronquée)
## Erreurs
[éventuelles commandes gh en échec]
Pour --dry-run, remplacer les numéros d'issue par [serait créé].
Principes
- Lecture seule. Aucune modification de code pendant l'analyse.
- Conservateur. En cas de doute, passer plutôt que de signaler un faux positif. Un rapport bruyant est ignoré.
- Respecter le projet. Les conventions du framework (callbacks, décorateurs, injection de dépendances, routage par convention) et les choix documentés dans le dépôt ne sont pas une dette.
- La preuve d'abord. Chaque résultat cite un fichier, une ligne et le code qui le prouve.
- Sortie structurée. Les analyses par catégorie retournent du JSON pour que la fusion et la déduplication soient fiables.
- L'utilisateur confirme avant de soumettre. La liste est toujours affichée en premier.