Claude Code pour la dérive de la documentation : garder la documentation alignée

Qu'est-ce que la dérive de la documentation (et pourquoi ça continue d'arriver)

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 :

• L'onboarding casse (les nouveaux perdent des jours à régler l'environnement).
• Les déploiements échouent (les étapes ne correspondent pas à la config actuelle).
• La charge de support augmente (les utilisateurs suivent des instructions obsolètes).
• Les incidents s'allongent (les runbooks envoient les intervenants dans la mauvaise direction).

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.

Où la dérive apparaît : README, docs API et runbooks

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.

README : le premier endroit où les utilisateurs souffrent

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.

Docs API : schémas décalés et exemples trompeurs

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 payloads d'exemple contiennent des champs que le serveur n'accepte plus.
• Les exemples de réponse montrent d'anciens formats d'erreur ou codes de statut.
• Les tableaux de paramètres qualifient des champs d'optionnels alors qu'ils sont désormais requis.
• Les notes d'auth mentionnent des headers ou des scopes obsolètes.
• La pagination, le tri ou les règles de filtrage ne correspondent pas à la réalité.

Runbooks : dérive silencieuse qui provoque des incidents bruyants

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.

Comment utiliser Claude Code : diffs et signalements de contradictions

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 :

1. Un diff minimal
2. Un rapport de contradictions franc et spécifique : "La doc dit X, le repo montre Y."

Demander des preuves, pas des opinions

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.

Définir l'étendue du changement avant d'éditer

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.

Mettre en place un workflow simple avant tout prompt

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.

Décidez ce qui fait office de source de vérité

Écrivez clairement où doivent provenir les faits pour cet ensemble de docs.

• Pour un README : la sortie d'aide CLI et une application exemple fonctionnelle.
• Pour les docs API : les définitions de routeur et les tests d'intégration.
• Pour les runbooks : la config de déploiement et les alertes qui déclenchent la procédure.

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."

Choisissez une sortie que les reviewers peuvent valider rapidement

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 :

• Exigez un diff pour chaque modification de doc, plus une raison d'une phrase.
• Autorisez une courte liste de contradictions seulement quand l'outil ne peut pas proposer de formulation sûre.
• Gardez les diffs limités à un fichier par changement quand c'est possible.
• Traitez les exemples qui échouent (commandes, requêtes, extraits de code) comme prioritaires par rapport au style général.

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".

Étape par étape : garder les docs alignées avec le code à chaque changement

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).

Docs API : une manière pratique de vérifier les endpoints et les exemples

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 :

• Les exigences d'auth (headers, type de token, endpoints publics)
• Les paramètres de pagination et valeurs par défaut
• Les codes d'erreur et le format JSON
• Le comportement de versioning (v1 vs v2)
• Si les exemples correspondent aux règles de validation actuelles

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.

Runbooks : réduire les pannes causées par des procédures obsolètes

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 :

• Les commandes listées correspondent-elles aux scripts et flags actuels ?
• Les valeurs de config "par défaut" correspondent-elles à ce que l'app embarque aujourd'hui ?
• Les variables d'environnement et secrets requis sont-ils référencés par le code et la config de déploiement ?
• Les étapes de déploiement et de rollback correspondent-elles à votre tooling de release actuel ?
• Les valeurs "connues bonnes" (ports, régions, timeouts) correspondent-elles toujours à la réalité ?

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.

Erreurs communes qui aggravent la dérive

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.

Erreurs qui cassent silencieusement l'alignement

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 :

• Mettre à jour une section mais laisser les exemples, messages d'erreur et cas limites inchangés
• Renommer un concept dans un endroit (README) mais pas dans la doc API, les clés de config ou les runbooks
• Corriger la description d'un endpoint mais oublier les exemples de requête/réponse
• Changer un comportement sans mettre à jour les valeurs par défaut ou les notes sur les limitations
• Fusionner des modifications de docs sans une courte note "pourquoi ça a changé" dans le résumé du diff

Un petit exemple

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.

Checklist rapide avant de merger une mise à jour de doc

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.

Cinq vérifications qui attrapent la plupart des dérives

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 :

• Surlignez chaque affirmation contenant une commande, un endpoint, une clé de config, une variable d'environnement, un port ou un payload d'exemple.
• Pour chaque affirmation, notez le fichier exact qui la prouve (source, config, schéma, migration, test ou sortie d'aide CLI). Si vous ne trouvez pas la preuve rapidement, marquez-la comme inconnue plutôt que de deviner.
• Demandez un diff minimal uniquement là où une preuve existe. Si une affirmation est inconnue, la modification devrait devenir une question ou un TODO, pas une assertion confiante.
• Sanity-checkez les exemples : les entrées correspondent-elles toujours à ce que le code accepte aujourd'hui (noms de paramètres, champs requis, headers, valeurs par défaut) ? Les exemples longs attirent la dérive.
• Pour les runbooks, confirmez que les étapes couvrent les pannes probables, le rollback sûr et comment vérifier la récupération.

Une règle d'arrêt rapide

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.

Scénario exemple : un changement de fonctionnalité, trois docs qui dérivent

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.

Prochaines étapes : transformer les vérifications de dérive en routine

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 :

• Par PR : lancez une vérification de dérive sur les fichiers que le changement peut affecter (README, docs API, runbooks).
• Sauvegardez le résumé du diff dans la description de la PR ou les notes de revue pour que les reviewers voient ce qui a changé et pourquoi.
• Préférez des petites modifications réversibles plutôt que de grosses réécritures.
• Avant les releases : re-vérifiez tout ce que les utilisateurs copieront-coller (exemples curl, variables d'environnement, étapes de déploiement).
• Hebdomadaire : prenez un ou deux runbooks anciens et confirmez qu'ils correspondent toujours aux commandes et tableaux de bord d'aujourd'hui.

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.