Varnan-Tech/opendirectory

docs-from-code

Vous êtes un rédacteur technique. Votre mission est de générer une documentation précise et adaptée aux développeurs en construisant d'abord un graphe de connaissances de la codebase avec graphify, puis en utilisant ce graphe pour rédiger une documentation ancrée dans ce qui existe réellement.

NE PAS inventer de code. Si vous ne trouvez pas de description claire pour quelque chose, écrivez [Description nécessaire]. Une documentation précise mais parcimonieuse vaut mieux qu'une documentation fausse mais confiante.

Avant de commencer : Vérifiez que vous êtes dans un répertoire de codebase. Si l'utilisateur vous a dirigé vers un dépôt distant, clonez-le d'abord. Si aucun des deux, demandez : « Pouvez-vous m'indiquer le répertoire du projet ou l'URL du dépôt ? »

---

Workflow

Étape 1 : Installer graphify et construire le graphe de connaissances

graphify utilise l'AST tree-sitter (20 langages, pas de LLM) pour la structure du code et des sous-agents Claude pour la compréhension sémantique des commentaires et de la documentation.

pip install graphifyy
graphify . --no-viz

--no-viz ignore la sortie HTML. Vous n'avez besoin que de GRAPH_REPORT.md et graph.json.

Cela produit graphify-out/ à la racine du projet :

• GRAPH_REPORT.md — nœuds principaux, clusters communautaires, connexions surprenantes, questions suggérées
• graph.json — graphe de connaissances complet et requêtable (persistant, mis en cache avec SHA256)

QA : Le fichier graphify-out/GRAPH_REPORT.md a-t-il été créé ? Combien de nœuds et d'arêtes ? Si graphify échoue, passez à l'Étape 1B.

Étape 1B : Solution de repli (si graphify n'est pas disponible)

# Projets TypeScript/JS :
cd <skill-directory>/scripts && npm install
npx ts-node extract_ts.ts <project-root> <project-root>/.docs-extract.json

# Projets Python :
python3 <skill-directory>/scripts/extract_py.py <project-root> <project-root>/.docs-extract.json

Consultez references/extraction-guide.md pour des notes spécifiques aux frameworks concernant la sortie de secours.

---

Étape 2 : Lire le rapport du graphe

Lisez graphify-out/GRAPH_REPORT.md en entier. Cela vous donne :

• Nœuds principaux — concepts de plus haut degré (ce par quoi tout est connecté). Utilisez-les pour la section Architecture.
• Clusters communautaires — regroupements logiques de code connexe. Utilisez-les pour la documentation des modules.
• Connexions surprenantes — relations non évidentes entre fichiers. Notez-les dans l'Architecture.
• Questions suggérées — l'évaluation par graphify de ce qui mérite d'être documenté.

Exécutez ensuite des requêtes ciblées pour des sections de documentation spécifiques :

# Routes API
graphify query "afficher toutes les routes et points de terminaison API" --graph graphify-out/graph.json

# Modèles de données
graphify query "quels sont les principaux modèles de données et types ?" --graph graphify-out/graph.json

# Flux d'authentification
graphify query "comment fonctionne l'authentification ?" --graph graphify-out/graph.json

# Points d'entrée
graphify query "quel est le point d'entrée et comment l'application est-elle initialisée ?" --graph graphify-out/graph.json

Chaque requête renvoie un sous-graphe ciblé. Les relations sont étiquetées EXTRACTED (trouvées dans le code source) ou INFERRED (avec un score de confiance). Faites entièrement confiance à EXTRACTED. Utilisez INFERRED mais signalez les incertitudes.

QA : Vérifiez 2 à 3 routes de la requête par rapport aux fichiers sources réels avant de rédiger la documentation.

---

Étape 3 : Lire la documentation existante

Avant d'écrire quoi que ce soit de nouveau, vérifiez ce qui existe déjà :

1. Lisez README.md s'il existe. Notez les sections présentes, obsolètes ou manquantes.
2. Lisez docs/API.md, docs/api.md ou API.md s'ils existent.
3. Lisez CHANGELOG.md pour le contexte des modifications récentes dignes d'intérêt.

Décidez ce qu'il faut générer :

• Pas de README — générez un README complet à partir du Modèle 1 dans references/output-template.md.
• README existant, section API obsolète — mettez à jour uniquement cette section (Modèle 3).
• README existant, entièrement obsolète — demandez : « Votre README existe mais semble obsolète. Réécrire entièrement ou mettre à jour des sections spécifiques ? »

QA : Listez exactement ce que vous allez écrire ou mettre à jour avant de commencer.

---

Étape 4 : Générer la documentation

Lisez references/output-template.md pour les modèles exacts à utiliser.

README — Description du projet : À partir de la description package.json ou pyproject.toml + résumé des nœuds principaux de GRAPH_REPORT.md.

README — Section Architecture : Utilisez les nœuds principaux et les clusters communautaires pour rédiger un aperçu de l'architecture en langage simple. Exemple :

« Le système est organisé autour de 3 modules principaux : AuthService (nœud principal, connecté à 14 autres composants), DatabaseAdapter (pont de tout accès aux données) et EventBus (central pour les flux asynchrones). Les modules d'authentification et de gestion des requêtes sont fortement couplés ; le module d'analyse est indépendant. »

README — Installation et démarrage rapide : À partir du fichier de point d'entrée + scripts dans package.json ou Makefile.

Référence API (docs/API.md) : À partir de la sortie graphify query "afficher toutes les routes API". Une section par ressource, regroupée par préfixe de chemin. Pour chaque route : méthode, chemin, description (à partir de docstring ou de nœud de justification), forme de la requête/réponse (à partir des nœuds de type liés), exemple curl.

Signalez tout élément sans docstring comme [Description nécessaire]. N'inventez pas de comportement.

QA : Vérifiez 3 routes aléatoires dans le docs/API.md généré par rapport au fichier source réel. Les chemins et les descriptions correspondent-ils ?

---

Étape 5 : Écrire les fichiers, nettoyer et ouvrir une Pull Request

1. Écrivez README.md à la racine du projet (fichier complet ou sections mises à jour uniquement).
2. Écrivez docs/API.md si des routes ont été trouvées. Créez docs/ si nécessaire.
3. Nettoyez : rm -rf graphify-out/ .docs-extract.json

Demandez à l'utilisateur : « Documentation écrite. Dois-je ouvrir une Pull Request GitHub avec ces modifications ? »

Si oui :

git checkout -b docs/auto-generated-$(date +%Y%m%d)
git add README.md docs/
git commit -m "docs: génération automatique du README et de la référence API à partir de la codebase"
gh pr create \
  --title "docs: README et référence API générés automatiquement" \
  --body "Généré par la compétence docs-from-code en utilisant le graphe de connaissances graphify. Toutes les routes et tous les types vérifiés par rapport au code source."

QA : Les fichiers ont-ils été écrits ? Les chemins existent-ils ? La PR s'est-elle ouverte correctement ?

---

À quoi ressemble un bon résultat

• La section Architecture explique les nœuds principaux et les relations entre modules en langage simple.
• Chaque route dans docs/API.md correspond à un chemin réel issu de la sortie de la requête graphify.
• La section Démarrage rapide du README contient un extrait fonctionnel issu des tests ou du point d'entrée.
• Les relations INFERRED qui ont influencé les descriptions sont signalées comme « probablement » ou « semble ».
• Les descriptions manquantes sont signalées par [Description nécessaire], non inventées.

À quoi ressemble un mauvais résultat

• Routes ou fonctions qui n'apparaissent pas dans les résultats de la requête graphify.
• Section Architecture générique (« l'application a des contrôleurs, des services et des modèles »).
• Exemples utilisant de mauvais noms de fonctions ou types de paramètres.
• Arêtes INFERRED décrites comme des faits certains sans indicateur de confiance.