Opus 4.7 est sorti hier jeudi 16 avril 2026. Parmi les cas d’usage qui profitent discrètement de la release, la génération de documentation technique mérite qu’on s’y attarde. La doc est un chantier chronique dans la plupart des équipes tech : tout le monde sait qu’il faut la maintenir, peu prennent le temps. 4.7 change la donne parce qu’elle produit de la doc utile en un tiers du temps manuel.

Les trois niveaux de documentation à couvrir

Avant de parler de méthode, identifions les trois niveaux que toute codebase devrait documenter.

Le niveau ligne. Commentaires inline qui expliquent “pourquoi” (pas “quoi”). Le bon commentaire explique une décision non triviale, pas ce que le code fait lisiblement.

Le niveau module. Docstring de chaque fonction publique, README de chaque package, explication des responsabilités et des dépendances.

Le niveau architecture. Vue d’ensemble du système, schémas d’interaction, décisions architecturales (ADR), runbooks opérationnels.

4.7 est bien équipé pour les trois niveaux. Le workflow varie selon le niveau visé.

Niveau ligne : les commentaires inline

Mauvaise pratique : demander à Claude de commenter chaque ligne d’un fichier. Tu obtiens des commentaires ”// incrémente x” qui ajoutent du bruit sans valeur.

Bonne pratique : donner à Claude le fichier et lui demander d’identifier les 5 à 10 endroits où un commentaire apporterait vraiment de la valeur. Le prompt : “Lis ce fichier. Identifie les zones où un commentaire explique une décision non évidente, un contournement, ou un invariant. Ne commente pas le reste.”

4.7 produit une liste réduite et pertinente. Tu valides, tu intègres.

Niveau module : les docstrings

Pour générer des docstrings sur un fichier entier, le prompt type : “Pour chaque fonction publique de ce fichier, génère une docstring au format [Google/NumPy/JSDoc/etc.]. Inclus la description, les paramètres, la valeur de retour, les exceptions possibles, et un exemple d’usage.”

4.7 produit les docstrings en une passe. Tu vérifies quelques exemples pour t’assurer que les exemples compilent (parfois le modèle utilise des valeurs qui ne correspondent pas à la réelle signature). Tu intègres.

Sur un fichier de 15-20 fonctions, compte 3-5 minutes pour obtenir une doc complète.

Niveau architecture : les ADR et runbooks

C’est là que 4.7 apporte le gain le plus spectaculaire. Avant, rédiger un ADR (architecture decision record) ou un runbook demandait d’écrire un texte structuré de plusieurs pages. Le temps nécessaire empêchait beaucoup d’équipes de le faire.

Workflow efficace : tu décris la décision en 5-10 bullet points dans un prompt. Tu demandes un ADR au format standard (context / decision / consequences / alternatives considered).

4.7 te rend un document d’1 à 2 pages, structuré, prêt à intégrer dans ton wiki. Tu révises, tu ajoutes les détails internes que le modèle ne pouvait pas deviner, tu publies.

Même pattern pour les runbooks opérationnels : tu donnes les étapes de diagnostic en vrac, tu obtiens un runbook formalisé avec sections “symptoms / diagnosis / remediation / escalation”.

Le pattern de doc “vivante”

Une approche que j’ai commencé à pratiquer avec 4.7 : la doc qui se régénère. Tu setups une commande (un script bash qui invoque Claude Code) qui, lancée sur un module, regénère la doc complète à partir du code source actuel.

Avantages : la doc reste synchronisée avec le code (il suffit de relancer le script après un refactor). Tu n’as pas à maintenir manuellement la doc.

Inconvénients : la doc régénérée écrase les ajouts humains manuels (contexte métier, choix historiques). Pour contourner, utilise un format qui sépare les sections “auto-générées” des sections “humaines” (par exemple un README structuré avec des balises <!-- auto:start --> ... <!-- auto:end --> qui indiquent les zones régénérables).

Ce que 4.7 change par rapport à 4.6

La densité de la doc générée. 4.7 produit une doc plus concise et plus utile. 4.6 avait tendance à sur-rédiger, avec des paragraphes creux. 4.7 est plus sec par défaut, ce qui convient parfaitement à la doc technique.

La cohérence inter-fichiers. Sur un package de 10 fichiers, 4.7 tient mieux la cohérence (vocabulaire, ton, exemples) que 4.6. Tu peux documenter tout un package en une session sans re-briefer à chaque fichier.

La qualité des exemples. Les exemples produits par 4.7 sont plus souvent exécutables sans correction. 4.6 produisait des exemples qui avaient parfois des erreurs de signature.

Les limites honnêtes

Le modèle ne connaît pas ton contexte métier. Il documente le code tel qu’il le voit, pas les raisons métier qui ont mené à cette implémentation. Pour les ADR, tu dois fournir ce contexte dans le prompt.

La doc peut dériver du code. Si tu génères la doc à un instant T et que le code évolue après, la doc reste fig. Les workflows de régénération aident mais demandent de la discipline.

Les exemples dans les docstrings doivent être vérifiés. Le modèle peut inventer des valeurs qui ne matchent pas la signature réelle. Un test de compile/run sur les exemples est indispensable avant publication.

FAQ

Quel format de docstring choisir ? Suivez la convention de votre projet. Google pour Python/C++, JSDoc pour JS/TS, OCamldoc pour OCaml, etc. 4.7 connaît tous les formats standards.

La doc générée par IA pose-t-elle un problème de licence ? Non pour du code que vous écrivez. La doc généré est votre propriété, comme le code associé.

Comment documenter un API public à forte audience ? Pour les API publiques, le workflow standard est : 4.7 génère une première version, un tech writer humain la révise et l’enrichit. Les deux en solo ne font pas aussi bien que le tandem.

---

Je dirige Linkuma, plateforme de netlinking low cost avec 40 000 sites au catalogue et 15 000 clients. On maintient une doc technique synchro grâce aux pipelines IA. Retours terrain sur linkuma.com, promos hebdo sur deals.linkuma.com.