tech-debt

Skill de codage. Analyse une base de code pour détecter la dette technique (code mort, duplication, défauts d'architecture, travail différé, anti-patrons de framework, tests de faible valeur), classe les résultats par sévérité et les enregistre en tant qu'issues GitHub après confirmation de l'utilisateur. À utiliser lorsque l'utilisateur demande un audit de dette technique, un nettoyage de la qualité du code, une liste de candidats au refactoring, ou souhaite transformer la dette en issues suivies. Prend en charge un chemin ciblé, une analyse complète, des catégories sélectionnées et une simulation (dry run).

Qu'est-ce que tech-debt ?

Ce skill analyse une base de code pour identifier et prioriser la dette technique, puis crée automatiquement des issues GitHub pour chaque problème trouvé. Il couvre six catégories : code mort, duplication, architecture, travail différé, anti-patrons de framework et qualité des tests. L'analyse est en lecture seule et peut être exécutée sur un chemin spécifique ou sur l'ensemble du dépôt, avec la possibilité de limiter les catégories ou de faire une simulation. Il utilise la CLI GitHub pour créer les issues, détecte automatiquement la pile technologique du projet (langage, framework, test runner) pour adapter ses règles, et applique un système de sévérité (P0 à P4) avec déduplication des résultats. L'utilisateur doit confirmer la liste avant la création des issues, et le skill peut être utilisé avec des agents parallèles pour accélérer l'analyse. Il est particulièrement utile pour les développeurs et les équipes souhaitant maintenir une base de code saine et suivre les efforts de refactoring de manière structurée.

Compatible avec✓Claude Code~Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/JAdshead/toolkit/tree/HEAD/skills/tech-debt

Installed? Explore more Développement et programmation skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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

  1. Si des chemins ont été donnés, les utiliser.
  2. Si --full a été donné, analyser le dépôt avec les exclusions ci-dessus.
  3. 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 :

IndicateurPile
Gemfile avec rails, ou config/application.rbRuby on Rails
manage.py ou django dans les requirements / pyproject.tomlDjango
pyproject.toml / requirements.txt avec fastapi ou flaskPython web
package.json avec next, react, vue, svelte, express, nestjsFramework JS/TS
go.modGo
Cargo.tomlRust
pom.xml / build.gradle*JVM (Spring si présent)
composer.json avec laravel/frameworkLaravel
*.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) :

  1. Annoncer Analyse de [Catégorie]... (X sur N).
  2. Appliquer la liste de contrôle pour cette catégorie dans references/categories.md, adaptée à la pile détectée.
  3. Collecter les résultats au format JSON ci-dessous.
  4. 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é

MotifSévéritéCatégorie
Tests qui cachent des problèmes de sécuritéP0Qualité des tests
Absence de vérification d'autorisation sur l'accès aux ressourcesP1Violations de patrons
God classes (>500 lignes ou >20 méthodes publiques)P1Architecture
Dépendances circulairesP1Architecture
Code inaccessibleP1Code mort
Tests qui ne font que moquer (le test moque ce qu'il teste)P1Qualité des tests
Stub du sujet puis assertion sur celui-ciP1Qualité des tests
Tests tautologiquesP1Qualité des tests
Corps de test videsP1Qualité des tests
Mocking excessif (>50% du test est la configuration)P1Qualité des tests
Stub de chaque instance d'une classeP1Qualité des tests
État mutable partagé entre les testsP1Qualité des tests
Fonctions longues (>50 lignes)P2Architecture
Couplage élevé (>10 imports de projet)P2Architecture
Doublons exacts ou quasi-identiquesP2Duplication
Avis de dépréciationP2Travail différé
Marqueurs temporaires ou de contournementP2Travail différé
Anti-patrons de frameworkP2Violations de patrons
Tests couplés à l'implémentationP2Qualité des tests
Tests qui ne vérifient que "ne lève pas d'exception"P2Qualité des tests
Fonctions non référencées, branches mortes, fichiers orphelinsP2Code mort
Imbrication profonde (>4 niveaux)P3Architecture
Imports inutilisésP3Code mort
Commentaires TODO / FIXMEP3Travail différé
Code commentéP3Travail différé
Violations de conventionsP3Violations de patrons
Assertions de test fragilesP3Qualité des tests
TODOs qui référencent un ticketP4Travail 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

  1. 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.
  2. 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.
  3. 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

  1. Lecture seule. Aucune modification de code pendant l'analyse.
  2. Conservateur. En cas de doute, passer plutôt que de signaler un faux positif. Un rapport bruyant est ignoré.
  3. 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.
  4. La preuve d'abord. Chaque résultat cite un fichier, une ligne et le code qui le prouve.
  5. Sortie structurée. Les analyses par catégorie retournent du JSON pour que la fusion et la déduplication soient fiables.
  6. L'utilisateur confirme avant de soumettre. La liste est toujours affichée en premier.

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Skills associés