De l'idée au Plugin : comment rétro-documenter son application

L'une des plus grandes problématiques que chaque développeur rencontre concerne la documentation. La mettre en place est chronophage et ce n'est pas intéressant, la maintenir, c'est encore pire !

Avec l'avènement de l'IA et la possibilité d'automatiser des tâches en langage naturel, n'est-ce pas l'occasion de casser cette problématique pour ne plus avoir à se soucier de la documentation ? Et si l'on pouvait passer d'un repository obscur à un écosystème parfaitement documenté, de manière autonome et standardisée ?

C'est dans cet intérêt que j'ai commencé à explorer la rétro-documentation par IA et que j'ai de façon itérative réalisé un plugin GitHub Copilot. Je vous partage ici mon aventure.

Contexte

Cette aventure a pris place lors d'une mission chez un client. Nous travaillions sur un projet avec une architecture en micro-service dont l'objectif était la génération de PDF. Le projet avait déjà quelques années, plusieurs équipes étaient passées dessus, il y a eu des changements d'outils... En bref, la documentation était explosée sur différents supports, certains morceaux n'étaient plus à jour, des liens morts, etc.

Difficile pour les nouveaux arrivants de comprendre l'environnement, quelle documentation fait encore foi et surtout où regarder. Autre problématique, comment maintenir une documentation technique et une documentation fonctionnelle alignées et à jour ?

À notre arrivée sur le projet, nous avons commencé à mettre en place une documentation technique via Antora au format AsciiDoc. Chaque repository contient sa propre documentation qui est ensuite centralisée sur un seul et même repository spécialisé pour la documentation. Ce dernier compile la documentation et publie un site sur GitHub Pages.

Phase 1 : L'approche empirique - L'itération sur les prompts

Avec l'ensemble de la documentation à maintenir sur une dizaine de micro-services, des personnes non techniques avec des questions régulières sur certaines règles, il était nécessaire de trouver une solution pour produire et maintenir de la documentation. La source de vérité étant le code, quoi de mieux que de générer la documentation à partir du code ?

La première phase a donc été d'expérimenter sur un repository avec des prompts ciblés du type :

Tu es un ingénieur logiciel devant effectuer de la rétro-documentation. En te basant sur le code et le paramétrage du repository, génère de la documentation au format AsciiDoc couvrant les points suivants :
- Vue globale technique du projet
- Installation et configuration
- Principaux cas d'utilisation
- Règles fonctionnelles
...

La documentation générée par un modèle du type Sonnet 4.5 permettait d'avoir une bonne base mais avoir tout d'un seul coup n'était pas une bonne idée, surtout lorsqu'on attaque un repository assez complexe.

Une deuxième phase a donc été de découper le prompt en plusieurs petits prompts pour générer chaque page de documentation de façon indépendante.
Ce faisant, le contexte était réduit et donc la qualité de la documentation produite se trouvait augmentée.

Cette phase a permis de trouver quels étaient les points importants pour la génération de notre documentation : le format, la structure, les points à couvrir, concentrer la génération sur un seul point à la fois, etc.
Cependant certains points n'étaient pas couverts : la structure interne de chaque fichier de documentation n'était pas consistante, la répétitivité de la tâche de génération, la perte de contexte.

Phase 2 : Standardisation - Création d'un skill local

Pour régler la problématique de consistance, quoi de mieux que d'utiliser des templates ?
Il est donc nécessaire de se tourner vers les skills !

Grâce à la documentation générée lors de la phase 1, le fichier SKILL.md a déjà de la matière. Avec l'aide de Copilot, nous avons généré une structure de fichier permettant de couvrir l'ensemble de nos besoins en documentation (technique, système et fonctionnelle). Pour chaque groupe, des fichiers spécialisés ont été définis.

Le skill décrit le rôle de chaque fichier, ce qu'il doit contenir comme information dans les grandes lignes et le lien vers le template.

Le skill est donc structuré ainsi :

.github/
  skills/
    my-skill
      SKILL.md
      templates
        1-technical
          code-structure.adoc
          configuration.adoc
          technical-overview.adoc
        2-system
          architecture-context.adoc
          workflows.adoc
          ...

Un fichier template contient la structure attendue avec des instructions pour définir ce qui est attendu auprès de l'IA. Par exemple pour code-structure.adoc :

= Code Structure & Architecture
:toc:
[AI INSTRUCTION: Scan the primary source directory (e.g., src/main/java/..., src/, or app/). Identify the internal architectural pattern by looking at package/folder names (e.g., controllers, services, repositories indicates Layered/MVC; domain, application, infrastructure, adapters indicates Clean/Hexagonal architecture). Do NOT list every single file. Focus only on the high-level package/folder structure.]

== Architectural Pattern
[AI INSTRUCTION: State the identified architectural pattern and provide a brief 1-2 sentence explanation of how it is applied in this specific codebase.]

Pattern Identified: [e.g., Hexagonal Architecture (Ports and Adapters) / Layered MVC / Domain-Driven Design]

Nous avons précisé dans le skill le fait de générer la documentation dans un ordre prédéfini : technique puis système et enfin fonctionnelle. En forçant cet ordre et en demandant à réutiliser les données trouvées dans les étapes précédentes, on évite de parcourir à nouveau l'intégralité du repository à la recherche d'informations, on construit une sorte de mémoire que notre agent enrichit.

Ce skill nous permet donc d'avoir une cohérence de structure globale de documentation mais aussi à l'intérieur de chaque document. Ceci nous ouvre la possibilité d'étendre notre travail aux autres projets.

Phase 3 : Partage et industrialisation - Création d'un repo dédié

Avoir le skill fonctionnant sur un projet est une bonne étape mais le faire fonctionner sur l'ensemble de nos projets c'est encore mieux !
On ne veut pas avoir à copier le dossier skills sur chacun de nos projets, ce n'est pas maintenable. Comme pour tout en informatique, une fois que l'on a quelque chose qui fonctionne et que l'on veut le réutiliser ailleurs, on l'extrait pour le mettre en commun.

Pour ce faire, nous avons créé un nouveau projet qui a pour vocation de contenir tous les skills qui seront utilisés par l'équipe.
La structure du projet correspond à ce que nous avions dans le projet source :

skills/
  my-skill
    SKILL.md
    templates
      1-technical
        code-structure.adoc
        ...

Lors de ce passage en commun un point important a été soulevé et qui n'avait pas été rencontré jusqu'à présent : les différents états d'un projet sur la documentation. Le skill était utilisé de façon itérative sur un seul projet dont la documentation s'enrichissait puis est devenue complète. Il nous a donc fallu distinguer 4 phases d'un projet et ajouter au skill une étape initiale de détermination de la phase actuelle du projet.
Les 4 phases identifiées sont :
- Projet vierge de documentation
- Documentation en cours
- Documentation terminée
- Projet avec documentation manuelle / legacy

Un inconvénient à cette solution de projet contenant directement les skills concerne son installation.
Il est nécessaire d'exécuter les commandes suivantes pour chaque projet sur lequels on souhaite utiliser les skills :

gh skill install my-project/my-skills my-skill
git add .github/skills
git commit -m "Add my skill"

Le skill est donc ajouté dans les sources du projet. Même s'il peut être installé et mis à jour par simple ligne de commande, cette solution est difficilement maintenable. L'alternative est d'installer le skill pour l'utilisateur (et non pas un projet), mais pour l'évolution du projet il est plus simple de créer un plugin.

Phase 4 : L'aboutissement - Création d'un plugin

Si le repository partagé de la Phase 3 résolvait notre problème de centralisation, l'obligation de lancer des lignes de commande pour l'installer sur chaque projet montrait les limites du système. Il fallait passer à l'étape supérieure.

Mais techniquement, quelle est la différence ?
Là où un Skill se comporte comme un "super-prompt" structuré exécuté localement, un Plugin Copilot est une véritable extension intégrée. Il offre une distribution simplifiée, mais permet surtout d'aller beaucoup plus loin avec la possibilité d'embarquer des Agents autonomes, capables d'interagir entre eux avec des rôles précis.
La bascule de ce simple "dossier de prompts" à une véritable "unité de distribution versionnée" a donc été le tournant majeur du projet.

Nous avons commencé par restructurer notre dossier pour coller aux standards d'un plugin Copilot et obtenir l'architecture suivante :

.github/
  plugin/
    marketplace.json
my-plugin/
  plugin.json
  skills/
    my-skill/
      SKILL.md
      references/
      templates/
  agents/
    my-explorer.agent.md
    my-writer.agent.md

Les éléments importants sont :

la définition de la marketplace (marketplace.json)
la définition du plugin (plugin.json)
la structure du plugin (agents, skills)

La marketplace

La marketplace permet de définir le repository comme une source de plugin. Cela va permettre de distribuer les plugins facilement en ligne de commande :

#Add the markeplace
copilot plugin marketplace add my-org/my-project
#Install the plugin
copilot plugin install my-plugin@my-marketplace
#Update the plugins from the marketplace
copilot plugin marketplace update my-marketplace

Pour ce faire, il suffit d'ajouter le fichier marketplace.json dans le dossier .github à la racine du projet. Le fichier doit contenir le nom de la marketplace, les plugins qu'il contient, etc.

Le plugin

Le plugin permet de définir les skills et les agents contenus ainsi que la version actuelle.

Ce groupement permet d'embarquer à la fois notre skill mais aussi des agents avec des outils et des rôles bien précis.
Dans notre cas de rétro-documentation, nous avons embarqué 2 agents spécialisés dans le plugin : un agent lecteur qui analyse la codebase et un agent scribe qui va générer la documentation à partir de l'analyse du lecteur.
Cette structure nous permet donc de scinder les rôles des agents et de les mettre à disposition avec le skill.

Bilan

Au-delà de l'exercice technique qu'a représenté la création de ce plugin, la vraie réussite se mesure à son adoption. Les retours de l'équipe sont positifs. La friction associée à la tâche de documenter a presque disparu : au lieu de repousser la rédaction, la génération de la doc fait désormais partie du flux de travail naturel. L'IA ne remplace pas l'expertise du développeur, mais elle agit comme un copilote particulièrement zélé qui fait le gros œuvre. Le développeur reprend son rôle de validateur, ce qui améliore considérablement l'expérience développeur globale sur le projet.

La prochaine étape de ce projet ? L'automatisation de la mise à jour par des workflows agentic !

Conclusion et perspectives

Le sujet de rétro-documentation peut toucher tous les projets, qu'ils soient legacy ou actuels, la documentation est un élément crucial de la vie d'un projet.
L'utilisation de l'IA pour générer cette documentation est un parfait cas d'usage pour mettre le pied à l'étrier.

Enfin pour finir, voici quelques recommandations que j'ai pu noter lors de cette aventure :

Relisez toujours ce qui est produit par l'IA (on ne le dit jamais assez)
Approchez votre problème par étapes, n'essayez pas de one-shot, construisez de façon itérative
Si votre skill produit des ressources (type document), précisez à vos agents (dans vos AGENTS.md, CLAUDE.md, etc.) de réutiliser cette documentation lorsqu'elle est présente
Si votre skill suit un cycle de vie, pensez aux différents états d'un projet (greenfield, brownfield, en cours, etc.)
Lorsque votre skill devient trop gros, découpez votre SKILL.md pour n'être plus qu'un point d'entrée (un routeur) lui précisant de charger une référence dédiée en fonction de votre logique (état du projet par exemple). Cela permettra d'économiser du contexte
Utilisez les templates pour de la cohérence de structure et ainsi augmenter la prédictibilité de vos sorties
Forcez la limitation de périmètre d'analyse et de génération. Limitez par exemple la génération de la documentation à une seule page ou un seul principe à la fois. Vous pouvez en profiter pour préciser ici de réutiliser la documentation précédemment générée comme point d'entrée.