docs
Objectif
Gestionnaire du cycle de vie de la documentation. Génère la documentation initiale du projet, maintient la documentation synchronisée avec les modifications du code, produit des références API et génère automatiquement les journaux de modifications. Résout le problème n°1 de la documentation : des documents qui existent mais sont obsolètes.
Déclencheurs
- Appelé par la phase 7 de
scaffoldpour la génération initiale de documentation - Appelé par
cookaprès la phase 7 pour mettre à jour la documentation après l'implémentation de fonctionnalités - Appelé par
launchavant le déploiement pour s'assurer que la documentation est à jour /rune docs init— génération de documentation pour la première fois/rune docs update— synchronisation de la documentation avec les modifications récentes du code/rune docs api— génération de documentation API/rune docs changelog— génération automatique du journal des modifications à partir de l'historique git
Appels (sortants)
scout(L2) : analyse du codebase pour trouver les cibles de documentation (routes, exports, composants, configurations)doc-processor(L3) : génération d'exportations PDF/DOCX si demandégit(L3) : lecture de l'historique des commits pour la génération du journal des modifications
Appelé Par (entrants)
scaffold(L1) : Phase 7 — génération de la documentation initiale pour un nouveau projetcook(L1) : après implémentation — mise à jour de la documentation pour les modules modifiéslaunch(L1) : avant déploiement — vérification que la documentation est à jourmcp-builder(L2) : génération de documentation du serveur MCP- Utilisateur :
/rune docsinvocation directe
Modes
Mode Init — /rune docs init
Génération de documentation pour la première fois pour un projet.
Mode Update — /rune docs update
Synchronisation incrémentielle — mise à jour uniquement de la documentation affectée par les modifications récentes du code.
Mode API — /rune docs api
Génération ou mise à jour de la documentation API spécifiquement.
Mode Changelog — /rune docs changelog
Génération automatique du journal des modifications à partir de l'historique des commits git.
Étapes Exécutables
Mode Init
Étape 1 — Analyser le Codebase
Invoquer rune:scout pour extraire :
- Nom du projet, description, pile technologique
- Structure des répertoires et fichiers clés
- Points d'entrée (main, index, app)
- Surface API publique (exports, routes, composants)
- Fichiers de configuration (.env.example, modèles de configuration)
- Documentation existante (le cas échéant — fusionner, ne pas écraser)
Étape 2 — Générer README.md
Structure :
# [Nom du projet]
[Description en une ligne]
## Démarrage rapide
[3 à 5 commandes pour démarrer : installer, configurer, lancer]
## Fonctionnalités
[Liste à puces extraite du code — routes, composants, capacités]
## Pile technologique
[Détecté à partir de package.json, requirements.txt, Cargo.toml, etc.]
## Structure du projet
[Répertoires clés avec descriptions en une ligne]
## Configuration
[Variables d'environnement de .env.example avec descriptions]
## Développement
[Commandes de serveur de développement, test, lint, build]
## Référence API
[Lien vers API.md si applicable, ou résumé en ligne]
## Licence
[Détecté à partir du fichier LICENSE ou de package.json]
Étape 3 — Générer ARCHITECTURE.md (si le projet a 10 fichiers ou plus)
Structure :
# Architecture
## Aperçu
[Diagramme système en texte/mermaid — composants et flux de données]
> L'aperçu ARCHITECTURE peut appeler `rune:diagram` pour une figure système conçue (type `architecture`) au lieu de Mermaid brut — `suggested_next: diagram`.
## Décisions Clés
[Modèles détectés : choix du framework, gestion d'état, base de données, approche d'authentification]
## Carte des Modules
[Chaque répertoire de premier niveau : objectif, fichiers clés, dépendances]
## Flux de Données
[Description du cycle de vie d'une requête ou du pipeline de données]
Étape 4 — Générer API.md (si des routes/points de terminaison sont détectés)
Analyser les fichiers de route et extraire :
- Méthode HTTP + chemin
- Paramètres de requête (chemin, requête, corps)
- Format de la réponse
- Exigences d'authentification
- Réponses d'erreur
Formater comme un tableau markdown ou une référence compatible OpenAPI.
Étape 5 — Rapport
Présenter à l'utilisateur les documents générés avec un résumé :
- Fichiers générés : [liste]
- Couverture : [ce qui est documenté par rapport à ce qui existe]
- Lacunes : [zones de code sans documentation — suggérer les étapes suivantes]
Mode Update
Étape 1 — Détecter les Modifications
Lire git diff depuis la dernière mise à jour de la documentation (suivi via le journal git des fichiers de documentation ou .rune/docs-sync.json).
Identifier :
- Nouveaux fichiers/modules → besoin de nouvelles sections de documentation
- Fonctions/routes modifiées → besoin de mises à jour de la documentation
- Code supprimé → besoin de suppression de la documentation
- Nouvelle configuration → besoin de mise à jour de la documentation de configuration
Étape 2 — Mettre à Jour les Sections Affectées
Pour chaque zone modifiée :
- Lire le code modifié
- Trouver la section de documentation correspondante
- Mettre à jour la documentation pour qu'elle corresponde au code actuel
- Si la section de documentation n'existe pas → la créer
- Si le code a été supprimé → supprimer ou marquer comme obsolète dans la documentation
Étape 3 — Générer une Entrée de Journal des Modifications
Déléguer à rune:git changelog pour produire une entrée de journal des modifications à partir des commits depuis la dernière mise à jour de la documentation.
Étape 4 — Vérification de Cohérence Inter-Document
La cohérence inter-document évite le deuxième problème de documentation le plus courant : des documents qui existent mais se contredisent mutuellement.
Après avoir mis à jour un document, vérifier la cohérence dans toute la documentation du projet :
| Vérification | Fichiers | Éléments à Comparer |
|---|---|---|
| Numéros de version | README, CLAUDE.md, package.json, CHANGELOG | Doivent tous correspondre à la version actuelle |
| Listes de fonctionnalités | README, page d'accueil, CLAUDE.md | Mêmes fonctionnalités listées (peuvent différer en niveau de détail) |
| Statistiques | README, CLAUDE.md, page d'accueil, tableau de bord | Le nombre de compétences, le nombre de tests, le nombre de signaux doivent correspondre |
| Commandes | README, CLAUDE.md, docs/ | Mêmes commandes avec les mêmes options |
| Pile technologique | README, ARCHITECTURE.md, CLAUDE.md | Références cohérentes au framework/bibliothèque |
Cohérence Inter-Document :
- [x] README.md ↔ CLAUDE.md : versions correspondent, commandes correspondent
- [x] README.md ↔ docs/index.html : statistiques correspondent, fonctionnalités correspondent
- [ ] README.md indique « 62 compétences » mais CLAUDE.md indique « 59 » → CORRIGER CLAUDE.md
Corriger les incohérences immédiatement — ne pas se contenter de les signaler. Mettre à jour le document obsolète pour correspondre à la source de vérité (généralement le code ou le document le plus récemment mis à jour).
Étape 5 — Rapport
Montrer à l'utilisateur : ce qui a été mis à jour, ce qui a été ajouté, ce qui a été signalé pour révision. Inclure les résultats de la Cohérence Inter-Document.
Mode API
Étape 1 — Détecter le Framework API
| Framework | Modèle de Route | Modèle de Fichier |
|---|---|---|
| Express | router.get/post/put/delete | routes/*.ts, *.router.ts |
| FastAPI | @app.get/post/put/delete | routers/*.py, main.py |
| NestJS | @Get/@Post/@Put/@Delete | *.controller.ts |
| Next.js App | export async function GET/POST | app/**/route.ts |
| Next.js Pages | export default function handler | pages/api/**/*.ts |
| SvelteKit | export function GET/POST | src/routes/**/+server.ts |
| Hono | app.get/post/put/delete | src/*.ts |
Étape 2 — Extraire les Points de Terminaison
Pour chaque route détectée :
- Méthode (GET, POST, PUT, DELETE, PATCH)
- Chemin (avec paramètres en évidence)
- Requête : paramètres, requête, forme du corps (à partir de schémas Zod, types TypeScript, modèles Pydantic)
- Réponse : forme (à partir du type de retour ou du helper de réponse)
- Authentification : requise ? (détecter le middleware comme
authMiddleware,@UseGuards) - Description : à partir de JSDoc/docstring si disponible
Étape 3 — Générer la Référence API
Formater en markdown :
# Référence API
## Authentification
[Description du mécanisme d'authentification]
## Points de Terminaison
### `POST /api/auth/login`
**Description**: Authentifier l'utilisateur et renvoyer les jetons
**Authentification**: Aucune
**Corps de la Requête**:
| Champ | Type | Requis | Description |
|-------|------|--------|-------------|
| email | string | oui | Email de l'utilisateur |
| password | string | oui | Mot de passe de l'utilisateur |
**Réponse** (200):
```json
{ "token": "string", "refreshToken": "string" }
Erreurs:
- 401 : Identifiants invalides
- 422 : Erreur de validation
#### Étape 4 — Sortie
Enregistrer dans `docs/API.md` ou un emplacement spécifique au projet. Si OpenAPI est demandé, générer `openapi.yaml`.
### Mode Changelog
#### Étape 1 — Déléguer à Git
Invoquer `rune:git changelog` pour regrouper les commits par type et les formater selon Keep a Changelog.
#### Étape 2 — Enrichir
Ajouter du contexte au journal brut :
- Lier les numéros de PR aux descriptions réelles
- Regrouper les modifications connexes sous des en-têtes de fonctionnalités
- Mettre en évidence les modifications importantes de manière proéminente
#### Étape 3 — Sortie
Ajouter ou mettre à jour `CHANGELOG.md`.
## Format de Sortie
### Sortie du Mode Init
Fichiers générés à la racine du projet :
- `README.md` — Démarrage rapide, Fonctionnalités, Pile technologique, Structure, Config, Commandes de développement
- `ARCHITECTURE.md` — Diagramme d'aperçu, Décisions clés, Carte des modules, Flux de données (si 10 fichiers ou plus)
- `docs/API.md` — Référence des points de terminaison avec méthode, chemin, paramètres, réponse, authentification (si des routes sont détectées)
### Sortie du Mode Update
Sections de documentation modifiées avec résumé des modifications :
Rapport de Mise à Jour de la Documentation :
- Mis à jour : [liste des sections de documentation modifiées]
- Ajouté : [nouvelles sections pour le nouveau code]
- Signalé : [sections obsolètes faisant référence à du code supprimé]
- Journal des modifications : [entrée ajoutée à CHANGELOG.md]
### Sortie du Mode API
`docs/API.md` — référence markdown par point de terminaison :
METHOD /path/:param
Description: [à partir de JSDoc/docstring] Authentification: [requise/aucune] Requête: [tableau des paramètres, requête, corps] Réponse: [forme avec codes de statut] Erreurs: [codes d'erreur et descriptions]
### Sortie du Mode Changelog
`CHANGELOG.md` — format Keep a Changelog regroupé par : Ajouté, Corrigé, Modifié, Supprimé.
## Contraintes
1. DOIT générer la documentation à partir du code réel — ne jamais inventer de fonctionnalités ou d'API qui n'existent pas
2. DOIT préserver la documentation existante — mettre à jour les sections, ne pas écraser les fichiers entiers
3. DOIT détecter l'obsolescence de la documentation — signaler les sections qui font référence à du code supprimé/modifié
4. DOIT inclure un Démarrage rapide dans chaque README — les utilisateurs doivent pouvoir démarrer en moins de 2 minutes
5. NE DOIT PAS générer de documentation pour du code qui n'existe pas encore (sauf s'il s'agit explicitement de créer des documents de spécification)
6. La documentation API DOIT correspondre aux signatures réelles des routes — une documentation API incorrecte est pire que pas de documentation du tout
## Retours
| Artefact | Format | Emplacement |
|----------|--------|-------------|
| README.md | Markdown | racine du projet |
| ARCHITECTURE.md | Markdown | racine du projet (si 10 fichiers ou plus) |
| Référence API | Markdown | `docs/API.md` |
| Entrée du journal des modifications | Markdown (Keep a Changelog) | `CHANGELOG.md` |
| Rapport de mise à jour de la documentation | Markdown | en ligne (sortie du chat) |
**Barrière de périmètre :** Documente uniquement ce qui existe dans le codebase — n'invente jamais de fonctionnalités, de points de terminaison ou d'API.
## Angles Morts
| Mode de défaillance | Gravité | Atténuation |
|---|---|---|
| Inventer des points de terminaison API qui n'existent pas | CRITIQUE | Contrainte 1 : analyser les fichiers de route réels, pas deviner |
| Écraser les sections README écrites par l'utilisateur | ÉLEVÉE | Contrainte 2 : fusionner, ne pas écraser — détecter les sections personnalisées |
| Documentation obsolète après des modifications du code | ÉLEVÉE | Le mode Update détecte les différences et met à jour les sections affectées |
| Documentation API avec des formes de requête/réponse erronées | ÉLEVÉE | Extraire des types Zod/Pydantic/TypeScript, pas de la mémoire |
| Section Démarrage rapide manquante | MOYENNE | Contrainte 4 : chaque README a un Démarrage rapide |
| Journal des modifications avec des liens PR orphelins | FAIBLE | Valider que les numéros de PR existent avant de créer des liens |
| Incohérence inter-document (README dit X, CLAUDE.md dit Y) | ÉLEVÉE | Étape 7 : Vérification de Cohérence Inter-Document — vérifier que les statistiques, les versions et les listes de fonctionnalités correspondent dans tous les documents |
| Mettre à jour un document mais pas les autres (dérive des statistiques) | ÉLEVÉE | Après toute mise à jour de documentation, parcourir tous les documents connexes pour les statistiques obsolètes — en particulier README ↔ CLAUDE.md ↔ page d'accueil |
## Terminé Quand
### Mode Init
- Codebase analysé avec scout
- README.md généré avec Démarrage rapide, Fonctionnalités, Pile technologique, Structure
- ARCHITECTURE.md généré (si 10 fichiers ou plus)
- API.md généré (si des routes sont détectées)
- Rapport de couverture présenté à l'utilisateur
### Mode Update
- Modifications depuis la dernière mise à jour de la documentation détectées
- Sections de documentation affectées mises à jour
- Entrée du journal des modifications générée
- Rapport de mise à jour présenté à l'utilisateur
### Mode API
- Framework API détecté
- Tous les points de terminaison extraits avec méthode, chemin, requête, réponse
- Référence API générée en markdown
- Enregistrée dans docs/API.md
### Mode Changelog
- Commits regroupés par type
- Formaté selon Keep a Changelog
- CHANGELOG.md mis à jour
## Profil de Coût
~2000-5000 tokens en entrée, ~1000-3000 tokens en sortie. Sonnet — la documentation nécessite une compréhension des modèles de code mais pas un raisonnement architectural approfondi.