Amorçage de la documentation
Il s'agit d'une tâche ponctuelle. Pour les modifications ultérieures, utilisez engineering:documentation-sync.
1. Faire l'inventaire
Listez les documents qui existent et marquez chacun comme présent, léger (existe mais est presque vide ou obsolète) ou manquant. Vérifiez au moins :
README.md, CONTRIBUTING.md, CHANGELOG.md, ARCHITECTURE.md ou docs/architecture/, enregistrements de décisions, CLAUDE.md, SECURITY.md, LICENSE, la référence API, la référence de configuration, les runbooks.
git ls-files '*.md' | grep -v node_modules
2. Laisser l'utilisateur choisir
Affichez le menu issu de resources/doc-catalog.md. Marquez chaque type comme présent, léger ou manquant. Marquez les types que vous recommandez pour ce type de projet.
- Les documents présents ne sont pas réécrits. L'utilisateur peut choisir « réviser » pour un document léger.
- L'utilisateur sélectionne. N'écrivez pas un type que l'utilisateur n'a pas sélectionné.
3. Construire la fiche de faits
Avant que quiconque n'écrive, collectez les faits qui seront utilisés par plusieurs documents. Prenez-les à partir du code et de git, pas de mémoire. Écrivez-les dans un fichier temporaire.
| Fait | Source |
|---|---|
| Nom du projet et objectif en une phrase | README, manifeste, utilisateur |
| Version actuelle | manifeste, dernier tag (git describe --tags --abbrev=0) |
| Langages, frameworks et leurs versions | manifestes et fichiers de verrouillage |
| Commandes d'installation, de test, de lint, de construction et d'exécution | engineering:development-commands |
| Composants et leurs noms | structure des répertoires, points d'entrée, fichiers compose |
| Variables d'environnement et paramètres | .env.example, et le code qui lit les paramètres (recherchez process.env, os.environ, getenv) |
| Dates importantes | le premier commit (git log --reverse), les tags |
| Ce qui fonctionne aujourd'hui, ce qui ne fonctionne pas | utilisateur, tickets ouverts |
Si deux sources sont en désaccord, demandez à l'utilisateur. Ne choisissez pas une source en silence. Chaque rédacteur n'utilise que la fiche de faits et le code.
4. Écrire
- Trois documents ou moins : écrivez-les vous-même, l'un après l'autre.
- Plus de trois : lancez un sous-agent pour chaque document ou petit groupe, au maximum quatre à la fois. Donnez à chaque sous-agent :
- le ou les fichiers exacts dont il est responsable, et la règle selon laquelle il ne peut pas modifier d'autre fichier ;
- la fiche de faits ;
- le plan de sections pour son type issu de
resources/doc-catalog.md; - l'instruction d'écrire en Technical English simplifié (la compétence
simple-english, si installée) ; - l'instruction de signaler les faits dont il avait besoin et qu'il n'a pas trouvés, au lieu de les inventer.
N'inventez pas d'historique, de chiffres, d'utilisateurs ou de fonctionnalités. Écrivez « À déterminer » et listez-le pour l'utilisateur.
5. Vérifier l'ensemble
Suivez resources/consistency-check.md. Corrigez chaque problème avant de continuer.
6. Commiter
Placez les documents sur une branche (engineering:git-branching) et ouvrez une PR (engineering:github-pr-merge). Dans le corps de la PR, listez chaque nouveau document et chaque « À déterminer » qui nécessite une réponse de l'utilisateur.
Compétences associées
engineering:documentation-sync: maintient ces documents à jour après cette opération.gener8v:brownfield: intègre une base de code existante dans le pipeline gener8v. Il écrit le contexte.gener8v/, pas ces documents de projet.