Générateur de guides d'intégration Wiki

Générez quatre documents d’intégration adaptés à différents publics dans un dossier « onboarding/ », chacun fournissant à une partie prenante différente exactement les informations dont elle a besoin.

Définition du référentiel source (À FAIRE EN PREMIER)

Avant de générer le moindre guide, vous DEVEZ déterminer le contexte du dépôt source :

1. Vérification de l’existence d’un dépôt distant Git: exécutez la commande ` git remote get-url origin ` pour détecter si un dépôt distant existe
2. Demandez à l’utilisateur: « S’agit-il d’un dépôt uniquement local, ou disposez-vous d’une URL de dépôt source (par exemple, GitHub, Azure DevOps) ? »
   • URL distante fournie → enregistrez-la sous le nom REPO_URL, utilisez des citations liées: [fichier:ligne](REPO_URL/blob/BRANCH/fichier#Lligne)
   • Référentiel local uniquement → utilisez des citations locales: (chemin_fichier:numéro_de_ligne)
3. Déterminer la branche par défaut: exécuter la commande git rev-parse --abbrev-ref HEAD
4. NE PAS continuer tant que le contexte du dépôt source n’est pas résolu

Quand l’activer

• L'utilisateur demande des documents d'intégration ou des guides de démarrage
• L'utilisateur exécute la commande /deep-wiki:onboard
• L'utilisateur souhaite aider les nouveaux membres de l'équipe à comprendre une base de code

Structure de sortie

Générer un dossier « onboarding/ » contenant les fichiers suivants :

onboarding/
├── index.md                    # Centre d’intégration — liens vers les 4 guides avec description du public cible
├── contributor-guide.md        # Pour les nouveaux contributeurs (suppose des connaissances en Python ou JS)
├── staff-engineer-guide.md     # Destiné aux ingénieurs seniors et principaux
├── executive-guide.md          # Destiné aux responsables techniques de niveau vice-président ou directeur
└── product-manager-guide.md    # Destiné aux chefs de produit et aux parties prenantes non techniques

index.md — Centre d'intégration

Une page d’accueil comprenant :

• Un résumé du projet en un paragraphe
• Tableau de sélection des guides:

Détection du langage

Analyse du référentiel à la recherche de fichiers de compilation afin de déterminer le langage principal des exemples de code :

• package.json / tsconfig.json → TypeScript/JavaScript
• *.csproj / *.sln → C# / .NET
• Cargo.toml → Rust
• pyproject.toml / setup.py / requirements.txt → Python
• go.mod → Go
• pom.xml / build.gradle → Java

Guide 1 : Guide du contributeur

Fichier: onboarding/contributor-guide.md Public visé: les ingénieurs rejoignant le projet. Ce guide suppose une maîtrise de Python ou de JavaScript ainsi qu'une expérience générale en génie logiciel. Longueur: 1 000 à 2 500 lignes. Progressif : chaque section s'appuie sur la précédente.

Sections obligatoires

Partie I : Bases (à ignorer si le dépôt utilise Python ou JS)

1. {Langage principal} pour les ingénieurs Python/JS — Tableaux comparatifs de syntaxe, modèle asynchrone, collections, système de types, gestion des paquets. Exemples de code concrets présentés en parallèle, PAS de descriptions abstraites.
2. Les fondamentaux de {framework principal} — Comparaison avec des frameworks Python/JS équivalents (par ex. FastAPI, Express). Pipeline de requêtes, routage, injection de dépendances (DI), configuration.

Partie II : Cette base de code 3. Objectif du projet — Présentation concise en 2 à 3 phrases 4. Structure du projet — Arborescence des répertoires annotée (où se trouve quoi et pourquoi). Inclure un aperçu graphique de l’architecture en base de données. 5. Concepts fondamentaux — Terminologie spécifique au domaine expliquée à l’aide d’exemples de code. Utilisez un diagramme E/S pour le modèle de données. 6. Cycle de vie d’une requête — Diagramme de séquence (avec numérotation automatique) retraçant une requête type de bout en bout. 7. Modèles clés — Modèles du type « Si vous souhaitez ajouter X, suivez ce modèle » accompagnés de code réel

Partie III : Devenir productif 8. Prérequis et configuration — Tableau : outil, version, commande d’installation. Procédure étape par étape avec le résultat attendu à chaque étape. 9. Votre première tâche — Guide pas à pas de l’ajout d’une fonctionnalité simple 10. Workflow de développement — Stratégie de branches, conventions de commit, processus de PR. Utilisation d’un organigramme. 11. Exécution des tests — Tous les tests, fichier unique, test unique, commandes de couverture 12. Guide de débogage — Tableau des problèmes courants : symptôme, cause, solution 13. Pièges courants — Erreurs commises par tous les nouveaux contributeurs et comment les éviter

Annexes

• Glossaire (plus de 40 termes)
• Référence des fichiers clés — Tableau : chemin d’accès, objectif, importance, source
• Fiche de référence rapide — Aide-mémoire des commandes et modèles les plus utilisés

Règles

• Tous les exemples de code sont rédigés dans la langue principale détectée
• Chaque commande doit pouvoir être copiée-collée avec le résultat attendu
• Au moins 5 diagrammes Mermaid (architecture, ER, séquence, organigramme, états)
• Utilisez Mermaid pour les diagrammes de workflow (couleurs du mode sombre) — ajoutez bloc de commentaires après chaque
• Étayer toutes les affirmations par du code réel — citer en utilisant le format avec lien

Guide 2 : Guide de l'ingénieur senior

Fichier: onboarding/staff-engineer-guide.md Public cible: Ingénieurs seniors/principaux qui ont besoin de connaître le « pourquoi » derrière chaque décision. Expérience approfondie des systèmes, ne connaissent peut-être pas le langage de ce dépôt. Longueur: 800 à 1 200 lignes. Dense, tranché, axé sur l’architecture.

Sections obligatoires

1. Résumé exécutif — Description du système en un paragraphe concis. Ce qu’il gère en interne par rapport à ce qu’il délègue.
2. L’idée architecturale centrale — Le concept le plus important, et le SEUL qui compte. Inclure du pseudocode dans un langage DIFFÉRENT de celui du dépôt.
3. Architecture du système — Diagramme TB complet sous forme de graphe Mermaid. Mettez en évidence le « cœur » du système.
4. Modèle de domaine — Diagramme erDiagram Mermaid des entités principales. Tableau des invariants de données : Entité, Invariant, Imposé par, Source.
5. Abstractions et interfaces clés — Diagramme de classes illustrant les abstractions porteuses.
6. Cycle de vie des requêtes — Diagramme de séquence (avec numérotation automatique) illustrant le parcours type d’une requête, de son entrée jusqu’à la réponse.
7. Transitions d’états — Diagramme d’états (stateDiagram-v2) pour les entités présentant des états de cycle de vie significatifs.
8. Journal des décisions — Tableau : décision, alternatives envisagées, justification, source.
9. Justification des dépendances — Tableau : Dépendance, Objectif, Ce qu’elle a remplacé, Source.
10. Flux de données et états — Comment les données circulent dans le système. Tableau comparatif des modes de stockage.
11. Modes de défaillance et gestion des erreurs — organigramme illustrant les chemins de propagation des erreurs.
12. Caractéristiques de performance — goulots d'étranglement, limites d'évolutivité, chemins fréquents.
13. Modèle de sécurité — Authentification, autorisation, limites de confiance, sensibilité des données.
14. Stratégie de test — Ce qui est testé, ce qui ne l’est pas, philosophie des tests.
15. Dette technique connue — Tableau : problème, niveau de risque, fichiers concernés, source.
16. Où approfondir — Ordre de lecture recommandé des fichiers source, liens vers les sections du wiki.

Règles

• Utiliser du pseudocode dans un autre langage pour expliquer les concepts
• Utiliser des tableaux comparatifs pour mettre en correspondance des concepts peu familiers (par exemple, Tâche e = Awaitable[T])
• Prose dense accompagnée de tableaux, PAS de listes à puces superficielles
• Chaque affirmation doit être étayée par une référence avec lien
• Au moins 5 diagrammes Mermaid (architecture, ER, classes, séquences, états, organigrammes)
• Chaque diagramme doit être suivi d’un un bloc de commentaires
• Utilisez abondamment les tableaux: les décisions, les dépendances et la dette technique doivent TOUTES faire l’objet de tableaux comportant une colonne « Source »
• Mettez l’accent sur le POURQUOI des décisions, et pas seulement sur CE QUI existe

Guide n° 3 : Guide à l'intention des dirigeants

Fichier: onboarding/executive-guide.md Public cible: vice-président/directeur de l’ingénierie. A besoin d’une vue d’ensemble des capacités, d’une évaluation des risques et du contexte d’investissement — PAS de détails au niveau du code. Longueur: 400 à 800 lignes. Stratégique, concis, axé sur la prise de décision.

Sections obligatoires

1. Présentation du système — Ce qu’il fait, qui l’utilise, valeur métier en 2 à 3 phrases
2. Carte des capacités — Tableau : capacité, statut (implémentée/partielle/prévue), maturité, dépendances. Ce que le système peut et ne peut pas faire aujourd’hui.
3. Aperçu de l’architecture — Diagramme LR de type Mermaid de haut niveau. Services, magasins de données, intégrations externes — AUCUN détail interne sur le code. Se concentrer sur les unités de déploiement et les limites des équipes.
4. Topologie des équipes — Quelle équipe/personne est responsable de quels composants. Tableau : composant, responsable, criticité, facteur de bus.
5. Thèse d’investissement technologique — Pourquoi ces technologies ont-elles été choisies ? Tableau : technologie, objectif, alternatives envisagées, niveau de risque.
6. Évaluation des risques — Tableau : risque, probabilité, impact, mesures d’atténuation, responsable. Aborder la fiabilité, la sécurité, l’évolutivité et la conformité.
7. Modèle de coûts et d’évolutivité — Comment les coûts évoluent-ils en fonction de l’utilisation ? Quels sont les goulots d’étranglement ? Quand le prochain investissement en évolutivité sera-t-il nécessaire ?
8. Carte des dépendances — Graphique TB illustrant les dépendances externes critiques. Tableau : dépendance, type (service/bibliothèque/plateforme), risque en cas d’indisponibilité.
9. Indicateurs clés et observabilité — Ce qui est mesuré, quels tableaux de bord existent, couverture des alertes. Tableau : indicateur, valeur actuelle, cible, source.
10. Alignement sur la feuille de route — Flux de travail d’ingénierie alignés sur les priorités métier. Ce qui est en cours, ce qui est prévu, ce qui est bloqué.
11. Résumé de la dette technique — Les 5 principaux postes de dette ayant un impact sur l’activité. Tableau : Problème, impact sur l’activité, effort de correction, priorité.
12. Recommandations — 3 à 5 recommandations concrètes pour le prochain trimestre, classées par ordre de priorité en fonction de leur impact.

Règles

• PAS d’extraits de code — ce guide s’adresse aux responsables techniques, pas aux développeurs
• Diagrammes au niveau des services/équipes, et non au niveau des classes/fonctions
• Chaque affirmation doit être étayée par des preuves — citez des sections du wiki, des documents d’architecture ou des fichiers source
• Au moins 3 diagrammes Mermaid (vue d’ensemble de l’architecture, carte des dépendances, capacités/feuille de route)
• Des tableaux pour chaque conclusion structurée — ce public lit des tableaux, pas des textes en prose
• Langage métier — traduisez les concepts techniques en termes d’impact (fiabilité, vitesse, coût, risque)

Guide n° 4 : Guide du chef de produit

Fichier: onboarding/product-manager-guide.md Public cible: chefs de produit et parties prenantes non issues de l’ingénierie. Ils doivent comprendre ce que fait le système, ce qui est possible et où se situent les limites — et NON comment il est construit. Longueur: 400 à 800 lignes. Centré sur l'utilisateur, axé sur les fonctionnalités, tenant compte des contraintes.

Sections obligatoires

1. Ce que fait ce système — argumentaire de 2 à 3 phrases rédigé dans un langage accessible aux utilisateurs (sans jargon)
2. Carte du parcours utilisateur — Graphique Mermaid LR ou diagramme de parcours illustrant les principaux flux utilisateur au sein du système
3. Carte des fonctionnalités — Tableau : fonctionnalité, statut (en production/en bêta/prévue/impossible), comportement vis-à-vis de l’utilisateur, limitations. Carte exhaustive de ce qui est implémenté et de ce qui ne l’est pas.
4. Modèle de données (vue produit) — Diagramme erDiagram simplifié réalisé avec Mermaid illustrant les entités avec lesquelles les utilisateurs interagissent. Expliquez en termes métier (par exemple : « Un projet comporte plusieurs documents » et non « relation FK »).
5. Configuration et indicateurs de fonctionnalité — Tableau : indicateur/paramètre de configuration, ce qu’il contrôle, valeur par défaut, qui peut le modifier. Ce qui peut être activé ou désactivé sans intervention technique.
6. Capacités de l’API — Quelles intégrations sont possibles ? Tableau : capacité, point de terminaison/méthode, authentification, limites de débit. Rédigé à l’intention des partenaires d’intégration, et non des développeurs.
7. Performances et SLA — Temps de réponse, limites de débit, objectifs de disponibilité. Tableau : opération, latence attendue, limite de débit, SLA actuel.
8. Limitations et contraintes connues — Liste honnête de ce que le système ne peut pas faire ou fait mal. Tableau : Limitation, Impact sur l’utilisateur, Solution de contournement, Correction prévue.
9. Données et confidentialité — Quelles données sont collectées, où elles sont stockées, politiques de conservation, statut de conformité. Tableau : Type de données, Emplacement de stockage, Conservation, Conformité.
10. Glossaire — Termes spécifiques au domaine expliqués en langage clair (sans jargon technique)
11. FAQ — Plus de 10 questions courantes qu’un chef de projet se poserait, avec des réponses concises

Règles

• ZÉRO jargon technique — pas de « middleware », « injection de dépendances », « ORM ». Utilisez un langage simple.
• Approche centrée sur l'utilisateur — Décrivez tout en termes d'expérience utilisateur, et non en termes de fonctionnement du code
• Au moins 3 diagrammes Mermaid (parcours utilisateur, modèle de données, carte des fonctionnalités / aperçu des capacités)
• Des tableaux pour chaque conclusion structurée — les chefs de projet parcourent les tableaux, pas les textes
• Si un concept technique doit être mentionné, expliquez-le en une phrase (par exemple : « Feature flags — des commutateurs qui nous permettent d’activer ou de désactiver des fonctionnalités sans déployer de code »)
• Chaque affirmation doit s’appuyer sur des preuves — citez des sections du wiki ou des fichiers sources à des fins de vérification

Règles relatives aux diagrammes Mermaid (TOUS les guides)

TOUS les diagrammes doivent utiliser les couleurs du mode sombre :

• Remplissage des nœuds : #2d333b, bordures : #6d5dfc, texte : #e6edf3
• Arrière-plans des sous-graphes : #161b22, bordures : #30363d
• Lignes : #8b949e
• Si vous utilisez des directives de style en ligne, utilisez des remplissages sombres avec `,color:#e6edf3`
• N'utilisez PAS
dans les étiquettes Mermaid (utilisez plutôt
ou des sauts de ligne)

Validation

Après avoir généré chaque guide, vérifiez :

• Que tous les chemins d'accès mentionnés existent bel et bien dans le dépôt
• Que tous les noms de classes/méthodes sont corrects (et non inventés de toutes pièces)
• Les diagrammes Mermaid s’affichent correctement (sans erreur de syntaxe)
• Aucune balise de type HTML nue (génériques tels que List) ne figure en dehors des balises de code — les envelopper dans des guillemets inversés
• Chaque guide est adapté à son public — pas de code dans les guides destinés aux dirigeants ou aux chefs de projet