Création de documentation
Rédiger du contenu Markdown en fonction du contexte actuel de la conversation et du contenu du dossier.
Le README est une spécification de l'état actuel destinée à un utilisateur humain, et non un journal des modifications, un journal des décisions ou un historique. N'enregistrez jamais d'informations historiques ou de choix effectués, uniquement la spécification telle qu'elle se présente au moment de la rédaction du README.
Périmètre
Trouver tous les fichiers README.md du projet et mettre à jour chacun d'eux. Le contenu du dossier se situe au niveau du README et en dessous (siblings et sous-dossiers), jamais au-dessus (parents). Faites attention aux couches de sous-dossiers, au périmètre et aux contextes délimités. Ne faites pas fuiter des concepts entre des documents de différentes couches. Chaque README couvre son propre niveau de dossier et ce qui se trouve en dessous, jamais les préoccupations des parents.
Si l'utilisateur a fourni des indications ou des domaines d'intérêt spécifiques, appliquez ce contexte lorsque vous décidez quoi mettre en avant dans la documentation.
Rassembler le contexte
N'exécutez jamais git directement. Le script de base fourni avec ce plugin couvre tout ce dont cette compétence a besoin de git. Exécutez chaque commande depuis la racine du dépôt et écrivez le chemin complet du script à chaque fois, car les variables shell ne persistent pas entre les commandes.
Commencez par le plan. Celui-ci trouve chaque README, ajoute un README racine lorsqu'il n'en existe pas, détermine la base de référence de chaque README, liste ce qui a changé depuis cette base et indique quoi faire avec chaque README. Lorsque les indications de l'utilisateur nomment des répertoires sur lesquels se concentrer, passez-les après readme. Sinon, ne passez rien.
bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" plan readme [<focus-dir>...]
Le plan affiche un bloc par action.
## updatenomme une base de référence, un périmètre et le README, suivis des commits, du diff stat et du statut depuis cette base. Mettez le README à jour. Un README que les modifications n'affectent pas conserve son contenu.## newliste les README à écrire à partir du code actuel. Ils n'ont pas besoin d'historique.## unchangedet## outside the focuslistent les README à laisser exactement tels quels.
head none signifie que le dépôt n'a aucun commit. Chaque README est nouveau.
Pour un bloc de mise à jour, comptez les fichiers dans son stat. À plus de 20 fichiers, sautez le diff complet et lisez directement les fichiers modifiés. À 20 fichiers ou moins, lisez le diff. Les fichiers non suivis, marqués ??, n'apparaissent dans aucun diff, donc lisez-les directement de toute façon. Le périmètre peut être celui du bloc ou un seul fichier, car il s'agit d'un pathspec git.
bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" diff <sha> <scope>
Ensuite, pour chaque README à mettre à jour ou à écrire, limité à son répertoire :
-
Lire le README actuel (s'il existe)
-
Explorer la base de code à ce niveau de répertoire et en dessous
-
Examiner l'historique de la conversation pour les décisions, modifications ou leçons apprises pertinentes
-
Utiliser les modifications et le contexte de la conversation pour identifier les sections qui nécessitent une mise à jour. Vérifier le code par rapport à la documentation et la documentation par rapport au code. Lorsque le code supprime une fonction, un indicateur ou un module, grep dans chaque README pour trouver son nom, puis relire chaque résultat et l'aperçu de chaque README pour une description en langage clair de la même chose.
grep -rn '<nom supprimé>' <dir>/README.md
N'incluez jamais la ligne de marquage dans le texte que vous écrivez ou modifiez. finish l'ajoute après l'écriture. Lorsque vous modifiez un README qui se termine déjà par une telle ligne, laissez cette ligne tranquille.
Si rien n'a changé qui justifie une mise à jour du README, dites-le et passez à la suite. finish s'applique quand même.
Plan du README.md
Ordre des sections et contenu d'un README.md. Chaque section est remplie à partir du projet cible. Omettez une section pour laquelle le projet n'a rien.
# Titreet un aperçu de cinq phrases maximum- Image ou vidéo optionnelle
## Architecture- composants sous forme de liste à puces, chacun avec son objectif## Prérequis- comptes, clés, identifiants, outils, environnements d'exécution, CLI, chacun avec la raison pour laquelle il est nécessaire## Structure du projet- dossiers uniquement, pas de fichiers, chacun avec un objectif en une ligne## Installation- les commandes qui l'installent## Utilisation- les commandes qui l'exécutent## Tests- omis lorsque le projet n'a pas de tests
Visez moins de 500 lignes. Divisez un README plus long en déplaçant les détails dans un README imbriqué à côté du code qu'il décrit.
Format
# Titre
Aperçu succinct. Cinq phrases maximum.
<!-- IMAGE OU VIDÉO OPTIONNELLE -->
<img src="demo.png" alt="Démo" width="800"/>
## Architecture
Composants de haut niveau et objectif
- Composant - objectif
- Composant - objectif
## Prérequis
- Prérequis - description et raison (comptes, clés, identifiants, outils, environnements d'exécution, CLI)
## Structure du projet
Afficher la structure des dossiers. Ne pas inclure les fichiers.
```text
projet/
├── src/
│ ├── composant-a/ # objectif - voir src/composant-a/README.md
│ └── composant-b/ # objectif - voir src/composant-b/README.md
├── scripts/ # objectif
└── tests/ # objectif
```
## Installation
```bash
# comment le projet est installé
<commande d'installation>
```
## Utilisation
```bash
# comment le projet est exécuté
<commande d'exécution>
```
## Tests
```bash
# comment les tests sont exécutés
<commande de test>
```
Finalisation
Exécutez finish à chaque fois, y compris pour une exécution qui n'a rien écrit. plan a laissé un fichier de plan derrière lui et seul finish le supprime, donc une exécution qui saute finish laisse un état pour que la suivante trébuche dessus.
bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" finish readme
Il tamponne chaque README que le plan a marqué comme nouveau ou mise à jour, et chaque README créé depuis le plan, avec le HEAD que le plan a vérifié. Le tampon est une ligne de marquage à la fin du README, un commentaire HTML nommant ce commit. finish laisse les README inchangés et les README hors focus tranquilles, et ne tamponne rien lorsque le dépôt n'a aucun commit. La sortie 4 signifie qu'un README planifié est manquant. Écrivez-le et exécutez finish à nouveau.
- N'appelez jamais
stampdirectement et n'écrivez ni ne modifiez jamais la ligne de marquage à la main. finish l'écrit. - Le marqueur est une métadonnée. La règle contre l'enregistrement de l'historique ne s'y applique pas.