Le texte brut l’emporte : créez un wiki adossé à Git auquel vos agents IA et vos ingénieurs font confiance

Votre problème n’est pas l’hallucination. C’est la documentation. Si votre savoir opérationnel est éparpillé entre Notion, Confluence, fils Slack, Google Docs et cinq wikis de fournisseurs, vos agents (et vos nouvelles recrues) jouent au téléphone arabe. Résultat : des réponses aux incidents lentes, des automatisations fragiles et une défiance rampante envers l’IA au sein de l’ingénierie.

Il existe un correctif simple, rapide et efficace : un wiki en texte brut, adossé à Git, que humains et agents lisent et écrivent. Inspiré par les échanges récents autour des wikis LLM à la Karpathy et par le rappel que le texte brut perdure, ce n’est pas de la nostalgie. C’est un choix qui optimise auditabilité, latence et coût — exactement ce dont une pile IA de production a besoin.

Pourquoi texte brut + Git l’emportent sur votre dispersion actuelle

• Une auditabilité que vous maîtrisez déjà : PR, diffs, CODEOWNERS et reviews sont des réflexes pour vos équipes. « Docs as code » vous apporte provenance et contrôle des changements sans acheter un outil de plus.
• Nativement compatible LLM : Markdown est économe en tokens, facile à découper et se compresse bien. Vous pouvez l’alimenter dans votre RAG sans vous battre avec des formats propriétaires ni des connecteurs fragiles.
• Peu coûteux et rapide : un index vectoriel de 100 k segments (768 dims en float32) représente ~300 Mo de vecteurs plus le surcoût d’index — disons moins de 500 Mo. Les bases vectorielles modernes renvoient un top‑k en moins de 50 ms à cette échelle.
• Durabilité « offline‑first » : si vos fournisseurs limitent les APIs ou changent de format, votre savoir compile quand même. Les miroirs Git et snapshots S3 survivent aux outils et aux organigrammes.

Le cadre de décision d’un CTO pour un wiki adossé à Git et lisible par des agents

1) Périmètre : ce qui a sa place (et ce qui n’en a pas)

• À inclure : vues d’ensemble d’architecture, runbooks, playbooks, contrats de service, spécifications d’API, FAQs produit, checklists d’onboarding, docs CI/CD, inventaires de shadow IT, limites et SLAs des fournisseurs.
• À exclure : secrets, identifiants, PII clients et journaux non caviardés. Ne discutez pas : votre wiki sert de référence et de support de raisonnement, pas de clés ni de données brutes.
• Classification : appliquez un tag de tri simple dans le front matter — vert (interne-public), ambre (interne-restreint), rouge (hors wiki). Les agents ne voient jamais le rouge. L’ambre est contrôlé au niveau des répertoires.

2) Topologie du dépôt et métadonnées

• Un dépôt kb par entité métier (ou un mono‑kb si vous êtes moins de 100 ingénieurs). Le sur‑sharding tue la découvrabilité ; le sous‑sharding surcharge les responsables.
• Arborescence par domaine : platform/, app/, data/, sec/, ops/, product/. Dans chacun, des dossiers au niveau service avec un squelette standard : overview.md, runbook.md, metrics.md, limits.md, faq.md.
• Front matter : Title, tags, owners (identifiants Git), last_verified_at, TTL_days, sensitivity. Votre CI peut en forcer la présence et la fraîcheur.

3) Contribution et revue

• PR uniquement : humains et agents proposent des changements via PR. Aucun commit direct sur main. Exigez au moins une approbation humaine pour toute modification de runbooks ou de limites.
• Garde‑fous CI : lint Markdown, correcteur orthographique, vérification de liens cassés, scan regex PII de base et un job de « fraîcheur des docs » qui signale les last_verified_at périmés. Faites échouer le build en cas d’alerte rouge.
• SLA par niveau : les PR Tier 0 (incidents, sécurité) visent une revue sous 4 h ; Tier 1 (critiques produit) sous 24 h ; Tier 2 hebdomadaire.

4) Stockage et indexation : l’hybride bat le tout‑vectoriel

• Principal : GitHub ou GitLab avec branches protégées, miroir nocturne vers S3. Gardez le dépôt du wiki découplé de vos dépôts de code.
• Recherche : utilisez un index hybride : un index inversé (OpenSearch, Meilisearch) pour la recherche exacte, plus un store vectoriel (Qdrant, Weaviate) pour le sémantique. Combinez les scores à l’exécution de la requête pour le meilleur des deux mondes.
• Ingestion : surveillez les diffs git ; découpez le Markdown modifié en segments de 300–500 tokens avec 10–15 % de chevauchement ; embed puis upsert. Cela évite de ré‑indexer le monde à chaque commit.

5) Interface agent : lire, citer et écrire comme un ingénieur

• Politique de retrieval : top‑k=8 candidats hybrides, puis re‑classement par cross‑encoder vers 3–5 extraits. Forcez les agents à citer les chemins de fichier et plages de lignes dans leurs réponses. Journalisez les citations.
• Mises à jour via PR : lorsqu’un agent détecte une dérive (ex. un 429 d’une API fournisseur contredit les limites documentées), il ouvre une PR avec un diff minimal et des liens vers les preuves. Les humains revoient ; la CI impose la fraîcheur.
• Hygiène mémoire : donnez aux agents un scratchpad court terme (Redis avec TTL de 24–72 h) pour le contexte éphémère. La mémoire durable vit dans Git après revue.

6) Identité, permissions et rayon d’explosion

• AuthN/AuthZ : SSO OIDC vers votre fournisseur Git ; CODEOWNERS pour les garde‑fous de domaine ; branches protégées pour main ; bots limités aux dépôts kb uniquement.
• Accès au niveau répertoire, pas au niveau fichier, pour garder une complexité supportable. Si vous avez besoin d’ACL au niveau document, votre problème est la classification, pas l’outillage.
• RBAC des agents : comptes de service séparés par agent, avec écriture limitée aux branches de brouillon. Chaque PR d’agent se labellise avec le workflow appelant et le run id.

7) Chaîne d’outils pour humains et machines

• Markdown (GFM) avec titres, tableaux et diagrammes mermaid. Évitez les intégrations propriétaires. Conservez les images à côté des docs avec un texte alternatif descriptif pour aider les pipelines OCR/LLM.
• Site statique pour les humains : Docusaurus ou MkDocs‑Material publié sur un domaine interne. Rapide, recherchable et versionné.
• Discipline de diagrammes : préférez des diagrammes textuels commités dans Git plutôt que des exports PNG. Les agents peuvent diff et mettre à jour du texte ; ils ne peuvent pas éditer votre capture.

8) Qualité, détection de dérive et télémétrie

• Métrique de couverture : suivez la « couverture de connaissance » comme (# de services Tier 0/1 avec runbooks et limites à jour) divisé par le total de services Tier 0/1. Ciblez 90 %+ sous 60 jours.
• Sondes de dérive automatisées : jobs légers qui interrogent les APIs critiques des fournisseurs (limites/endpoints) et comparent à la doc. Ouvrez une PR en cas d’écart au‑delà d’un seuil (p. ex. 10 %).
• Analytics de recherche : journalisez les requêtes en échec et les recherches sans résultat sur le site statique et côté agents ; transformez le top 20 en docs à chaque sprint.

9) Coût et performance : des chiffres que vous pouvez défendre

• Exemple d’échelle : 5 000 pages Markdown de 800 tokens en moyenne, découpées en segments de 400 tokens ≈ 10 000 chunks.
• Stockage : 10 000 vecteurs × 3 Ko ≈ 30 Mo de vecteurs ; avec index HNSW et métadonnées, budgétez 100–150 Mo.
• Latence : une recherche hybride à 10–100 k chunks renvoie typiquement en 30–70 ms sur du matériel standard. Le re‑ranking ajoute 10–25 ms CPU. Un RAG de bout en bout sous 200 ms est atteignable on‑prem.
• Coût d’embedding : si vous auto‑hébergez un petit modèle d’embedding, un seul GPU classe T4 peut embed 10–20 k chunks en quelques minutes ; le CPU‑only est plus lent mais économique pour des jobs nocturnes. Les embeddings managés coûtent de quelques cents à quelques dollars par ré‑index — encore négligeable à cette échelle.

Une architecture de référence pragmatique

• Rédaction : dépôt GitHub/GitLab (kb) → PR (humains + agents) → CI (lint, scan PII, fraîcheur, liens cassés) → main protégée.
• Publication : build de site statique vers un domaine interne avec recherche par mots‑clés intégrée.
• Index : service d’ingestion surveillant les diffs du dépôt → découpe/normalisation → embed → upsert vers Qdrant (sémantique) et OpenSearch (lexical).
• Service : API de retrieval mélangeant lexical + vectoriel → re‑ranking optionnel → renvoie extraits classés + citations → consommateurs agents/humains.
• Gouvernance : sondes de dérive + analytics de recherche → PR pour combler les écarts → tableaux de bord de couverture/fraîcheur.

Sécurité et conformité : volontairement ennuyeuses

• Aucun secret dans le wiki. Traitez les connaissances classées rouge comme hors wiki et pointez vers votre coffre-fort ou votre système de tickets.
• Garde‑fous PII : des regex dans la CI attrapent les fuites évidentes ; des scans DLP périodiques attrapent le reste. Faites échouer les builds en cas de détection.
• Backups : miroir S3 nocturne avec rétention immuable et réplication inter‑régions. Testez les restaurations chaque trimestre.
• Conservation légale : taguez les commits associés aux enquêtes ; empêchez le garbage collection des branches concernées.

Modes d’échec fréquents (et comment les éviter)

• Laisser les agents committer sur main : faites passer chaque changement d’agent par une PR avec revue humaine. C’est ainsi que vous préservez la confiance.
• Modéliser les permissions au niveau fichier : c’est un piège. Utilisez un périmètre au niveau répertoire et améliorez la classification.
• « On synchronisera Notion plus tard » : les connecteurs pourrissent et limitent le débit. Migrez maintenant les docs critiques vers Markdown ; laissez derrière un bandeau de dépréciation.
• Diagrammes et PDFs uniquement binaires : si un LLM ne peut pas faire de diff, il ne peut pas maintenir. Préférez des artefacts text‑first. Lancez de l’OCR sur les PDFs hérités et annotez avec un alt text.
• Indexer chaque commit globalement : surveillez les diffs ; ne ré‑embed que les segments changés. Cela garde coûts et latence prévisibles.

Un déploiement 30–60–90 jours qui ne perturbera pas la livraison

Jours 0–30 : mettre en place l’ossature

• Créez le(s) dépôt(s) kb, choisissez le générateur de site statique, imposez les garde‑fous CI (lint, scan PII, fraîcheur) et définissez le front matter et le squelette de dossiers.
• Instrumentez la recherche hybride (OpenSearch + Qdrant) et une API de retrieval simple. N’optimisez pas trop le ranking pour l’instant.
• Migrez les runbooks et limites Tier 0 pour vos 10 services principaux. Nommez des responsables et fixez des SLAs.

Jours 31–60 : brancher les agents et la détection de dérive

• Activez les « PR d’agent » avec un compte bot à périmètre restreint. Exigez des citations pour toute modification rédigée par un agent.
• Ajoutez des sondes de dérive pour deux dépendances externes (p. ex. limites de débit de votre fournisseur d’authentification, pagination de l’API de facturation). Branchez les sondes pour ouvrir automatiquement des PR en cas de divergence.
• Publiez des tableaux de bord d’usage : % de couverture, % de fraîcheur, top des recherches en échec.

Jours 61–90 : monter en charge et durcir

• Élargissez aux services Tier 1 et à la doc plateforme. Visez 90 % de couverture sur les Tiers 0/1.
• Ajoutez le re‑ranking et ajustez les poids de mélange. Visez un retrieval de bout en bout <200 ms.
• Menez un exercice de red team : tentez d’insérer de la PII dans le wiki et de contourner la CI. Corrigez les constats.

Où les équipes nearshore aident (et où elles n’aident pas)

Si vous manquez de capacité, une équipe nearshore disciplinée peut amorcer ce chantier sans détourner votre roadmap. Brazil offre 6–8 heures de recouvrement avec les fuseaux horaires des États‑Unis, des workflows natifs Git et des ingénieurs qui vivent dans la CI. Elles sont utiles pour le travail ingrat : migration de docs, plomberie CI, sondes de dérive et pipelines d’indexation. Gardez la propriété et la revue chez vos responsables de domaine ; n’externalisez pas la voix de vos runbooks.

Quand ne pas faire cela

• Si 90 % de votre savoir est constitué de captures d’écran et de PDFs de fournisseurs et que vous ne pouvez pas vous engager vers le tout‑texte à l’avenir, vous nagerez à contre‑courant. Corrigez cela d’abord.
• Si vous n’avez pas une culture de la revue, un wiki Git devient un cimetière aussi vite que votre Notion. Nommez des responsables et faites respecter les SLAs.
• Si votre contrainte principale est un accès documentaire piloté par la conformité au niveau utilisateur/fichier, acceptez un CMS plus lourd avec des ACL par document et intégrez prudemment avec les agents.

Le point stratégique : unifier la vérité humaine et la vérité des agents

La plupart des équipes construisent par accident deux graphes de connaissances : un pour les humains (belles pages) et un pour les machines (index et prompts). C’est là que naissent les hallucinations et la dérive. Un wiki en texte brut adossé à Git réduit cette distance. Les humains proposent et revoient ; les agents citent et ouvrent des PR. Tout le monde voit la même vérité, avec les mêmes garde‑fous, via le même workflow auquel vous faites déjà confiance pour le code.

À retenir

• Texte brut + Git offrent auditabilité, vitesse et compatibilité LLM sans acheter une plateforme supplémentaire.
• Gardez secrets et PII hors du wiki ; classez les docs et contrôlez par répertoire avec CODEOWNERS et des branches protégées.
• Utilisez une pile de recherche hybride (lexical + vectoriel) alimentée par une ingestion sensible aux diffs ; visez un retrieval <200 ms.
• Contraignez les agents à citer leurs sources et à soumettre des PR ; ne les laissez jamais committer sur main.
• Mesurez couverture et fraîcheur, ajoutez des sondes de dérive et transformez les recherches en échec en docs à chaque sprint.
• Commencez par les runbooks et limites Tier 0 ; atteignez 90 % de couverture en 60–90 jours sans perturber la livraison.