Communitygithub.com

Rune-kit/rune

Génère et maintient automatiquement la documentation de projet. Crée des README, des documentations API, des documentations d'architecture, des journaux de modifications et les maintient synchronisés avec les changements de code. La compétence « la documentation n'est jamais obsolète ».

Qu'est-ce que rune ?

Cette compétence, nommée « docs » dans le kit Rune, agit comme un gestionnaire de cycle de vie de la documentation. Elle résout le problème numéro un de la documentation : des documents qui existent mais qui sont obsolètes. La compétence génère initialement la documentation d'un projet (README, ARCHITECTURE.md, API.md, CHANGELOG) en se basant strictement sur le code existant, puis la maintient à jour de manière incrémentielle via un mode de mise à jour qui détecte les modifications dans le code grâce à git diff. Elle est déclenchée par d'autres compétences comme `scaffold`, `cook` et `launch`, ou directement par l'utilisateur via des commandes `/rune docs`. La compétence analyse le code source pour extraire les routes API, les configurations, les composants et la structure du projet, et génère une documentation précise et traçable. Elle effectue également une vérification de cohérence entre les documents pour éviter les contradictions, corrigeant automatiquement les incohérences. L'aspect le plus critique est le respect de la règle « ne pas inventer » : chaque affirmation dans la documentation doit être traçable jusqu'à un fichier, une fonction ou une configuration spécifique dans le code. La compétence utilise différents modes (init, update, api, changelog) pour répondre à des besoins spécifiques à différentes étapes du cycle de développement.

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Rune-kit/rune/tree/HEAD/skills/docs

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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 scaffold pour la génération initiale de documentation
  • Appelé par cook après la phase 7 pour mettre à jour la documentation après l'implémentation de fonctionnalités
  • Appelé par launch avant 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 projet
  • cook (L1) : après implémentation — mise à jour de la documentation pour les modules modifiés
  • launch (L1) : avant déploiement — vérification que la documentation est à jour
  • mcp-builder (L2) : génération de documentation du serveur MCP
  • Utilisateur : /rune docs invocation 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 :

  1. Lire le code modifié
  2. Trouver la section de documentation correspondante
  3. Mettre à jour la documentation pour qu'elle corresponde au code actuel
  4. Si la section de documentation n'existe pas → la créer
  5. 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érificationFichiersÉléments à Comparer
Numéros de versionREADME, CLAUDE.md, package.json, CHANGELOGDoivent tous correspondre à la version actuelle
Listes de fonctionnalitésREADME, page d'accueil, CLAUDE.mdMêmes fonctionnalités listées (peuvent différer en niveau de détail)
StatistiquesREADME, CLAUDE.md, page d'accueil, tableau de bordLe nombre de compétences, le nombre de tests, le nombre de signaux doivent correspondre
CommandesREADME, CLAUDE.md, docs/Mêmes commandes avec les mêmes options
Pile technologiqueREADME, ARCHITECTURE.md, CLAUDE.mdRé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

FrameworkModèle de RouteModèle de Fichier
Expressrouter.get/post/put/deleteroutes/*.ts, *.router.ts
FastAPI@app.get/post/put/deleterouters/*.py, main.py
NestJS@Get/@Post/@Put/@Delete*.controller.ts
Next.js Appexport async function GET/POSTapp/**/route.ts
Next.js Pagesexport default function handlerpages/api/**/*.ts
SvelteKitexport function GET/POSTsrc/routes/**/+server.ts
Honoapp.get/post/put/deletesrc/*.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.

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Skills associés