Guide d’introduction aux compétences mattpocock Skills : apprendre à l’IA à faire du TDD et à déboguer de façon structurée

Présentation du projet

mattpocock/skills est un « kit de compétences » de méthodologie d’ingénierie pour les outils de programmation par IA. Son point de départ est très simple : les outils de programmation par IA vont vite, mais ce n’est pas pour autant qu’ils sont fiables.

Au fil de nombreuses pratiques, Matt Pocock a identifié quatre modes d’échec fréquents dans la programmation par IA :

• Désalignement des besoins : vous pensez que l’IA a compris, mais elle dévie
• Sorties trop redondantes : l’IA emploie 20 mots pour dire ce qu’on pourrait exprimer en 1 mot
• Le code ne marche pas : sans boucle de feedback, l’IA code à l’aveugle dans une boîte noire
• Une architecture qui se dégrade vite : l’IA accélère le développement, mais accélère aussi l’entropie logicielle

Ces problèmes ne sont pas des bugs de l’outil : ils viennent d’un manque de méthodologie. mattpocock/skills apporte une réponse ciblée : elle compresse des décennies d’expérience d’ingénierie en un ensemble de compétences (Skills) composables, pour que l’IA suive la même discipline d’ingénierie quel que soit le modèle.

Niveau / Durée / Résultats

Niveau : Débutant — aucune expérience en TDD requise, il suffit de savoir utiliser la ligne de commande et un outil de programmation par IA
Durée : environ 30 minutes pour parcourir entièrement le flux
Résultats : mettre en place un workflow complet de l’alignement des besoins → tests pilotés par les tests → débogage structuré → réflexion architecturale

Profil des lecteurs cibles

• Développeurs backend / full-stack avec 1 à 5 ans d’expérience
• Vous utilisez déjà Claude Code, Codex ou un outil de programmation par IA similaire
• Vous avez l’impression que le code généré « fonctionne, mais manque de stabilité », et vous voulez instaurer un rythme de développement maîtrisé
• Vous êtes intéressé par le TDD, mais vous n’avez jamais trouvé une bonne porte d’entrée

Dépendances et environnement

Arborescence complète du projet

skills/
├── CLAUDE.md                          # Spécification du répertoire des compétences
├── README.md                          # Vue d’ensemble et documentation d’utilisation
├── skills/
│   ├── engineering/
│   │   ├── diagnose/
│   │   │   └── SKILL.md               # Processus de débogage structuré
│   │   ├── grill-with-docs/
│   │   │   └── SKILL.md               # Entretien approfondi avec documents
│   │   ├── improve-codebase-architecture/
│   │   │   └── SKILL.md               # Diagnostic d’amélioration d’architecture
│   │   ├── setup-matt-pocock-skills/
│   │   │   └── SKILL.md               # Point d’entrée d’initialisation
│   │   ├── tdd/
│   │   │   ├── SKILL.md               # Workflow de TDD en tranches verticales
│   │   │   ├── tests.md               # Exemples de tests bons / mauvais
│   │   │   ├── mocking.md             # Bonnes pratiques pour les mocks
│   │   │   ├── refactoring.md         # Quand décider de refactoriser
│   │   │   ├── deep-modules.md        # Principes de conception pour modules profonds
│   │   │   └── interface-design.md    # Conception d’interfaces testables
│   │   ├── to-issues/
│   │   │   └── SKILL.md               # Découpage des besoins en GitHub Issues
│   │   ├── to-prd/
│   │   │   └── SKILL.md               # Génération de PRD
│   │   ├── triage/
│   │   │   └── SKILL.md               # Machine à états de triage des issues
│   │   └── zoom-out/
│   │       └── SKILL.md               # Lecture à l’échelle globale du code
│   ├── productivity/
│   │   ├── caveman/
│   │   │   └── SKILL.md               # Mode de communication compressé, économise 75% de tokens
│   │   ├── grill-me/
│   │   │   └── SKILL.md               # Entretien approfondi sur les besoins
│   │   └── write-a-skill/
│   │       └── SKILL.md               # Guide pour écrire des Skills personnalisées
│   └── misc/
│       ├── git-guardrails-claude-code/
│       │   └── SKILL.md               # Garde-fous de sécurité Git
│       └── scaffold-exercises/
│           └── SKILL.md               # Échafaudage du répertoire d’exercices
└── .claude-plugin/
    └── plugin.json                    # Métadonnées du plugin

Étapes pas à pas

Étape 1 : Installer mattpocock Skills

Dans n’importe quel outil de programmation par IA qui prend en charge Skills, exécutez la commande suivante pour finaliser l’installation :

npx skills@latest add mattpocock/skills

Le script d’installation vous guide pour choisir les Skills à activer, et à quel outil IA elles sont rattachées. Étape clé : confirmez le choix de /setup-matt-pocock-skills ; c’est le point d’entrée d’initialisation pour toutes les Skills à venir.

Étape 2 : Initialiser la configuration

Une fois l’installation terminée, exécutez dans votre outil de programmation par IA :

/setup-matt-pocock-skills

Cette Skill vous pose successivement :

1. Issue Tracker : quel outil utilisez-vous pour gérer les Issues (GitHub / Linear / fichiers locaux)
2. Triage Labels : quels termes utiliser pour étiqueter une Issue (la Skill /triage s’en servira)
3. Chemin de sauvegarde des documents : où seront générés les ADR et autres documents

Une fois la configuration terminée, un CONTEXT.md sera généré à la racine du projet : c’est un « dictionnaire de langue commune » entre l’IA et vous. Ce fichier est extrêmement important : il uniformise l’usage des termes dans le projet ; ensuite, toutes les conventions de nommage et les commentaires de l’IA s’appuieront sur ce contenu.

Étape 3 : Aligner les besoins avec /grill-me

Quand vous avez un nouveau besoin ou un design à confier à l’IA, ne lancez pas directement la production. Exécutez d’abord :

/grill-me

L’IA vous interrogera une à une, en passant par toutes les branches de l’arbre de décisions. Par exemple, si vous prévoyez « d’ajouter une fonctionnalité de remboursement au module de paiement », l’IA va relancer :

• Le remboursement est-il intégral ou partiel ?
• Quels sont les déclencheurs du remboursement (action utilisateur / automatisation par fraude / manuel par le support) ?
• Que devient l’inventaire après le remboursement ?
• Faut-il persister les logs de remboursement ?

Chaque question s’accompagne d’une proposition de réponse, et vous n’avez qu’à confirmer ou corriger. Ce processus ressemble à un entretien structuré : il s’assure que l’IA comprend réellement ce que vous voulez faire, plutôt que de dévier « au sens littéral ».

Étape 4 : Utiliser /tdd pour des tests en tranches verticales

Une fois les besoins alignés, on passe au développement. C’est la partie la plus centrale de mattpocock/skills : interdiction des tranches horizontales.

Qu’est-ce qu’une tranche horizontale ? Écrire tous les tests d’abord, puis écrire tout le code ensuite. C’est un terrain de malentendus TDD très fréquent : l’IA y tombe particulièrement facilement, et les tests finissent par « tester un comportement imaginé », pas le comportement réel.

La bonne approche : ne faire qu’une tranche verticale à la fois.

ROUGE : Écrire un test qui décrit le premier comportement → test échoue
VERT : Écrire le code minimal pour faire passer le test → test passe
REFactor : Refactoriser (optionnel)

Répétez cette boucle. À chaque fois que l’IA termine un test, elle a déjà « vu » l’implémentation correspondante ; du coup, elle teste un comportement réel, pas un comportement supposé.

Prenons un exemple concret : supposons qu’on doive implémenter une fonctionnalité de checkout pour un panier.

// Première manche : on teste seulement « le panier peut ajouter un article »
import { describe, it, expect } from 'vitest';
import { Cart } from './cart';

describe('Cart', () => {
  it('allows adding an item', () => {
    const cart = new Cart();
    cart.addItem({ id: 'book-1', name: 'TypeScript 入门', price: 59 });
    expect(cart.items).toHaveLength(1);
  });
});

// cart.ts — implémentation minimale pour faire passer le test
export interface CartItem {
  id: string;
  name: string;
  price: number;
}

export class Cart {
  items: CartItem[] = [];

  addItem(item: CartItem) {
    this.items.push(item);
  }
}

// Deuxième manche : tester « le panier calcule le prix total »
it('calculates total price', () => {
  const cart = new Cart();
  cart.addItem({ id: 'book-1', name: 'TypeScript 入门', price: 59 });
  cart.addItem({ id: 'book-2', name: 'React 实战', price: 79 });
  expect(cart.totalPrice()).toBe(138);
});

// cart.ts — ajout de la méthode totalPrice
export class Cart {
  items: CartItem[] = [];

  addItem(item: CartItem) {
    this.items.push(item);
  }

  totalPrice(): number {
    return this.items.reduce((sum, item) => sum + item.price, 0);
  }
}

Chaque manche suit : test échoue → code minimal passe → manche suivante. C’est le rythme central des tranches verticales.

Étape 5 : Utiliser /diagnose pour un débogage structuré

Quand le code a un problème, ne demandez pas directement à l’IA de « corriger le bug ». Commencez par construire une boucle de feedback, en exécutant :

/diagnose

/diagnose force l’IA à suivre une boucle de débogage en six étapes :

Pourquoi ce processus est-il important ? Parce que la méthode de débogage la plus courante chez l’IA consiste à « deviner, modifier, vérifier le résultat ; si ce n’est pas bon, deviner encore ». Sans boucle de feedback, cela revient à lancer des fléchettes dans le noir. /diagnose transforme le débogage en une discipline d’ingénierie, pas en magie.

Un scénario typique : supposons que votre interface de paiement commence soudainement à renvoyer une erreur 500 :

// Étape 1 : construire une boucle de feedback — écrire un test de défaillance pour identifier l’API concernée
import { describe, it, expect } from 'vitest';
import { createHonoServer } from './server';
import fetch from 'node-fetch';

describe('Payment API', () => {
  it('returns 200 for valid checkout', async () => {
    const app = createHonoServer();
    const response = await fetch('http://localhost:3000/api/checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        items: [{ id: 'book-1', quantity: 1 }],
        userId: 'user-123',
      }),
    });
    expect(response.status).toBe(200); // pour l’instant : échoue, car la réponse réelle est 500
  });
});

À l’étape 3, l’IA génère une liste d’hypothèses :

1. Si « le service d’inventaire time-out entraîne une exception non interceptée », alors un mock du service d’inventaire en succès fera disparaître le 500
2. Si « la transaction de base de données n’a pas été committée », alors vérifier l’appel à transaction.commit() montrera le problème
3. Si « l’erreur vient d’un parsing de format renvoyé par le gateway de paiement », alors valider le format des données mock du gateway permettra de reproduire le souci

L’IA vérifie une hypothèse à la fois, sans entasser toutes les modifications en même temps.

Étape 6 : Utiliser /write-a-skill pour construire une Skill personnalisée

Quand vous avez accumulé dans un projet une série de workflow spécifiques, vous pouvez les emballer sous forme de Skill pour que l’IA puisse l’appeler à tout moment dans ce projet :

/write-a-skill

L’IA vous posera successivement :

1. Quel domaine cette Skill couvre-t-elle ?
2. Quels sont les scénarios d’usage concrets ?
3. Faut-il fournir des scripts ou de simples instructions suffisent ?
4. Y a-t-il du matériel de référence ?

Puis elle génère une structure standard :

my-custom-skill/
├── SKILL.md              # Fichier de commande principal (obligatoire)
├── REFERENCE.md          # Documentation détaillée (si le contenu dépasse 100 lignes, la diviser)
├── EXAMPLES.md           # Exemples d’utilisation
└── scripts/
    └── helper.ts         # Script utilitaire (optionnel)

Le champ description de SKILL.md est l’unique point d’entrée que l’IA utilise pour percevoir cette Skill ; il y a des exigences strictes de format :

---
name: my-custom-skill
description: De générer des clients d’API sûrs en types à partir d’un JSON Schema, et d’y injecter des données Mock.
              Use when user mentions "API client", "generate types", or "mock data".
---

La première phrase du description dit « ce qu’elle fait », la deuxième dit « dans quel scénario elle se déclenche », et des mots déclencheurs guident l’IA pour le chargement automatique.

Dépannage des problèmes fréquents

1. L’IA n’exécute pas les tests et écrit directement du code

Symptôme : vous appelez /tdd, mais l’IA passe directement à l’implémentation, en sautant la phase ROUGE.

Dépannage :

• Vérifiez que CONTEXT.md a bien défini le framework de tests du projet ainsi que les conventions de test
• Au début de /tdd, précisez clairement « écrire un seul test, ne pas écrire d’autre code »
• Si l’IA saute encore, incitez-la à revenir en ROUGE en saisissant manuellement dans la conversation : « d’abord écrire un test qui échoue »

Cause racine : compréhension littérale du concept TDD par l’IA : elle considère que « écrire des tests » suffit pour faire du TDD ; elle ne comprend pas que « tester en échouant » lui-même est un signal.

---

2. Piège des tranches horizontales — écrire tous les tests en une fois

Symptôme : l’IA génère d’un coup 10 fichiers de tests dans /tdd, puis écrit ensuite toutes les implémentations d’un coup.

Dépannage :

• Intervention directe : dites à l’IA « n’écrire que le premier test, puis l’implémenter »
• Dans CONTEXT.md, ajoutez un avertissement contre les anti-patterns : « interdiction des tranches horizontales : à chaque fois, une seule tranche verticale »

Cause racine : l’IA aime l’illusion du « tout faire d’un coup » ; les tranches horizontales lui donnent l’impression d’avoir une vue complète, mais produisent en réalité quelque chose de fragile.

---

3. La boucle de débogage n’a pas de signal de feedback

Symptôme : vous appelez /diagnose, mais l’IA modifie seulement le code à répétition, sans établir un signal d’échec reproductible.

Dépannage :

• Phase 1 échoue : ne passez pas à la Phase 2. Dites explicitement à l’IA : « il n’y a pas encore de signal d’échec reproductible ; continuez à construire la boucle de feedback »
• Essayez d’utiliser node-fetch et de vraies requêtes HTTP pour construire un signal de bout en bout, plutôt que de tout masquer avec des mocks

Cause racine : la boucle de feedback est le cœur du débogage ; sans elle, toutes les actions suivantes sont des mouvements à l’aveugle.

---

4. Le descriptif de la Skill ne fonctionne pas — la Skill n’est pas déclenchée automatiquement

Symptôme : vous avez écrit une Skill personnalisée, mais l’IA ne la charge pas.

Dépannage :

• Vérifiez que le plugin.json a bien enregistré cette Skill
• Confirmez que le description contient des mots déclencheurs (des termes que l’utilisateur prononcera réellement)
• Vérifiez que le name et le format du description dans SKILL.md respectent les exigences (frontmatter YAML)

Cause racine : le chargement des Skills dépend du matching des mots-clés dans le description ; si la description n’est pas assez précise, la Skill ne se déclenche pas.

---

5. L’entretien /grill-me devient un rapport à sens unique

Symptôme : quand vous exécutez /grill-me, l’IA ne fait que recevoir vos informations, sans poser de questions proactives.

Dépannage :

• L’IA explique qu’elle est passée en mode entretien uniquement quand vous voyez qu’elle pose des questions : continuez à répondre, ne coupez pas
• Si l’IA se tait pendant plus de 3 tours, dites manuellement : « continue à me poser des questions, j’ai encore plus d’infos »
• La cause vient généralement du fait que l’IA pense avoir « compris », alors qu’elle n’a compris que littéralement

Cause racine : l’IA a tendance à converger rapidement vers un état « ça ressemble à une compréhension », plutôt que d’explorer toutes les branches.

---

6. CONTEXT.md trop volumineux provoque une explosion de tokens

Symptôme : à mesure que le projet avance, CONTEXT.md grossit de plus en plus ; l’IA commence alors à dépasser le contexte ou à répondre plus lentement.

Dépannage :

• Refactoriser régulièrement CONTEXT.md : conserver les « termes universels déjà stabilisés », et déplacer les « notes de décisions temporaires » vers le répertoire docs/adr/
• /improve-codebase-architecture peut aider à identifier ce qui devrait être extrait de CONTEXT.md

Cause racine : CONTEXT.md est un fichier qui grossit dynamiquement ; sans maintenance, il devient un deuxième monorepo.

Lecture complémentaire / pistes d’approfondissement

Extension de la méthodologie : Matt Pocock, lui-même, est un fervent défenseur du « TypeScript en type gymnastics » ; son cours Total TypeScript est une excellente extension pour comprendre le développement piloté par les types.

Du TDD à l’amélioration d’architecture : après plusieurs cycles de refactoring en TDD, vous pouvez utiliser /improve-codebase-architecture pour un diagnostic d’architecture. Il s’appuie sur le langage de domaine dans CONTEXT.md et sur les enregistrements de décisions dans docs/adr/ pour identifier les « modules superficiels » (interfaces complexes, mais peu de fonctionnalités) ainsi que les opportunités de refactoring.

Écosystème de Skills personnalisées : la philosophie de conception de mattpocock/skills est « petit et composable ». Vous n’avez pas forcément besoin d’installer toutes les Skills fournies : vous pouvez installer uniquement /tdd et /diagnose, puis introduire progressivement ces pratiques au quotidien. Dans la communauté, d’autres développeurs ont aussi construit des ensembles de Skills à partir de ce framework : cela vaut le coup de s’y intéresser.