Que fait Générateur de README ?
Créez des fichiers README.md soignés et complets pour les dépôts de code internes/d'entreprise en analysant le code existant et en posant des questions ciblées.
Pourquoi cette compétence existe
Un bon README est la porte d’entrée d’un code. Pour les projets internes surtout, un README absent ou trop succinct signifie que chaque nouveau membre de l’équipe perd des heures à comprendre ce que fait le projet, comment l’exécuter et où chercher. Cette compétence automatise le gros du travail — elle lit le code, en déduit ce qu’elle peut, demande ce qu’elle ne peut pas déterminer, et produit un README qui rend les développeurs productifs rapidement.
Workflow
Étape 1 : Analyser le code source
Avant de demander quoi que ce soit à l’utilisateur, exécutez une analyse structurée en quatre phases pour rassembler un maximum de contexte. Cela réduit la charge sur l’utilisateur — il ne doit combler que les lacunes, pas décrire ce que vous pouvez déjà voir.
Attribuez à chaque fait un niveau de confiance : [confirmé] (lu dans le source), [inféré-élevé] (preuve forte), [inféré-faible] (preuve partielle), ou [inconnu]. Les trouvailles à faible confiance ou inconnues deviendront des questions de clarification à l’étape 2.
Voir references/analysis-phases.md pour les actions d’outil détaillées, les motifs grep, les listes de vérification d’extraction et les modèles d’enregistrement.
Phase 1 — Analyse des métadonnées du projet : Recherchez globalement les fichiers de gestionnaire de paquets (pyproject.toml, package.json, etc.), les modèles d’env, les Dockerfiles, les configurations CI/CD et les fichiers de chaîne d’outils. Lisez chacun et extrayez : nom/version du projet, langage, dépendances (catégorisées avec leurs rôles), scripts/commandes, variables d’environnement (obligatoires vs optionnelles), étapes CI, licence.
Phase 2 — Analyse de l’architecture : Recherchez globalement tous les fichiers source pour mapper la structure des répertoires. Greppez les marqueurs de point d’entrée (if __name__, main(), etc.) et lisez chaque point d’entrée. Construisez le graphe d’importation en grepant les instructions d’importation dans tous les fichiers source — classez les modules en cœur (fort degré entrant), feuilles ou orchestrateurs. Identifiez le motif architectural (pipeline, MVC, en couches, microservices, événementiel, CLI, monolithe) à l’aide de la liste de vérification des indicateurs. Greppez les motifs de chargement de configuration pour trouver les fichiers de configuration runtime.
Phase 3 — Analyse approfondie des modules : Lisez chaque fichier source significatif (priorité : cœur → point d’entrée → plus volumineux → reste). Pour chacun, extrayez : le rôle (une phrase), les exports clés avec signatures, les notes de conception (décisions non évidentes, cas particuliers, conventions), et les dépendances internes. Tracez le flux de travail principal de bout en bout à travers le graphe d’importation, en étiquetant les types de données qui circulent entre les modules. Pour les codes avec 8 fichiers source ou plus, distribuez des sous-agents parallèles regroupés par clusters de dépendances.
Phase 4 — Analyse de l’infrastructure de support : Recherchez globalement les fichiers de test et les fixtures. Lisez les 30 à 50 premières lignes de chaque fichier de test pour établir une correspondance test-à-module. Greppez les classes d’exception personnalisées et les instructions raise pour cartographier la hiérarchie des erreurs. Analysez les modèles, ressources et documents existants. Extrayez les scénarios d’erreur courants pour le tableau de dépannage.
Étape 2 : Poser des questions de clarification
Après l’analyse, demandez à l’utilisateur ce que vous n’avez pas pu déduire avec confiance. Restez ciblé — ne posez pas de questions sur des choses que vous savez déjà. Les lacunes courantes incluent :
- Objectif du projet : Quel problème cela résout-il ? Qui l’utilise ? (si pas évident à partir du code)
- Pièges de configuration : Y a-t-il des prérequis non évidents, des exigences VPN, des registres de paquets internes ou des étapes de configuration de base de données ?
- Flux de travail clés : Quelles sont les 2-3 choses qu’un développeur fait le plus souvent avec ce projet ?
- Déploiement : Comment/où cela est-il déployé ? (si pas clair à partir des configurations CI/CD)
- Conventions d’équipe : Y a-t-il des conventions de nommage, des stratégies de branche ou des modèles à signaler ?
- Contact : Qui possède/mainient ce projet ? (nom + email pour la section Contact)
Présentez vos questions de manière concise. Si le code est simple et que vous êtes confiant dans votre analyse, vous n’aurez besoin que de 1-2 questions — voire aucune. Faites preuve de discernement.
Étape 3 : Générer le README.md
Rédigez le README en utilisant la structure et les directives ci-dessous.
Structure du README
Utilisez ceci comme modèle. Incluez toutes les sections, mais adaptez la profondeur à la complexité du projet. Utilisez des règles horizontales --- entre chaque section principale pour une respiration visuelle.
# Nom du Projet
  
Description brève et claire. Utilisez **gras** pour mettre en évidence la technologie clé ou le type de produit.
---
## Table des Matières
Générez une table des matières imbriquée et complète qui inclut TOUS les titres ## et ###. Indentez les sous-sections sous leurs parents pour que les lecteurs puissent voir la structure complète d’un coup d’œil. C’est particulièrement important pour les README longs — la TdM sert à la fois d’outil de navigation et de plan du document entier.
Exemple de la profondeur attendue :
- [Aperçu](#aperçu)
- [Architecture](#architecture)
- [Architecture de Haut Niveau](#architecture-de-haut-niveau)
- [Structure des Dossiers](#structure-des-dossiers)
- [Graphe des Dépendances des Modules](#graphe-des-dépendances-des-modules)
- [Pour Commencer](#pour-commencer)
- [Prérequis](#prérequis)
- [Installation](#installation)
- [Exécution des Tests](#exécution-des-tests)
- [Variables d’Environnement](#variables-denvironnement)
- [Utilisation](#utilisation)
- [Exemple : Cas d’Utilisation Principal](#exemple-cas-dutilisation-principal)
- [Exemple : Cas d’Utilisation Secondaire](#exemple-cas-dutilisation-secondaire)
- [Référence API](#référence-api)
- [Ressource A](#ressource-a)
- [Ressource B](#ressource-b)
- [Dépannage](#dépannage)
- [Contact](#contact)
- [Licence](#licence)
Chaque titre ### dans le document doit apparaître comme une entrée indentée sous son titre ## parent. Ne sautez pas de sous-sections — tout l’intérêt d’une TdM complète est que les lecteurs peuvent accéder directement à n’importe quelle partie du document.
---
## Aperçu
Développez la description. Mettez en gras les termes clés. Utilisez des listes numérotées pour les processus en plusieurs étapes.
---
## Architecture
### Architecture de Haut Niveau
```mermaid
graph TD
...
```
Structure des Dossiers
dossier-racine/
├── src/ # Brève annotation
├── tests/ # Brève annotation
└── ...
[Flux de Données / Pipeline / Dépendances des Modules — diagrammes supplémentaires]
...
Pour Commencer
Prérequis
Installation
Exécution des Tests
Variables d’Environnement
| Variable | Requise | Description |
|---|---|---|
DB_URL | Oui | Chaîne de connexion PostgreSQL |
Utilisation
Exemples de code réels pour les 2-3 opérations les plus courantes.
Référence API
Dépannage
| Symptôme | Cause Probable | Correction |
|---|---|---|
message d’erreur | Quel est le problème | Comment le résoudre |
Contact
Pour toute question ou assistance, contactez :
- Nom — [email protected]
Licence
Usage Interne Uniquement – Nom de l’Entreprise Logiciel propriétaire. © [Année] [Entreprise]. Tous droits réservés.
## Badges Shields.io
Incluez toujours des badges shields.io juste après le titre `# Titre` (3 à 6 badges couvrant le langage, le framework, la bibliothèque clé, le gestionnaire de paquets, la base de données, l’infrastructure). Voir [references/badge-reference.md](references/badge-reference.md) pour le format, les exemples et les suggestions de couleurs par catégorie.
## Directives pour les Diagrammes Mermaid
Utilisez généreusement les diagrammes Mermaid — ils rendent l’architecture, les flux de données et les processus immédiatement compréhensibles. Un README typique devrait contenir **3 à 6 diagrammes** ; les projets complexes (pipelines de données, systèmes multi-services) peuvent en avoir **6 à 10 ou plus**. Voir [references/mermaid-guidelines.md](references/mermaid-guidelines.md) pour savoir quand utiliser chaque type de diagramme, les bonnes pratiques et les recommandations spécifiques au type de projet.
## Directives de Rédaction
- **Soyez spécifique plutôt que générique.** « Exécutez `npm run dev` » vaut mieux que « Démarrez le serveur de développement. » Incluez les commandes réelles, les chemins de fichiers et les noms de variables.
- **Écrivez pour le nouveau membre de l’équipe.** Supposez des compétences générales en ingénierie mais aucun contexte sur le projet.
- **Mettez en gras les termes clés et les noms de produits** lors de la première mention et dans les aperçus. Cela aide les lecteurs à scanner.
- **Utilisez des listes numérotées pour les processus séquentiels.** « 1. **Extrait** les données de X. 2. **Transforme** ces données. 3. **Charge** dans Y. » — mettez le verbe en gras.
- **Les exemples de code doivent être exécutables.** Copiez depuis le code source réel lorsque c’est possible.
- **Les tableaux de variables d’environnement sont non négociables.** Listez chaque variable.
- **Dépannage sous forme de tableau** (Symptôme | Cause Probable | Correction) — lisible et cohérent.
- **Les annotations de la structure des dossiers doivent être brèves.** Une courte phrase par répertoire.
- **Incluez toujours une section Contact.** Demandez à l’utilisateur qui maintient le projet. Format : `**Nom** — [email protected]`.
- **Utilisez des règles horizontales `---`** entre toutes les sections principales pour une structure visuelle.
## Sortie
Sauvegardez le README sous le nom `README.md` dans la racine du dépôt (ou le répertoire de travail courant si aucune racine de dépôt n’est identifiable). Si un fichier `README.md` existe déjà, confirmez avec l’utilisateur avant d’écraser — il pourrait vouloir en conserver des parties.