La documentation vivante : un Skill Claude qui se met à jour tout seul
Nous connaissons tous cette situation : un nouveau développeur arrive sur le projet, ouvre la documentation du composant le plus critique du système d'information, et découvre qu'elle date de 18 mois.
Sur une mission récente, un composant métier stratégique évoluait à chaque sprint. La documentation, elle, ne suivait jamais. Le problème n'était pas la volonté de l'équipe, mais le coût de la mise à jour manuelle : personne n'avait le temps de la refaire à chaque changement, et la refaire en fin de sprint arrivait toujours trop tard, une fois le contexte déjà oublié.
Créer un Skill de documentation vivante
J'ai créé un Skill Claude de living documentation : une documentation
générée et rafraîchie automatiquement à partir du code réel. Pour le
construire, j'ai utilisé le skill-creator d'Anthropic, un skill dédié à la
création d'autres skills.
La démarche s'est faite en quatre étapes.
1. Définir le besoin
À chaque évolution du composant, régénérer une documentation qui décrit les règles métier, les flux, les contrats d'API et les invariants, en langage clair. L'objectif n'était pas de documenter le code ligne par ligne, mais de capturer l'intention métier que le code seul ne rend pas toujours visible.
2. Lancer skill-creator
En décrivant le workflow (quoi, quand déclencher, quelle sortie attendue),
skill-creator guide la génération de la structure complète : un fichier
SKILL.md avec les instructions et les déclencheurs, un dossier de scripts
pour l'extraction du code, un dossier de références pour les standards de
documentation de l'équipe.
3. Affiner le SKILL.md
C'est ici qu'on encapsule la connaissance métier : le vocabulaire du domaine (le langage ubiquitaire du DDD), les règles à toujours documenter, le format attendu (diagrammes, tableaux de décision, exemples). Cette étape a demandé plusieurs itérations : les premières versions généraient une documentation techniquement correcte mais peu lisible pour les Business Analysts, qui étaient pourtant le public principal visé.
Un extrait simplifié du SKILL.md obtenu ressemble à ceci :
---
name: living-documentation
description: Régénère la documentation métier d'un composant à partir du code réel
---
## Quand se déclencher
Sur demande explicite : "mets à jour la living documentation de <composant>"
## Étapes
1. Lire le code source du composant et son historique récent (git log)
2. Identifier les règles métier, invariants et contrats d'API
3. Comparer avec la documentation existante dans docs/<composant>.md
4. Proposer les sections à ajouter, modifier ou supprimer
5. Ne jamais documenter en jargon technique : le public est le Business Analyst
4. Utiliser au quotidien
Après chaque évolution significative, un simple prompt — « mets à jour la living documentation du composant X » — suffit. Claude relit le code, détecte les écarts avec la documentation existante, et propose la mise à jour en utilisant ce skill. L'équipe relit, valide, commit. Le coût marginal d'une mise à jour est passé de plusieurs heures à quelques minutes de revue.
Avant et après le skill
| Documentation manuelle | Skill de living documentation | |
|---|---|---|
| Déclencheur | Décision consciente de « prendre le temps » | Un prompt après chaque évolution significative |
| Coût par mise à jour | Plusieurs heures, souvent repoussées | Quelques minutes de relecture |
| Détection des écarts code/doc | Aucune, sauf relecture manuelle complète | Automatique, à chaque régénération |
| Public réel visé | Souvent des développeurs, par défaut | Business Analyst, contraint explicitement dans le SKILL.md |
La dernière ligne est celle qui a demandé le plus d'itérations : rien dans un skill ne garantit par défaut que la sortie vise le bon public, ça reste une instruction à formuler aussi explicitement que le reste du workflow.
Ce que ça change
Résultat : une documentation alignée sur le code, un onboarding accéléré, et des Business Analysts qui comprennent enfin ce que fait réellement le composant, sans devoir interrompre un développeur pour se le faire expliquer oralement à chaque fois.
Un effet secondaire inattendu : le simple fait de régénérer la documentation révèle parfois des incohérences dans le code lui-même, des cas où le comportement réel a dérivé du comportement voulu sans que personne ne s'en aperçoive. La documentation vivante n'est pas seulement un outil de communication, elle devient un outil de détection de dette silencieuse.
La leçon à en tirer : la living documentation n'est plus un fardeau. Avec les skills, elle devient un workflow concret et reproductible, à la portée de toute équipe. Que vous soyez junior ou architecte expérimenté, choisissez un composant critique et testez : le retour sur investissement se mesure dès le premier sprint.