Apprenez à utiliser Claude Code pour détecter la dérive de la documentation et garder les README, docs API et runbooks en accord avec le code en générant des diffs et en signalant les contradictions.
La dérive de la documentation est la séparation progressive entre ce que disent vos docs et ce que le code fait réellement. Ça commence par de petites différences, puis finit par des situations de type « on jure que ça marchait le mois dernier ».
Dans une équipe réelle, la dérive ressemble à ça : le README indique qu'on peut lancer un service avec une commande, mais une nouvelle variable d'environnement est désormais requise. La doc API montre un endpoint avec un champ renommé. Un runbook demande à l'on-call de redémarrer "worker-a", alors que le processus est maintenant réparti sur deux services.
La dérive arrive même avec de bonnes intentions parce que le logiciel change plus vite que les habitudes de documentation. Les gens livrent des correctifs sous pression, recopient d'anciens exemples ou supposent que quelqu'un d'autre mettra la doc à jour plus tard. Elle s'amplifie aussi quand il y a trop d'endroits qui semblent être la "source de vérité" : README, références API, pages wiki internes, tickets et connaissances de terrain.
Les coûts sont concrets :
Polir le texte n'efface pas la dérive si les faits sont faux. Ce qui aide, c'est de traiter la doc comme quelque chose que l'on peut vérifier : comparez-la au code actuel, aux configs et aux sorties réelles, puis signalez les contradictions quand la doc promet un comportement que le code n'a plus.
La dérive se manifeste souvent dans des documents considérés comme des "références rapides". Ils sont mis à jour une fois, puis le code continue d'évoluer. Commencez par ces trois types car ils contiennent des promesses concrètes que vous pouvez vérifier.
Les README dérivent quand les commandes quotidiennes changent. Un nouveau flag est ajouté, un ancien est supprimé, ou une variable d'environnement est renommée, mais la section d'installation montre encore l'ancienne réalité. Les nouveaux collègues copient-collent les instructions, rencontrent des erreurs et supposent que le projet est cassé.
La pire version est « presque correcte ». Une variable d'environnement manquante peut faire perdre plus de temps qu'un README totalement obsolète, parce que les gens essaient encore de petites variations au lieu de remettre en question la doc.
Les docs API dérivent quand les champs des requêtes ou réponses changent. Même de petits changements (champs renommés, valeurs par défaut différentes, nouveaux headers requis) peuvent casser des clients. Souvent, la liste des endpoints est correcte alors que les exemples sont faux, et ce sont précisément ces exemples que les utilisateurs copient.
Signaux typiques :
Les runbooks dérivent quand les étapes de déploiement, rollback ou opérationnelles changent. Une commande obsolète, un mauvais nom de service ou un prérequis manquant peut transformer une réparation de routine en panne.
Ils peuvent aussi être "exacts mais incomplets" : les étapes fonctionnent toujours, mais elles omettent une migration, un vidage de cache ou l'activation d'un flag. C'est là que les intervenants suivent parfaitement le runbook et se retrouvent quand même surpris.
Claude Code pour la dérive de la documentation fonctionne mieux si vous traitez les docs comme du code : proposez un petit patch révisable et expliquez pourquoi. Au lieu de lui demander de "mettre à jour le README", demandez-lui de générer un diff par rapport à des fichiers spécifiques. Les reviewers obtiennent un avant/après clair et repèrent plus vite les changements involontaires.
Une bonne vérification de dérive produit deux choses :
Quand vous prompt, exigez des preuves provenant du repo : chemins de fichiers et détails comme des routes, valeurs de config ou tests qui démontrent le comportement actuel.
Voici un modèle de prompt qui reste ancré :
Check these docs for drift: README.md, docs/api.md, runbooks/deploy.md.
Compare them to the current repo.
Output:
1) Contradictions list (doc claim -> repo evidence with file path and line range)
2) Unified diffs for the smallest safe edits
Rules: do not rewrite sections that are still accurate.
Si Claude affirme "l'API utilise /v2", il doit l'étayer en pointant vers le router, le spec OpenAPI ou un test d'intégration. S'il ne trouve pas de preuve, il doit le dire.
La dérive commence souvent par un changement de code qui affecte discrètement plusieurs docs. Faites d'abord analyser l'impact : qu'est-ce qui a changé, où, quelles docs sont probablement cassées et quelles actions utilisateurs sont affectées.
Exemple : vous renommez une variable d'environnement API_KEY en SERVICE_TOKEN. Un rapport utile retrouve tous les endroits où l'ancien nom apparaît (section d'installation du README, exemples API, section secrets du runbook), puis produit un diff serré qui met à jour uniquement ces lignes et les commandes d'exemple qui échoueraient désormais.
Si vous pointez un modèle vers "toutes les docs" sans règle, vous obtenez souvent une prose réécrite qui contient encore des faits faux. Un workflow simple maintient les changements petits, répétables et faciles à relire.
Commencez par un seul ensemble de docs : le README, la référence API, ou un runbook réellement utilisé. Corriger une zone de bout en bout vous apprend quels signaux faire confiance avant de monter en charge.
Écrivez clairement où doivent provenir les faits pour cet ensemble de docs.
Une fois ces sources nommées, les prompts sont plus précis : "Compare le README à la sortie d'aide CLI actuelle et aux valeurs par défaut de la config, puis génère un patch."
Mettez-vous d'accord sur un format de sortie avant la première vérification. Mélanger les formats rend plus difficile la compréhension des changements.
Règles simples :
Une habitude pratique : ajoutez une petite note à chaque PR de doc comme "Source of truth checked: routes + tests" pour que les reviewers sachent ce qui a été comparé. Ça transforme les mises à jour de docs de "ça a l'air bien" en "vérifié contre quelque chose de réel".
Traitez chaque changement de code comme une petite enquête sur la doc. Le but est de détecter tôt les contradictions et de produire un patch minimal que les reviewers peuvent approuver.
Commencez par choisir les fichiers exacts à vérifier et une question de dérive claire. Par exemple : "Avons-nous changé des variables d'environnement, des flags CLI, des routes HTTP ou des codes d'erreur que la doc mentionne encore ?" Être précis empêche le modèle de réécrire des sections entières.
Ensuite, demandez à Claude Code d'extraire d'abord les faits précis depuis le code. Demandez-lui d'énumérer uniquement des éléments concrets : commandes utilisateurs, endpoints et méthodes, champs de requête et de réponse, clés de config, variables d'environnement requises et étapes opérationnelles référencées par des scripts ou des configs. Si quelque chose n'apparaît pas dans le code, il doit répondre "not found" au lieu de deviner.
Puis demandez un tableau de comparaison simple : affirmation de la doc, ce que montre le code, et un statut (match, mismatch, missing, unclear). Ça maintient la discussion factuelle.
Après cela, demandez un diff unifié avec des modifications minimales. Indiquez-lui de ne changer que les lignes nécessaires pour résoudre les discordances, de conserver le style existant de la doc et d'éviter d'ajouter des promesses non soutenues par le code.
Terminez par un court résumé pour le reviewer : ce qui a changé, pourquoi, et ce qu'il faut vérifier (comme une variable renommée ou un header requis).
Les docs API dérivent quand le code change discrètement : une route est renommée, un champ devient requis, ou la forme d'une erreur change. Le résultat : des intégrations clientes cassées et du temps perdu à déboguer.
Avec Claude Code pour la dérive, la mission est de prouver ce que l'API fait depuis le repo, puis de pointer les discordances dans les docs. Demandez-lui d'extraire un inventaire depuis le routing et les handlers (chemins, méthodes, modèles de requête et de réponse) et de le comparer à ce que la référence API affirme.
Concentrez-vous sur ce que les gens copient-colle vraiment : commandes curl, headers, payloads d'exemple, codes de statut et noms de champs. Dans un seul prompt, faites vérifier :
Quand il trouve une discordance, n'acceptez que des diffs qu'il peut justifier par une preuve dans le code (la définition exacte de la route, le comportement du handler ou le schéma). Ça garde les patches petits et révisables.
Exemple : le code retourne maintenant 201 sur POST /widgets et ajoute un champ requis name. La doc montre encore 200 et omet name. Un bon résultat signale les deux contradictions et met à jour uniquement le code de statut et le JSON d'exemple de cet endpoint, en laissant le reste intact.
Les runbooks échouent de la façon la plus coûteuse : ils paraissent complets mais leurs étapes ne correspondent plus au fonctionnement actuel. Un petit changement comme une variable renommée ou une nouvelle commande de déploiement peut allonger un incident parce que les intervenants suivent des instructions inefficaces.
Traitez le runbook comme du code : demandez un diff par rapport au repo actuel et exigez des signalements de contradictions. Comparez-le à ce que le système utilise aujourd'hui : scripts, valeurs par défaut de config et outils en place.
Concentrez-vous sur les points de défaillance qui causent le plus de rebond en incident :
Ajoutez aussi des pré-vérifications rapides et des sorties attendues pour que les intervenants puissent savoir s'ils sont sur la bonne voie. "Vérifiez que ça marche" ne suffit pas ; incluez le signal exact attendu (une ligne d'état, une chaîne de version ou la réponse d'un health check).
Si vous construisez et déployez des apps sur des plateformes comme Koder.ai, cela compte d'autant plus car les snapshots et le rollback ne servent que si le runbook nomme la bonne action et reflète le chemin de récupération actuel.
La façon la plus rapide de créer de la dérive est de traiter la doc comme de la "belle prose" plutôt que comme un ensemble d'affirmations devant correspondre au code.
Une erreur fréquente est de demander d'abord une réécriture. Quand on saute l'étape de vérification des contradictions, on obtient parfois un texte plus fluide qui reste incorrect. Commencez toujours par demander ce que la doc affirme, ce que fait le code et où ils divergent.
Une autre erreur est de laisser le modèle deviner. Si un comportement n'est pas visible dans le code, les tests ou les configs, considérez-le comme inconnu. "Probablement" est la façon dont on invente des promesses dans les README et dont les runbooks deviennent de la fiction.
Ces problèmes se retrouvent souvent lors de mises à jour courantes :
Un handler change pour renvoyer 401 → 403 pour les tokens expirés, et le nom du header passe de X-Token à Authorization. Si vous ne réécrivez que la section auth, vous risquez d'oublier que l'exemple API montre toujours l'ancien header, et que le runbook demande à l'on-call de surveiller des pics de 401.
Quand vous générez des diffs, ajoutez une courte phrase de décision : "Les échecs d'auth retournent maintenant 403 pour distinguer credentials invalides vs manquants." Cela empêche la prochaine personne de "corriger" la doc en revenant à l'ancien comportement.
Traitez chaque mise à jour de doc comme un petit audit. L'objectif est qu'un lecteur n'ait pas de mauvaises surprises en suivant les instructions.
Avant de merger, parcourez le README, les docs API et le runbook pour repérer les affirmations concrètes et vérifiez-les une par une :
Si vous trouvez deux affirmations ou plus inconnues dans le même document, mettez la fusion en pause. Ajoutez soit des preuves (chemins de fichiers et noms de fonctions), soit réduisez la doc à ce qui est certain.
Une petite équipe met à jour l'auth : au lieu d'envoyer une clé API via X-API-Key, les clients envoient maintenant un token court via Authorization: Bearer <token>. Le code est livré, les tests passent, et l'équipe passe à autre chose.
Deux jours plus tard, un nouveau développeur suit le README. Il indique encore "set X-API-Key in your environment" et montre un exemple curl avec l'ancien header. Il n'arrive pas à faire marcher l'application localement et suppose que le service est en panne.
Pendant ce temps, la doc API est aussi obsolète. Elle décrit l'ancien header et montre toujours un champ de réponse user_id, alors que l'API renvoie désormais userId. Rien n'est mal écrit, mais cela contredit le code, donc les lecteurs copient le mauvais comportement.
Puis survient un incident. L'on-call suit l'étape du runbook "rotate the API key and restart workers". Ça n'aide pas parce que le vrai problème est la vérification du token après un changement de config. Le runbook les envoie dans la mauvaise direction pendant 20 minutes.
C'est là que Claude Code pour la dérive est utile quand il produit des diffs et des signalements de contradictions, pas une réécriture complète. Vous pouvez lui demander de comparer le middleware d'auth et les handlers aux extraits du README, aux exemples API et aux étapes du runbook, puis de proposer des patches minimaux :
- Header: X-API-Key: <key>
+ Header: Authorization: Bearer <token>
- { "user_id": "..." }
+ { "userId": "..." }
L'important est qu'il signale les discordances, pointe les emplacements exacts et ne change que ce que le repo prouve être obsolète.
La documentation reste exacte quand sa vérification devient ennuyeuse et répétable. Choisissez une cadence qui correspond au risque de vos changements. Pour du code très actif, faites-le à chaque PR. Pour des services stables, un balayage hebdomadaire plus une vérification avant release suffisent souvent.
Traitez la dérive de doc comme une alarme de test, pas comme une tâche d'écriture. Utilisez Claude Code pour générer un petit diff et une courte liste de contradictions, puis corrigez la plus petite chose qui rend la doc vraie à nouveau.
Une routine légère :
Rendez ces résumés de diff faciles à retrouver plus tard. Une petite note comme "Docs mises à jour pour correspondre au nouveau endpoint /v2, header déprécié retiré, réponse d'exemple mise à jour" aide quand quelqu'un demande des mois plus tard pourquoi une doc a changé.
Appliquez la logique "snapshots et rollback" aux docs aussi. Si une instruction est incertaine, changez-la à un seul endroit, vérifiez-la rapidement, puis copiez la version confirmée ailleurs.
Si vous développez rapidement, il peut être utile de générer l'app et une première version de sa doc ensemble sur Koder.ai (koder.ai), puis d'exporter le code source et de garder les changements révisables dans votre workflow habituel. Le but n'est pas une prose parfaite, mais d'aligner ce que font les gens (commandes, endpoints, étapes) avec ce que le code fait réellement.
La dérive de la documentation se produit quand vos docs cessent progressivement de correspondre à ce que le code fait réellement. Elle commence souvent par de petits changements (une variable d'environnement renommée, un champ devenu requis, un code de statut différent) qui ne sont jamais reportés dans le README, les exemples d'API ou les runbooks.
Parce que le code évolue sous pression et que la documentation n'a pas la même discipline.
Causes courantes :
Commencez par les documents que les gens exécutent réellement, pas ceux qui sont « sympas à avoir ». Ordre pratique :
Corriger ceux-ci en priorité réduit les échecs les plus coûteux.
Parce qu'une prose soignée peut rester fausse. La dérive concerne surtout des affirmations incorrectes.
Une meilleure approche consiste à traiter la doc comme des énoncés testables : « exécutez cette commande », « appelez cet endpoint », « définissez cette variable », puis vérifiez ces affirmations contre le repo, les configs et les sorties réelles.
Demandez deux sorties :
Exigez aussi que si l'outil ne trouve pas de preuve dans le repo, il indique « not found » plutôt que de deviner.
Parce que les reviewers valident un diff bien plus vite. Un diff montre exactement ce qui a changé et décourage les réécritures « aidantes » qui introduisent de nouvelles promesses.
Bon choix par défaut : un fichier par diff quand c'est possible, et chaque changement accompagné d'une phrase expliquant pourquoi, liée à une preuve dans le repo.
Exigez qu'il cite des preuves.
Règles pratiques :
Vérifiez les parties que les gens copient-collent :
Si la liste des endpoints est correcte mais que les exemples sont faux, les utilisateurs échouent toujours : traitez les exemples comme une priorité élevée.
Les runbooks dérivent quand la réalité opérationnelle change.
Contrôles à fort impact :
Sans moyen de vérifier l'avancement, les intervenants perdent du temps en incident.
Utilisez une règle simple de « source de vérité » par type de doc :
Puis intégrez ça au workflow : lancez des vérifications de dérive sur les docs affectées à chaque PR, et gardez les modifications petites et révues.