Système de documentation auto-entretenu utilisant des blocs délimités pour un décalage zéro

Un développeur sur r/ClaudeAI a partagé une solution pour maintenir une documentation précise dans des espaces de travail multi-projets où les agents d'IA de codage comme Claude Code oublient le contexte entre les sessions. Le système résout des problèmes avec 8 projets, 20 fonctions Lambda, 42 clés API, 12 points de terminaison d'API et 19 variables d'environnement où l'agent devinait les noms de fonctions, modifiait les mauvais fichiers et perdait le contexte.

Le système de délimitation

Au lieu de demander à Claude de mettre à jour la documentation après l'implémentation, le développeur a créé un script bash de 740 lignes qui extrait des données structurées directement des fichiers sources et les injecte dans CLAUDE.md via des blocs de commentaires HTML délimités. Chaque CLAUDE.md a des délimitations marquant les sections générées automatiquement :

## Fonctions Serverless <!-- auto:lambdas generated="2026-03-26" source="infrastructure/lib/api-stack.ts" -->
| Fonction | Route | Mémoire | Délai d'expiration |
|----------|-------|--------|---------|
| quote-save | /quotes/save | 256MB | 15s |
| quote-get | /quotes/get | 256MB | 15s |
...20 lignes extraites de la configuration CDK...
<!-- /auto:lambdas -->

## Architecture <-- écrit à la main, jamais modifié par le script

Comment ça marche

Le script :

• Analyse les fichiers sources réels (CDK TypeScript, FastAPI Python, package.json, etc.)
• Extrait des données structurées (noms de fonctions, routes, variables d'environnement, versions des dépendances)
• Remplace tout ce qui se trouve entre les délimitations
• Met à jour la date de génération pour indiquer la fraîcheur
• Valide : vérifie que chaque nom de Lambda a un fichier gestionnaire correspondant, que chaque variable d'environnement existe dans .env

Les sections écrites à la main (descriptions de l'architecture, pièges, contexte de la logique métier) se trouvent en dehors des délimitations et ne sont jamais modifiées.

Contenu généré automatiquement

• Outil de citation (20 Lambdas) : Inventaire des Lambdas, piles CDK, variables d'environnement, nombre de tests, dépendances extraites de CDK TypeScript et package.json
• Tableau de bord des ventes (12 points de terminaison) : Routes d'API, liste des thèmes, dépendances extraites des décorateurs FastAPI, types TypeScript et requirements.txt
• Analyse de données (42 utilisateurs) : Données utilisateur, dépendances extraites du fichier d'identification Python et de requirements.txt
• 5 autres projets : Versions des dépendances extraites de package.json/requirements.txt

Système d'avertissement d'obsolescence

Un crochet de synchronisation de documentation (déclenché après chaque modification de code) vérifie la date de génération sur chaque délimitation. Si une section est plus ancienne que 7 jours :

Avertissement : 3 sections générées automatiquement dans agent-quoting-tool/CLAUDE.md sont obsolètes (la plus ancienne : 2026-03-19).
Exécutez : ./scripts/generate-inventory.sh quoting

Ceci est non bloquant — avertit mais n'empêche jamais de travailler. La vérification d'obsolescence s'exécute parallèlement aux crochets existants avec la même fenêtre de limitation de 10 minutes, sans surcharge supplémentaire.

Détails d'implémentation

La configuration utilise uniquement bash avec grep/sed/awk/jq, zéro dépendance. Commandes :

scripts/generate-inventory.sh all # Tout rafraîchir
scripts/generate-inventory.sh quoting # Un seul projet

Le script sauvegarde d'abord chaque CLAUDE.md (une sauvegarde par jour, par projet). Le développeur note de ne pas analyser les AST depuis bash — leur analyseur TypeScript est une boucle grep/sed ligne par ligne qui fonctionne pour des fichiers contrôlés mais serait fragile pour du TypeScript arbitraire.

Principales observations

Les délimitations permettent au contenu généré automatiquement et au contenu écrit à la main de coexister dans le même fichier. Claude lit l'intégralité de CLAUDE.md au début de la session et obtient les deux : des données extraites précises ET un contexte humain qu'il ne peut pas déduire du code. Le développeur recommande de commencer par les extractions à plus forte valeur (inventaires Lambda et tableaux de variables d'environnement qui causent des bugs lorsqu'ils divergent) et note que l'avertissement d'obsolescence est plus précieux que l'exécution automatique.

L'ensemble du système a pris environ 3 heures à construire (conception, implémentation, tests, première exécution).