IA agentique : comment nous maintenons notre documentation technique à jour

La plupart d'entre nous prenons des milliers de photos chaque année sans jamais prendre le temps d’en regarder la plupart. Popsa est là pour vous permettre d’identifier celles qui comptent vraiment pour vous et à les transformer en objets concrets que vous conserverez et prendrez plaisir à redécouvrir, encore et encore.

Nos applications mobiles embarquent des modèles de machine learning directement sur les appareils des utilisateurs, sans transfert vers le cloud. Elles analysent les photos, repèrent les visages et les moments significatifs, puis génèrent une mise en page qui raconte une histoire. Vu de l’extérieur, ça parait simple, et c’est précisément l’objectif.

En réalité, cette simplicité repose sur une architecture complexe : applications iOS, Android et web, services backend pour les règlements et la gestion des commandes, infrastructure dédiée au traitement et à la distribution des images dans plus de 50 pays. Ces systèmes traitent des données personnelles sensibles et des transactions financières. Ils doivent rester performants et sécurisés, et il est essentiel que l’équipe entretienne une compréhension claire et à jour de l’ensemble du système.

Cette compréhension repose sur une documentation qui décrit les interactions entre les systèmes, les conventions en place et les zones sensibles à surveiller. C’est ce qui permet à une équipe de maintenir, sécuriser et faire évoluer des systèmes complexes, sans dépendre d’une seule personne à l’origine de chaque élément. Mais maintenir cette documentation à jour est un réel défi auquel toutes les équipes d’ingénierie ont été confrontées à un moment ou à un autre –, la nôtre y compris !

J’ai travaillé au sein de suffisamment d’équipes d’ingénierie pour connaître ce cycle. À chaque fois, quelqu’un dit : « cette fois, on va vraiment tenir la doc tech à jour correctement ». S’ensuit un regain d’efforts : les pages se multiplient, les conventions sont consignées, les schémas d’architecture prennent forme. Parfois, les équipes vont même jusqu’à changer entièrement d’outil (GitHub, Confluence, Coda), insufflant un nouvel élan. Pendant quelques semaines, parfois quelques mois, tout est parfait.

Puis, ça se dégrade.

Non pas par manque d’attention, mais parce que l’évolution d’un logiciel n’est pas linéaire. On peut absorber des dizaines de changements progressifs sans que la documentation devienne désuète. Puis survient une refonte de la couche d’authentification, une migration vers un nouveau framework, ou une réorganisation d’API… La documentation était juste au moment où elle a été rédigée, mais le code, lui, a continué d’évoluer. Par exemple, nous venons de refondre notre application iOS, passant d’une navigation linéaire à une navigation par onglets. Après un changement d’une telle ampleur, des sections entières de documentation peuvent décrire un système qui n’existe plus. La documentation devient facilement obsolète.

La plupart des ingénieurs en sont conscients. C’est pourquoi notre équipe s’est récemment dit que pour résoudre ce problème il fallait considérer la documentation comme un système, plutôt que comme une simple tâche.

Un manque jamais vraiment comblé

Naturellement, d’autres ont déjà tenté d’y remédier. Des outils comme Javadoc, Swagger ou Doxygen génèrent automatiquement de la documentation à partir du code. Ils remplissent bien leur rôle – références d’API, signatures de fonctions, schémas d’endpoints – mais le rendu reste algorithmique et peu engageant. Ils indiquent ce qu’une fonction reçoit et renvoie, sans dire pourquoi le système a été conçu ainsi, quelles conventions le régissent, ni comment les éléments s’articulent. La documentation qui devient obsolète est celle rédigée par les individus – vues d’architecture, documents de conventions. Et c’est précisément ce manque qui n’a jamais été comblé.

Pendant des années, concevoir une meilleure solution demandait plus d’efforts que de mettre à jour la documentation manuellement, mais l’arrivée de l’IA a changé la donne. L’écart entre « ce serait génial que ça se mette à jour tout seul » et « je peux à présent construire un système qui le fait » s’est comblé.

Notre équipe travaille rapidement, échange l’information de manière fluide, intègre de nouveaux ingénieurs sans accroc et maintient une compréhension partagée du fonctionnement des systèmes. C’est précisément ce que permet une documentation de haut niveau. Lorsque nous avons passé la nôtre en revue récemment, le constat était familier : certaines sections tenaient encore la route, d’autres décrivaient des bases de code datant de plusieurs mois, et par endroits, la documentation n’avait tout simplement jamais existé – la connaissance résidait uniquement dans la tête de quelques personnes.

Aujourd’hui, comme beaucoup d’équipes, nous utilisons de plus en plus d’agents d’IA dans nos dépôts de code, et ces agents ont les mêmes besoins. Grâce à une documentation de haut niveau, nous pouvons intégrer ces agents comme nous le faisons avec de nouveaux ingénieurs : voici comment les systèmes s’articulent, voici les conventions, voici ce qui compte. Mais, qu’il s’agisse d’utilisateurs humains ou d’agents intelligents, tous les publics peuvent pâtir du même problème : une documentation rédigée une fois, puis jamais mise à jour.

Humains et machines

C’est l’arrivée de ce second public (les agents d’IA) qui a récemment changé notre manière d’aborder l’ensemble du sujet. La documentation était jusqu’ici pensée pour le confort des équipes : un « plus » appréciable, que l’on néglige souvent non sans une certaine culpabilité. Avec l’arrivée des agents d’IA, elle est devenue une véritable composante d’infrastructure.

Constatant que nous répétions les mêmes conventions à plusieurs endroits, nous avons décidé de centraliser et de formaliser cette connaissance. Nous déployons désormais, dans l’ensemble de nos principaux dépôts, des fichiers (AGENTS.md, CLAUDE.md, .cursorrules), tous générés à partir de modèles et comportant un en-tête renvoyant vers notre référentiel central de documentation.

Lorsqu’un agent d’IA commence à travailler sur une base de code Popsa, la première chose qu’il voit est un lien vers notre documentation vivante. On y retrouve les conventions, les modèles de conception, le glossaire, les décisions d’architecture et – point crucial – la connaissance produit Sans cela, comment un agent saurait-il qu’un PBK-7 correspond à un album photo relié de format moyen, ou que TIL-2b désigne un cadre photo noir avec finition brillante ?

Cela crée un cycle particulièrement vertueux :

• les ingénieurs produisent le code

• les agents qui le relisent s’appuient sur la documentation pour formuler des retours plus pertinents et mieux contextualisés

• ces retours entraînent des modifications du code

• ces modifications génèrent des pull requests (PR) de mise à jour de la documentation, prêtes à être revues et fusionnées.

La doc tech ainsi mise à jour devient alors immédiatement disponible pour toute personne ou tout agent qui reprend le travail par la suite. Le système s’autoalimente et gagne en cohérence à mesure qu’il se propage à l’ensemble des dépôts. À mesure que les noms de produits, les feature flags et les événements d’analyse sont intégrés à la documentation centrale, cette connaissance devient accessible à des agents intervenant sur d’autres bases de code

L’équipe Android déploie une nouvelle fonctionnalité. Quelques semaines plus tard, lorsqu’un agent examine la pull request correspondante côté iOS, il dispose du contexte nécessaire pour repérer une incohérence de nommage ou des conventions de suivi différentes. La documentation centrale devient ainsi une mémoire partagée à l’échelle de toute l’entreprise, et non plus un simple référentiel propre à un dépôt donné.

Il y a aussi un enjeu économique. Sans documentation fiable, un agent qui commence à travailler sur un dépôt doit explorer la base de code à partir de zéro : parcourir les fichiers, lire le code source, rechercher des modèles récurrents. Cette exploration consomme des tokens et du temps à chaque interaction. Avec une documentation structurée et à jour, l’agent n’a plus qu’à lire un seul document pour obtenir une vision d’ensemble immédiate. Maintenir une doc tech précise et à jour réduit ainsi le coût de chaque interaction pour tous les agents travaillant au sein de l’entreprise.

Fonctionnement

Nous avons mis en place un pipeline automatisé. Le principe est simple, même si sa mise en œuvre a demandé une réflexion approfondie.

Lorsqu’un ingénieur fusionne du code dans l’un de nos principaux dépôts – services backend, applications web, iOS ou Android, dépôt IaC, une GitHub Action légère se déclenche. Elle récupère les chemins des fichiers modifiés ainsi que la référence du commit, puis envoie un évènement repository_dispatch vers notre dépôt central de documentation.

Côté réception, un autre workflow intercepte cet événement et exécute un traitement très ciblé.

Le point essentiel est qu'il ne régénère pas l’ensemble. Un fichier de configuration YAML associe chaque dépôt source aux fichiers de documentation qu’il peut impacter, ainsi qu’à des schémas glob définissant les chemins de fichiers à surveiller. Une modification des modules Terraform ne déclenchera pas une mise à jour du document de standards Go, tout comme une modification de fichiers Swift n’affectera pas les conventions TypeScript. Seule la documentation réellement concernée par la modification du code est analysée.

Le workflow lance alors Claude Code Code avec un prompt soigneusement construit. Claude lit la documentation existante, explore le dépôt source à l’état exact du commit ayant déclenché l’événement, compare ce que dit la documentation avec le comportement réel du code, puis propose des modifications. Fait notable : il peut également indiquer qu’aucune modification n’est nécessaire. Le prompt encadre précisément ce que Claude doit et ne doit pas faire : conserver la structure des documents, utiliser l’anglais britannique, inclure les chemins de fichiers dans les exemples, ne pas supprimer de contenu encore valide, ne pas ajouter de contenu spéculatif. Nous demandons des « modifications ciblées » plutôt que des « réécritures complètes ».

Quelques précisions sur la manière d’opérer. Le dépôt de documentation ne fonctionne ni par interrogation régulière ni par planification. Ce sont les dépôts sources qui envoient des événements lors des modifications. Ainsi, tout nouveau dépôt peut s’intégrer simplement en ajoutant un workflow de notification et une entrée dans le fichier de configuration. Une seule mise à jour de documentation par dépôt source est exécutée à la fois. Si deux PR sont fusionnées à la suite, la seconde mise à jour attend la fin de la première au lieu d’être ignorée, et Claude peut retourner NO_CHANGES_NEEDED, auquel cas le pipeline se termine proprement. Toutes les modifications de code n’impactent pas les conventions documentées, et le système en tient compte intelligemment, sans générer de bruit inutile.

Un point que nous avons particulièrement apprécié : pendant le développement, Cursor’s Bugbot (un outil de revue de code basé sur l’IA) a détecté six bugs dans l’implémentation initiale du pipeline. Une IA qui examine le code destiné à faire fonctionner une autre IA. Des tortues jusqu'en bas.

Nous avons rendu ce pipeline open source afin que vous puissiez l’adapter à vos propres dépôts.

Passer en revue, pas valider machinalement

Même si tout ce qui nous permet d’aller plus vite nous enthousiasme, nous observons et testons ces systèmes avec une grande rigueur. Le workflow auto‑docs ouvre automatiquement une PR, ce qui permet aux ingénieurs de la relire, de vérifier si les modifications proposées reflètent réellement les changements apportés dans le code, et d’en évaluer la vraisemblance : « Est‑ce bien ce que le code fait désormais ? » Notre équipe peut approuver, demander des corrections ou fermer la PR si nécessaire. Cette étape de relecture de la PR maintient les ingénieurs humains aux commandes : nous restons attentifs à l’évolution de la documentation et conservons une bonne connaissance des conventions. Nous gardons la maîtrise de notre base de connaissances, même si nous ne réalisons plus le travail fastidieux de maintenance au quotidien.

À l’ère de l’IA, c’est ainsi que nous redéfinissons la répartition des rôles :

concevoir le système relève de l’ingénieur, relire sa production relève aussi de l’ingénieur, tandis que la partie répétitive intermédiaire revient à l’IA. Parcourir un diff de modifications de code source, identifier les sections de documentation concernées, rédiger les paragraphes mis à jour, exécuter le linter, ou encore ouvrir la PR relèvent du « travail de fond » dont l’IA s’acquitte désormais avec une réelle efficacité.

Le schéma sous-jacent

Bien que nous ayons conçu ce système pour améliorer la qualité de notre documentation, nous avons découvert un modèle applicable à toute une catégorie de tâches d’ingénierie. Pensez aux tâches que chaque équipe juge essentielles, mais que personne ne veut endosser :

• Maintenir une couverture de test pertinente au fil de l’évolution du code.

• Tenir à jour un changelog décrivant fidèlement les changements apportés.

• Vérifier que les contrats d’API correspondent toujours à leurs implémentations.

• Auditer les versions des dépendances.

• Valider les architecture decision records (ADR).

Ces tâches partagent toutes la même structure : un état actuel et un état désiré, avec pour travail de les comparer et de proposer des mises à jour. Lire l’état actuel, consulter la source de vérité, faire la différence, produire une modification ciblée pour relecture humaine. C’est un modèle que l’IA maîtrise bien, à un coût quasi nul (après mise en place).

Cela nous ramène à notre point de départ. Les gens confient à Popsa leurs photos les plus personnelles, et les souvenirs des personnes et des lieux qui leur sont chers. Les systèmes qui sous-tendent cette expérience doivent être compris, maintenus et sécurisés – non seulement par leurs créateurs, mais par tous ceux qui y travaillent ensuite. La documentation est ce qui rend cela possible, et pour la première fois, nous disposons d’un moyen de la maintenir vivante sans qu’elle devienne pour autant un emploi à temps partiel.

Le résultat : une équipe qui passe moins de temps à maintenir des connaissances et plus de temps à améliorer l’expérience utilisateur – meilleure conservation, meilleure confidentialité, meilleurs produits. Les ingénieurs se concentrent sur le travail qui compte vraiment pour les utilisateurs, et non sur l’entretien en arrière-plan.

C’est la finalité du système. Non pas la documentation en soi, mais ce qu'elle nous permet de faire : concevoir des systèmes à la hauteur des souvenirs qui nous sont confiés