Vibe coding — avancé

3.0Objectifs de la session

• Configurer un projet pour l'IA avec un CLAUDE.md efficace
• Déléguer des sous-tâches à des sous-agents et savoir quand le faire
• Brancher des outils externes via MCP (docs à jour, base de données, navigateur)
• Générer des tests utiles et mener une refacto multi-fichiers en confiance

3.1Donner le contexte projet : CLAUDE.md

Le CLAUDE.mdà la racine du repo est lu automatiquement au démarrage de chaque session. C'est le brief permanentde votre collègue IA : conventions, commandes, architecture. Ce que vous y écrivez, vous n'avez plus à le répéter dans chaque prompt.

# Mon projet — API de facturation

## Stack
TypeScript strict, Node 22, Fastify, Prisma + PostgreSQL, vitest.

## Commandes
- `npm run dev` — serveur local (port 3000)
- `npm test` — tests unitaires (vitest)
- `npm run lint` — ESLint + prettier check

## Architecture
- `src/routes/` — un fichier par ressource, schémas JSON à côté
- `src/services/` — logique métier, jamais d'accès HTTP direct
- `src/db/` — accès Prisma uniquement ici

## Conventions
- Pas de `any`. Erreurs typées via Result<T, E>.
- Tests obligatoires pour tout service ; nommage `*.spec.ts`.

Règles d'or

• Court— le fichier entre dans le contexte à chaque session : chaque ligne inutile coûte. Visez moins d'une page.
• Factuel — commandes exactes, chemins réels, contraintes vérifiables. Pas de vœux pieux (« code de qualité »).
• À jour— un CLAUDE.md périmé est pire qu'absent : le modèle suivra des instructions fausses avec assurance.

Le dossier .claude/ complète le dispositif : settings.json(permissions, outils autorisés) partagé via Git pour toute l'équipe, settings.local.json pour les réglages personnels.

3.2Agents et sous-agents

Un agent peut déléguer des sous-tâchesà d'autres agents : chacun part avec un contexte propre, travaille, et ne renvoie que sa conclusion. Le contexte principal reste léger.

Quand déléguer

• Exploration large— « où est gérée l'authentification dans ce repo ? » : le sous-agent lit vingt fichiers, vous ne recevez que la réponse.
• Tâches parallélisables — migrer 8 composants indépendants : un sous-agent par composant, en parallèle.
• Recherches jetables— comparer trois libs : les détails n'ont pas besoin de polluer votre session principale.

Quand rester inline

• Tâche courte et ciblée — un fichier connu, une fonction précise : déléguer coûte plus cher que faire.
• Décisions enchaînées — quand chaque étape dépend du résultat précédent et de votre validation.

3.3MCP : brancher des outils externes

Le Model Context Protocolest un standard ouvert pour connecter des outils au modèle. Un serveur MCP expose des capacités (lire une doc, interroger une base, piloter un navigateur) que l'agent peut appeler pendant la session.

Exemples concrets

• Docs à jour— un serveur type Context7 récupère la documentation actuelle d'une lib : fini les APIs hallucinées sur les versions récentes.
• Base de données — inspecter un schéma PostgreSQL réel avant de générer une migration Prisma.
• Navigateur — vérifier visuellement une page, lire la console, reproduire un bug front.
• Outils internes — votre API de tickets, votre CI : tout ce qui a une API peut devenir un serveur MCP.

3.4Skills & plugins : capitaliser le savoir-faire

Un skillest un dossier de consignes réutilisables que l'agent charge à la demande : une procédure de l'équipe (« comment on fait une migration DB », « notre checklist de release »), un domaine d'expertise, un format de livrable. Là où le CLAUDE.md dit ce qu'est le projet, un skill dit comment on fait telle tâche.

.claude/skills/
  release/
    SKILL.md        # procédure de release pas à pas
  migration-db/
    SKILL.md        # règles de migration + commandes
    verifier.sh     # script que l'agent peut exécuter

Invoqués explicitement (/release) ou automatiquement quand la tâche correspond. Les pluginsvont plus loin : ils packagent skills + serveurs MCP + agents + hooks en un ensemble installable et partageable — le moyen de diffuser les pratiques d'une équipe à toute l'organisation.

3.5Bosser en multi-agent

Au-delà du sous-agent ponctuel (vu en 3.2), on peut paralléliser le travail : plusieurs agents qui avancent en même temps sur des tâches indépendantes, pendant que vous orchestrez.

Les patterns qui marchent

• Fan-out exploration — 3-4 agents lisent chacun un sous-système, vous récupérez les synthèses. Comprendre une grosse codebase en minutes.
• Producteur / vérificateur— un agent implémente, un autre (contexte vierge, donc sans biais) relit et tente de casser. La review adversariale attrape ce que l'auteur ne voit plus.
• Travaux parallèles isolés — un agent par tâche indépendante, chacun dans son git worktree (copie isolée du repo) : pas de conflits de fichiers, chaque branche mergée séparément.
• Pipeline — découper une migration en lots, chaque lot traverse les mêmes étapes (transformer → tester → commit) sans attendre les autres.

Les règles qui évitent le chaos

• Tâches réellement indépendantes — deux agents sur les mêmes fichiers = conflits garantis. Découpez par périmètre.
• Consignes fermées — un agent parallèle ne peut pas vous poser de question en cours de route : critères de fin explicites dans le prompt.
• L'humain reste l'orchestrateur — vous validez chaque résultat avant merge. Multi-agent multiplie le débit, pas la confiance.
• Coût réel — chaque agent consomme des tokens. Paralléliser une tâche triviale coûte plus cher que la faire soi-même.

3.6Tests générés

L'IA écrit des tests vite et bien — à condition de cadrer. Deux stratégies : tests d'abord(vous validez le comportement attendu avant l'implémentation, excellent garde-fou) ou tests après (plus rapide, mais risque de tests qui entérinent les bugs existants).

Pièges à connaître

• Tests qui testent l'implémentation— mocks partout, assertions sur les appels internes : la refacto suivante casse tout sans qu'aucun bug n'existe. Exigez des tests de comportement.
• Assertions creuses — expect(result).toBeDefined() passe toujours. Relisez les assertions comme vous relisez le code.
• Cas limites oubliés — demandez-les explicitement : « ajoute les cas vide, null, unicode, très grand ».

La boucle rouge/vert assistée

1. Faire écrire les tests à partir de la spec — les lire, les valider
2. Lancer : ils doivent échouer (rouge) — sinon ils ne testent rien
3. Faire implémenter jusqu'au vert, sans toucher aux tests
4. Refacto libre : les tests protègent

3.7Gérer le contexte long

Une session qui s'éternise se dégrade : le contexte se remplit de tentatives ratées, de sorties de commandes et de pistes abandonnées. Le modèle finit par dériver — il mélange les consignes du début avec les contre-ordres du milieu.

• Compaction— résumer la session en cours pour repartir sur un contexte propre en gardant l'essentiel.
• Sessions fraîches — une tâche = une session. Terminé, commité ? Nouvelle session.
• Découper les grosses tâches— une refacto de 30 fichiers se planifie d'abord (liste écrite dans un fichier), puis s'exécute par lots vérifiables.

3.8TP de la session

Dossier exercices/session-3/ du repo. Au programme :

• TP1 — Écrire le CLAUDE.mddu repo d'exercices, le tester sur une tâche réelle, mesurer la différence avec/sans
• TP2 — Refacto multi-fichiers : extraire un service transverse, tests générés en garde-fou, boucle rouge/vert
• TP3 — Brancher un serveur MCP de documentation et régénérer un code qui hallucinait une API
• TP4 (bonus)— Créer un skill d'équipe, puis mener deux tâches en parallèle avec deux agents sur des périmètres étanches

3.9Checklist & quiz de validation

• J'ai écrit un CLAUDE.md court, factuel et vérifié sur une vraie tâche
• J'ai délégué une exploration à un sous-agent avec un brief autoportant
• J'ai branché un serveur MCP et constaté la différence sur une lib récente
• J'ai mené une boucle rouge/vert : tests validés, échec constaté, implémentation au vert
• Je sais reconnaître la dérive de contexte et repartir sur une session propre
• J'ai créé un skill qui capitalise une procédure de l'équipe
• J'ai fait travailler deux agents en parallèle sur des périmètres étanches

3.10Défi inter-session