Une équipe de douze personnes décide d'améliorer ses résultats avec l'IA. Elle crée un canal sur Teams : "AI context docs". Au cours des deux semaines suivantes, elle produit quarante pages de documentation : comment fonctionnent les signals d'Angular, comment configurer HttpClient avec des interceptors, les modèles d'injection de dépendances en .NET, ce qu'est un middleware, comment fonctionnent les groupes de variables dans Azure DevOps.
Ils mettent tout cela dans un fichier de contexte. Quarante pages. Trois mille mots.
Les résultats avec l'IA ne s'améliorent pas.
L'IA continue de générer des services avec un nommage incorrect. Elle continue de placer des fichiers dans des dossiers inappropriés. Elle continue d'ignorer que l'équipe utilise des services facade et génère des services plats. Elle continue de proposer des imports croisés entre des domaines qui ne devraient pas communiquer directement.
Ce que cette équipe a documenté, le modèle le savait déjà. Les signals d'Angular figurent dans la documentation officielle que le modèle a traitée lors de son entraînement. HttpClient se trouve dans cent mille tutoriels. Le modèle de middleware en .NET est présent dans chaque cours Pluralsight transcrit et chaque réponse de Stack Overflow indexée.
Ce que l'équipe n'a pas documenté — et ce qui aurait tout changé —, ce sont cinq lignes : pourquoi ils utilisent des services facade, quelle est leur convention de nommage, quels domaines ne peuvent pas importer d'autres domaines, et pourquoi ils ne mettent pas en cache les jetons dans le service d'authentification.
Cinq lignes. Pas quarante pages.
Le problème n'a jamais été la quantité de documentation. C'était l'orientation.
Le critère manquant
Il existe une question qui résout 90 % des doutes sur ce qu'il faut documenter pour un LLM :
Cette information existe-t-elle sur Internet ?
Si la réponse est oui — dans la documentation officielle, les tutoriels, les dépôts publics, Stack Overflow — le modèle la connaît probablement déjà. La documenter est redondant. Vous occupez le contexte avec des informations que le modèle possède par défaut.
Si la réponse est non — si cette information n'existe que dans votre équipe, dans vos décisions, dans votre histoire organisationnelle — alors le modèle en a besoin de votre part. Car il n'y a aucun autre moyen de l'obtenir.
C'est un critère simple, mais ses implications sont profondes. Cela change complètement ce qui vaut la peine d'être documenté.
Ne documente pas Angular. Documente ta façon d'utiliser Angular.
Ne documente pas .NET. Documente pourquoi votre équipe utilise .NET de cette manière.
Ne documente pas ce qu'est un pipeline Azure DevOps. Documente pourquoi le vôtre est structuré ainsi et pas autrement.
Le modèle sait ce qu'est un interceptor. Il ne sait pas que dans votre projet, les interceptors suivent un modèle spécifique avec une logique de retry personnalisée, car la passerelle APIM a un timeout de 30 secondes qui impose cette décision.
Le modèle sait ce qu'est la clean architecture. Il ne sait pas que dans votre monorepo, la séparation entre les domaines existe pour une raison métier spécifique : le domaine des paiements ne peut pas être couplé à celui des utilisateurs, car la réglementation financière exige qu'ils soient déployables de manière indépendante.
Le modèle sait comment fonctionne Nginx. Il ne sait pas que votre reverse proxy a une configuration particulière pour les microfrontends, car il y a eu un problème de CORS en production qui a mis deux jours à être résolu, et la solution a été un en-tête personnalisé dans un bloc location spécifique.
Tout cela est une information exclusive. Elle n'existe que dans votre équipe. Et c'est exactement ce dont le modèle a besoin pour passer de la génération de code générique à la génération de code qui fonctionne dans votre projet.
Ce que le LLM sait déjà
Je pense que de nombreuses équipes enterprise sous-estiment ce que les modèles de langage comprennent déjà. Je ne le dis pas comme une opinion, mais comme une observation répétée dans des projets réels.
Les LLM ont été entraînés avec des millions de dépôts publics. Ils ont traité la documentation officielle complète d'Angular, React, Vue, .NET, Spring, Node. Ils ont vu des milliers d'implémentations de chaque modèle. Ils ont lu l'intégralité de Stack Overflow. Ils ont traité chaque tutoriel, chaque cours transcrit, chaque article de blog technique ayant une visibilité suffisante.
Qu'est-ce que cela signifie en pratique ?
Frameworks et langages : Le modèle comprend les lifecycle hooks, l'injection de dépendances, le routing, le state management, les reactive patterns, les testing strategies — dans chaque framework mainstream. Vous n'avez pas besoin de lui expliquer ce qu'est un WritableSignal dans Angular ou comment fonctionne un IServiceCollection en .NET. Il le sait. Probablement mieux que la plupart des développeurs juniors de votre équipe, car il a vu plus d'implémentations diverses que n'importe quelle personne individuellement.
Modèles de conception : SOLID, DDD, CQRS, Event Sourcing, microservices, repository pattern, mediator, facade, strategy — les modèles courants sont intégrés comme connaissance de base. Le modèle sait ce qu'est un service facade. Ce qu'il ne sait pas, c'est pourquoi VOUS avez choisi les services facade plutôt qu'une autre option.
APIs et bibliothèques publiques : Si une bibliothèque a plus de cinq cents étoiles sur GitHub, le modèle la connaît. Les APIs d'Azure, AWS, GCP — traitées de manière extensive. Nginx, Redis, Docker, Kubernetes — il connaît les configurations standard, les flags, les options. Vous n'avez pas besoin de copier la documentation officielle dans votre fichier de contexte. C'est de la pure redondance.
Bonnes pratiques génériques : Tout ce qui apparaît dans les premiers résultats de "best practices [technologie]" sur Google fait déjà partie de la connaissance de base du modèle. Modèles de gestion des erreurs courants, en-têtes de sécurité, configurations CORS, pipelines CI/CD standard, bonnes pratiques de Dockerfile.
Il existe un test pratique : Posez une question générique sur votre stack au modèle sans lui donner aucun contexte de votre projet. Si la réponse est correcte — et dans les frameworks matures, elle le sera dans 90 % des cas — vous n'avez pas besoin de documenter cela. Le modèle le possède déjà.
Ce que cela implique est inconfortable mais nécessaire : si vos quarante pages de documentation répètent des choses que le modèle sait déjà, elles ne sont pas seulement inutiles — elles sont activement nuisibles. Elles occupent de l'espace dans la fenêtre de contexte. Elles entrent en concurrence avec les informations qui compteraient vraiment. Le modèle ne fait pas de distinction entre vos trente pages de tutoriel Angular redondant et vos cinq lignes de conventions critiques. Il traite tout avec le même poids. Et si les cinq lignes importantes se diluent parmi trente pages de bruit, le résultat se dégrade.
Moins de documentation correcte l'emporte sur plus de documentation générique. Toujours.
Ce que le LLM ne peut pas inférer
Maintenant, l'autre côté. Si le modèle sait déjà tout ce qui est générique — qu'est-ce qu'il ne sait pas et ne pourra jamais savoir sans votre aide ?
Il y a six catégories d'informations qui sont exclusives à votre organisation. Elles n'existent dans aucun ensemble de données d'entraînement. Elles ne peuvent pas être déduites du code. Elles ne figurent dans aucun tutoriel. Seule votre équipe les connaît. Et ce sont exactement ce qui sépare un résultat qui passe la revue de code d'un résultat qui est immédiatement rejeté.
1. Décisions architecturales
Le pourquoi derrière votre structure. Pas le quoi — le pourquoi.
Le modèle peut voir dans votre base de code que vous utilisez des services facade. Il peut voir que votre monorepo a une structure de domaines. Il peut voir que vous n'utilisez pas NgRx global. Ce qu'il ne peut pas voir, c'est pourquoi.
Pourquoi des services facade ? Parce qu'avec douze microfrontends, vous avez besoin d'une interface publique stable entre les domaines, et les services domain changent trop fréquemment pour être consommés directement par d'autres équipes.
Pourquoi SignalStore local et pas NgRx global ? Parce que vous avez évalué NgRx en 2023 et que le surcoût de boilerplate ne se justifiait pas pour la taille de vos features. L'état est local à chaque microfrontend par conception.
Pourquoi des vertical slices dans le domaine des paiements mais des layers dans le domaine des utilisateurs ? Parce que les paiements ont des exigences de conformité qui imposent une traçabilité par opération, et les vertical slices facilitent l'audit trail.
Sans le pourquoi, l'IA propose des alternatives que l'équipe a déjà évaluées et rejetées. Elle suggère NgRx "comme amélioration". Elle suggère l'injection directe de services domain "pour simplifier". Des solutions que vous avez déjà écartées il y a un an pour des raisons concrètes qui n'existent que dans la mémoire de la personne qui a pris la décision.
Une ligne documentant la raison évite des mois de suggestions non pertinentes.
2. Contraintes métier
Des règles qui ne viennent pas de la technologie mais du métier. Le modèle génère des solutions techniquement parfaites qui violent des contraintes qui ne sont même pas techniques.
"Nous ne pouvons pas utiliser de CDN externes car la réglementation bancaire interdit que les données des clients passent par des nœuds hors de l'UE." L'IA cesse de suggérer Cloudflare comme optimisation des assets.
"Le service de notifications ne peut pas faire plus de 100 requêtes par minute vers le fournisseur de SMS car notre contrat avec le vendeur a cette limite." L'IA cesse de proposer des envois groupés massifs.
"Nous ne pouvons pas modifier le format de réponse de l'API des partenaires car trois intégrateurs externes dépendent de ce format jusqu'au renouvellement du contrat en 2027." L'IA cesse de suggérer "d'améliorer" le schéma de réponse.
Chacune de ces contraintes est invisible dans le code. On ne peut pas les déduire en lisant l'implémentation. Un nouveau développeur les découvrirait lors de sa troisième semaine quand quelqu'un lui dit "on ne peut pas faire ça à cause de X." L'IA n'a pas cette troisième semaine. Elle a besoin de la contrainte documentée.
3. Conventions internes
Tout ce qui s'apprend par la revue de code et la tradition orale.
Votre convention de nommage spécifique : {Feature}{Tipo}Service — pas {Tipo}Service. Votre structure de dossiers : libs/{domain}/{feature}/services/ — pas src/services/. Votre modèle de gestion d'erreurs : encapsuler les appels HTTP avec handleApiError() du shared — pas des try/catch manuels. Votre style de test : describe par méthode publique, mocks avec ng-mocks, assertions avec un helper personnalisé.
Rien de tout cela n'est dans un .eslintrc qui l'impose. Il n'y a pas de linter qui le détecte. Cela n'existe que dans la pratique de l'équipe. Cela se corrige lors des revues de code. Cela se transmet des seniors aux juniors lors de la programmation en binôme. Cela s'absorbe par répétition.
Le modèle suit les conventions les plus courantes sur Internet. Les vôtres lui sont invisibles. Et c'est pourquoi il génère des services qui s'appellent NotificationService au lieu de UserNotificationFacadeService, qui vont dans src/services/ au lieu de libs/notifications/user/services/, et qui utilisent try/catch au lieu de votre wrapper personnalisé.
Cinq lignes de conventions documentées. Voilà ce qui sépare "l'IA ne comprend pas notre projet" de "des résultats qui passent la revue de code."
4. Limites entre domaines
Quel module est responsable de quoi. Quels imports sont autorisés. Quelles données traversent les frontières et lesquelles ne le font pas.
Dans un monorepo Nx avec microfrontends, ces règles sont critiques. libs/domain-payments ne peut pas importer de libs/domain-users. La communication entre domaines se fait via shared/contracts. Les composants de shared/ui ne peuvent pas avoir de logique métier. Ce qui est dans feature/ est privé à ce domaine.
Tous les membres de l'équipe le savent. Personne ne l'a écrit. Et l'IA viole ces frontières dans chaque deuxième résultat parce qu'elle n'a aucun moyen de connaître des règles qui ne sont ni écrites ni imposées par des outils.
Chaque violation commise par l'IA est un indicateur que cette frontière n'existe que dans les têtes de l'équipe. C'est une information qui devrait être explicite non seulement pour l'IA — mais pour toute personne nouvelle.
5. Raisons historiques
Pourquoi quelque chose a été fait d'une manière qui semble sous-optimale. Les bugs qui conditionnent les décisions actuelles. Les migrations incomplètes. Les contournements qui ne peuvent pas être supprimés.
Le service d'auth ne met pas en cache les jetons. Cela semble inefficace. Un nouveau développeur — ou une IA — le voit et pense "optimisation évidente." Mais il y a un incident en 2024 où un jeton révoqué restait actif dans le cache et a provoqué un accès non autorisé pendant quatre heures. Post-mortem. Décision explicite : ne jamais mettre en cache les jetons d'auth dans ce service.
Où est-ce documenté ? Nulle part. Dans la tête du senior qui a vécu l'incident et dans un fil Slack archivé.
L'IA suggère de mettre en cache. Quelqu'un implémente la suggestion. Le bug revient. Et alors : "C'est déjà arrivé une fois. Personne ne s'en souvenait ?"
Une ligne. "Jetons d'auth : pas de cache. Référence : incident #347 (2024), jeton révoqué actif dans le cache." Une ligne qui évite de répéter un problème de production.
6. Exceptions organisationnelles
Des règles qui s'appliquent à tout sauf à un cas concret — et pourquoi.
"Tous les services utilisent .NET 8 sauf payment-gateway qui reste en .NET 6 jusqu'au T2 2027 pour cause de certification PCI-DSS en attente." L'IA cesse de suggérer de migrer ce service et cesse de générer du code qui suppose .NET 8 dans ce contexte.
"Tous les domaines suivent la clean architecture sauf legacy-reporting qui est en vertical slices parce qu'il a été partiellement migré depuis un monolithe et n'a pas été terminé en raison d'une dépriorisation métier." L'IA n'essaie pas de "corriger" l'incohérence.
"Tous les pipelines utilisent le template standard sauf celui de mobile-bff qui a des étages supplémentaires en raison des exigences de signature d'Apple." L'IA génère du YAML correct pour chaque contexte.
Chaque exception a une raison. Si la raison n'est pas documentée, l'IA — et les nouveaux employés — tenteront de "normaliser" l'exception. Ce qui casse parfois des choses de manière coûteuse.
Le contraste en action
Je veux rendre tangible la différence entre documenter ce que le modèle sait déjà et documenter ce que seule votre équipe connaît. Trois situations que j'ai vues se répéter.
L'équipe qui a documenté Angular et n'a rien amélioré.
Une équipe écrit un guide de trente pages pour donner du contexte à l'IA. Lifecycle hooks. Comment fonctionne l'ID. Comment créer des composants avec l'API standalone. Routing avec lazy loading. Test avec TestBed.
Tout cela, le modèle le sait. Mieux que le guide, d'ailleurs, car le modèle a vu plus de variantes et plus d'exemples.
Les résultats de l'IA restent médiocres. Non pas parce que le modèle ne comprend pas Angular — mais parce qu'il ne comprend pas CE projet Angular.
Solution : ils suppriment les trente pages. Ils écrivent vingt lignes :
- Patron : services facade comme interface publique. Services domain internes.
- Convention de nommage :
{Feature}{Tipo}Service - État : signals, pas BehaviorSubject.
- Emplacement :
libs/{domain}/{feature}/services/ - Interdit : subscribe() manuel. Services >300 lignes. Imports entre domaines.
- Test : describe par méthode, ng-mocks, assertions avec helper
expectSignal().
Les résultats commencent à passer la revue de code. Non pas parce que le modèle s'est amélioré. Mais parce qu'il a maintenant l'information qui lui manquait — l'information exclusive de l'équipe.
Vingt lignes ont remplacé trente pages. Et elles ont mieux fonctionné.
L'API .NET où cinq lignes ont tout changé.
Wiki Confluence de quinze pages. "Comment on développe des APIs dans notre équipe." Cela inclut : ce qu'est un Controller, comment fonctionne le routage dans ASP.NET, ce qu'est un middleware, comment on configure Entity Framework. Le modèle connaît chaque mot de ce contenu.
Les contrôleurs générés par l'IA sont techniquement corrects selon les pratiques standard de .NET. Mais ils ne suivent pas les huit conventions de l'équipe. Nommage des endpoints différent. Middleware dans un ordre différent. Format des réponses d'erreur différent. Rate limiting par clé API au lieu de par utilisateur.
Solution : cinq lignes.
- Versionnage :
/api/v{n}/{resource} - Convention de nommage : verbes en anglais, singulier pour GET item, pluriel pour GET collection
- Format d'erreur : toujours
ProblemDetailsavec correlationId du middleware - Rate limiting : par clé API (pas par utilisateur), en-tête
X-Api-Key - Ordre du middleware : Correlation → Auth → RateLimit → Validation → Handler
Contrôleurs générés prêts pour la revue de code. Cinq lignes. Pas quinze pages.
Le pipeline qui n'existait que dans une tête.
Pipeline Azure DevOps. Templates personnalisés réutilisables. Variables par environnement dans des groupes de variables avec nommage spécifique. Étages conditionnels. Deployment gates avec approbation manuelle pour la production. Un système sophistiqué construit pendant un an et demi par le lead DevOps.
L'IA génère du YAML générique Azure DevOps — correct selon la documentation officielle, inutile pour cette équipe. Il n'utilise pas les templates. Il ne référence pas les groupes de variables. Il ne suit pas la structure des étages.
L'équipe dit "l'IA ne comprend pas Azure DevOps avancé." Correction : l'IA comprend parfaitement Azure DevOps. Ce qu'elle ne comprend pas, c'est votre configuration, car elle n'existe que dans la tête d'une personne.
Solution : dix lignes.
- Templates :
templates/build-{platform}.yml,templates/deploy-{env}.yml - Groupes de variables :
vars-{service}-{environment}(ex:vars-api-production) - Étages : Build → Test → Deploy-Dev → Deploy-Staging → Deploy-Prod
- Conditions : Deploy-Prod uniquement sur main, nécessite l'approbation de @devops-leads
- Secrets : toujours de Key Vault, jamais en ligne. Référence :
$(KeyVault-{service})
L'IA génère du YAML cohérent avec la configuration. Mais ce qui a été révélateur, c'est l'effet secondaire : un développeur junior a lu ces dix lignes et a compris la structure du pipeline pour la première fois. Il était dans l'équipe depuis six mois et n'avait jamais compris la logique complète — parce que personne ne la lui avait expliquée autrement qu'en disant "regarde comment celui-ci est fait."
Ces dix lignes n'ont pas seulement aidé l'IA. Elles ont aidé l'équipe.
Documentation comme infrastructure
Il y a quelque chose que je veux expliciter parce que je pense que c'est le changement de mentalité le plus important de cet article.
La documentation dont je parle n'est pas de la bureaucratie. Ce n'est pas l'acte de documenter pour respecter un processus. Ce ne sont pas ces wikis Confluence que personne ne lit et qui se dégradent en deux semaines. Ce n'est pas ce qu'un responsable qualité demande pour satisfaire une norme ISO.
C'est de l'infrastructure.
Tout comme une équipe a une infrastructure de CI/CD, une infrastructure de monitoring, une infrastructure de test — la connaissance explicite de l'équipe est une infrastructure opérationnelle. C'est ce qui permet aux outils de fonctionner, aux nouvelles personnes d'être productives, et aux décisions passées de ne pas se répéter.
Pensez-y ainsi : personne ne remet en question le besoin de pipelines de CI/CD. Personne ne dit "c'est de la bureaucratie d'avoir des tests automatisés." Ce sont des infrastructures qui permettent à l'équipe de fonctionner. La connaissance explicite — documentée de manière concise, maintenable, située à côté du code — est exactement cela. Une infrastructure qui permet à l'équipe de fonctionner. À l'IA de fonctionner. À toute nouvelle personne de fonctionner.
Et comme toute infrastructure, elle a de la maintenance. Les décisions changent. Les conventions évoluent. Les exceptions se résolvent. Un architecture.md n'est pas un document statique que l'on écrit une fois et que l'on archive. C'est un artefact vivant qui reflète l'état actuel de la connaissance de l'équipe. Il est mis à jour lorsqu'une nouvelle décision est prise. Il est corrigé quand quelque chose change. Il est versionné comme le code l'est.
Le coût de maintenance est minime — si la documentation est concise. Vingt lignes se mettent à jour en cinq minutes. Quarante pages ne se mettent jamais à jour. Le format importe : bref, structuré, déclaratif, et situé là où on le consulte (à côté du code, pas dans un système externe que personne n'ouvre).
L'avantage qui ne peut pas être copié
Tout cela a une implication stratégique qui va bien au-delà de la productivité individuelle.
Dans un futur très proche, toutes les équipes auront accès aux mêmes modèles. Aux mêmes outils. Aux mêmes capacités de contexte. Aux mêmes agents. La technologie sera une commodité.
Ce qui ne sera pas une commodité, c'est la connaissance explicite de chaque organisation. Les décisions documentées. Les conventions formalisées. Les raisons historiques enregistrées. Les frontières définies.
La qualité du contexte organisationnel est un avantage concurrentiel qui ne peut pas être copié. Ce n'est pas un meilleur modèle — c'est votre information, votre histoire, vos décisions, rendues explicites de manière consommable par les outils et les personnes.
Les équipes qui travailleront le mieux avec l'IA ne seront pas celles qui ont les meilleurs prompts. Ce ne seront pas celles qui utilisent l'outil le plus cher. Ce ne seront pas celles qui ont suivi le plus de cours "AI pour développeurs."
Ce seront celles qui ont la meilleure connaissance explicite.
Celles qui ont transformé la connaissance tacite — dans les têtes des personnes, dans les fils Slack, dans la tradition orale — en connaissance explicite : documentée, versionnée, maintenue, consommable à la fois par les outils et par les personnes.
Cette transformation est celle qui produit un avantage composé. Chaque décision documentée améliore chaque interaction future avec l'IA. Chaque convention rendue explicite réduit les frictions avec chaque nouvel outil. Chaque raison historique enregistrée évite de répéter des erreurs avec chaque nouvelle personne — qu'elle soit humaine ou un modèle.
Et cet avantage s'accumule. Chaque semaine qui passe avec une connaissance explicite est une semaine de meilleurs résultats, d'onboarding plus rapide, de moins d'erreurs répétées. Les équipes qui commencent aujourd'hui prennent de l'avance demain. Et l'avantage s'amplifie avec chaque amélioration technologique — car chaque nouveau modèle extrait plus de valeur d'un contexte riche.
La valeur qui transcende l'IA
Il y a quelque chose que je veux dire clairement parce que c'est important : la vraie valeur de rendre explicite la connaissance de votre équipe n'est pas d'aider l'IA.
L'IA est le catalyseur. C'est la raison pour laquelle il y a maintenant une urgence. Mais les bénéfices sont bien plus larges.
Onboarding. Une personne nouvelle qui lit vingt lignes de décisions clés et de conventions de l'équipe commence à produire du code aligné dès la première semaine — au lieu d'avoir besoin de quatre semaines d'osmose et de corrections dans les revues de code. J'ai vu le temps d'onboarding être réduit de moitié avec un fichier d'une page.
Bus factor. Si les cinq décisions les plus critiques du projet vivent dans la tête d'un senior et que ce senior part — il emporte avec lui une partie du projet qui est irrécupérable. Ces mêmes cinq décisions documentées survivent aux personnes. La connaissance appartient à l'équipe, pas aux individus.
Cohérence. Des conventions explicites produisent automatiquement un code cohérent. Pas grâce à des règles de lint — grâce à la clarté. Quand tout le monde sait quel est le bon patron (parce qu'il est écrit, pas parce qu'il a été appris par répétition), les incohérences disparaissent sans effort d'imposition.
Décisions futures. Savoir pourquoi une décision a été prise permet de l'évaluer lorsque le contexte change. "Nous avons choisi X pour Y raison dans Z contexte." Si Z ne s'applique plus, vous pouvez reconsidérer X avec information. Sans le pourquoi documenté, changer des décisions revient à naviguer à l'aveugle — et l'équipe a tendance à ne rien toucher "au cas où."
L'IA a mis un coût immédiat et visible à l'absence de connaissance explicite. C'est l'incitation nouvelle. Mais l'investissement bénéficie à tout le reste simultanément. Vous documentez pour l'IA et, par la même occasion, vous améliorez l'onboarding, réduisez le bus factor, augmentez la cohérence et facilitez l'évolution architecturale.
C'est un investissement à multiples retours. L'IA n'est que le plus visible et le plus urgent.
Le critère en une phrase
Si vous avez besoin d'une règle simple pour décider quoi documenter :
Si vous pouvez trouver cette information sur Google, le modèle l'a déjà. Si elle n'existe que dans votre équipe, le modèle a besoin de vous.
Quand vous doutez, demandez : "Quelqu'un de l'extérieur de l'équipe, lisant uniquement le code et la documentation publique, pourrait-il savoir cela ?" Si non — documentez. Si oui — ne perdez pas votre temps.
Ce n'est pas "documentez tout." Ce n'est pas "ne documentez rien." C'est : documentez ce qui est exclusif. Ce que seule votre organisation connaît. Ce qui n'existe dans aucun ensemble de données d'entraînement. Ce qui fait que votre projet est votre projet et non un tutoriel générique.
Et commencez par ce sur quoi l'IA échoue systématiquement. Chaque résultat médiocre est un indicateur d'une information qui devrait être explicite et ne l'est pas. Si l'IA génère des services avec une convention de nommage incorrecte — documentez votre convention de nommage. Si elle viole les frontières entre modules — documentez les frontières. Si elle suggère des patrons que vous avez écartés — documentez la raison pour laquelle ils ont été écartés.
L'IA vous dit exactement quoi documenter. Vous avez juste besoin d'écouter.
Prochaine étape
Si cette série d'articles résonne avec ce que vous observez dans votre équipe, chaque semaine je publie des analyses pratiques sur la façon dont les équipes enterprise peuvent mieux travailler avec l'IA. Sans hype. Sans marketing. Des diagnostics réels et des solutions concrètes pour les architectes et tech leads qui construisent des systèmes complexes.
Si vous voulez voir la structure concrète du fichier qui applique ce critère — quelles sections inclure, quel format fonctionne, comment le maintenir — lisez "Pourquoi un architecture.md vaut mieux que cent prompts magiques."
Si avant de documenter vous voulez diagnostiquer où se trouvent les dettes les plus coûteuses de votre projet, lisez "La dette technique que l'IA commence à révéler."
Vous savez maintenant quoi documenter. Vous savez maintenant quoi ne pas documenter. Le critère est simple. L'avantage à l'appliquer est composé. Et la première étape est petite — vingt lignes que seule votre équipe connaît.
Publié : Mai 2026