mise à jour documentation plugin

Mise à jour de la documentation du projet

Deux responsabilités :

1. CLAUDE.md — aperçu concis du projet (toujours chargé)
2. .llmdocs/ — documents détaillés concept par concept (chargés à la demande). Tous les fichiers ici sont des documents de conception persistants.

---

1. CLAUDE.md — La carte

Portée

Trouver tous les répertoires CLAUDE.md et .llmdocs/ dans le projet et mettre à jour chacun d'eux. Faites attention aux couches de sous-dossiers, à la portée et aux contextes bornés. Ne propagez pas les concepts entre les documents à différentes couches. Chaque CLAUDE.md et .llmdocs/ couvre son propre niveau de répertoire et en dessous, jamais les préoccupations parentes.

Si l'utilisateur a fourni des directives ou des domaines d'intérêt spécifiques, appliquez ce contexte pour décider quels documents mettre à jour et sur quoi mettre l'accent.

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. Il trouve chaque CLAUDE.md et son .llmdocs/, y compris les fichiers requis qui n'existent pas encore, résout la ligne de base de chaque document, liste ce qui a changé depuis, et indique quoi faire avec chaque document. Lorsque les directives de l'utilisateur nomment des répertoires sur lesquels se concentrer, passez-les après llmdocs. Sinon, ne passez rien.

bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" plan llmdocs [<focus-dir>...]

Le plan imprime un bloc par action.

• ## update nomme une ligne de base, une portée et les documents qui la partagent, suivis des commits, du diff stat et du statut depuis cette ligne de base. Mettez ces documents à jour. Un document que les changements n'affectent pas conserve son contenu.
• ## new liste les documents à écrire à partir du code actuel. Ils n'ont besoin d'aucun historique.
• ## unchanged et ## outside the focus listent les documents à laisser exactement tels quels.

head none signifie que le dépôt n'a aucun commit. Chaque document est nouveau.

Pour un bloc de mise à jour, comptez les fichiers dans son stat. À plus de 20, sautez le diff complet et lisez les fichiers modifiés directement. À 20 ou moins, lisez le diff. Les fichiers non suivis, marqués ??, n'apparaissent dans aucun diff, donc lisez-les directement dans les deux cas. La portée peut être celle du bloc ou un seul fichier, car c'est un pathspec git.

bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" diff <sha> <scope>

Ensuite, pour chaque paire CLAUDE.md/.llmdocs/ avec des documents à mettre à jour ou à écrire :

1. Lisez le CLAUDE.md actuel et chaque fichier dans .llmdocs/ (s'ils existent)
2. Explorez la base de code à ce niveau de répertoire et en dessous
3. Passez en revue l'historique de la conversation pour les décisions, changements ou leçons apprises pertinents
4. Utilisez les changements et le contexte de la conversation pour identifier ce qui a changé. Les llmdocs sont des spécifications de l'état actuel, pas un journal des changements, pas un journal des décisions, pas un enregistrement historique. N'enregistrez jamais d'informations historiques ou de choix effectués, uniquement la spécification telle qu'elle se trouve au moment de la rédaction des llmdocs.

Écrire/Mettre à jour CLAUDE.md

Objectif : moins de 500 lignes. Chaque ligne doit mériter sa place.

# <Nom>

<1-2 lignes sur le but de ce répertoire/composant>

## Stack

<liste à puces : langage, frameworks, dépendances clés pertinentes à ce niveau>

## Disposition

<répertoires clés et ce qu'ils contiennent à ce niveau>

## Commandes

<build, test, lint, déploiement — commandes uniquement>

## Conventions

<style, nommage, modèles — uniquement ce qui évite les erreurs>

## Concepts clés

<termes du domaine, logique métier que Claude doit connaître à ce niveau>

## Docs LLM

Documents détaillés dans `.llmdocs/` :

- @.llmdocs/architecture.md — <description en 1 ligne>
- @.llmdocs/data-model.md — <description en 1 ligne>

Règles CLAUDE.md

• PAS d'explications verbeuses — Claude déduit
• PAS de duplication du contenu .llmdocs/ — simplement référencer avec une courte description
• La section ## Docs LLM DOIT lister tous les fichiers .llmdocs/ avec une description d'une ligne chacun
• Un CLAUDE.md qui liste ses fichiers .llmdocs/ sous ## Docs précède l'en-tête actuel. Renommez cet en-tête en ## Docs LLM chaque fois que vous mettez à jour le fichier
• Préservez les instructions personnalisées existantes (flux de travail git, variables d'environnement, etc.)
• Supprimez le contenu uniquement lorsque le code le contredit, et nommez chaque suppression dans le résumé
• Lorsque le code supprime une fonction, un indicateur ou un module, greppez chaque document de ce niveau pour son nom, puis relisez chaque occurrence et la ligne d'objectif de chaque document pour une description en langage clair de la même chose. Supprimer le nom d'un document ne suffit pas

grep -rn '<nom supprimé>' <dir>/CLAUDE.md <dir>/.llmdocs

• N'incluez jamais la ligne de marqueur dans le texte que vous écrivez ou modifiez. finish l'ajoute après l'écriture. Lors de l'édition d'un document qui se termine déjà par un, laissez cette ligne tranquille
• Utilisez @.llmdocs/fichier.md pour importer un document s'il doit toujours être chargé

---

2. .llmdocs/ — Le territoire

Processus

Un fichier conceptuel au-delà des sept requis est à vous d'ajouter, et le plan ne le nomme jamais. finish le tamponne quand même, ainsi que tous les autres documents de ce niveau créés pendant l'exécution.

1. Évaluer : utilisez les blocs de mise à jour du plan pour identifier les documents concernés
2. Identifier : déterminez quels documents existants sont concernés, ou si un nouveau document est nécessaire
3. Mettre à jour CLAUDE.md : assurez-vous que la section ## Docs LLM liste tous les nouveaux fichiers de documents

Si rien n'a changé qui justifie des mises à jour de documentation, dites-le et passez à autre chose.

Emplacement

Utilisez le chemin nommé par la première importation sous l'en-tête ## Docs LLM de CLAUDE.md, ou sous ## Docs dans un CLAUDE.md qui le précède. Sinon, utilisez par défaut .llmdocs/ au niveau du répertoire cible. CLAUDE.md et .llmdocs/ peuvent exister à n'importe quel niveau de répertoire dans le projet.

Structure

Plate, 1 fichier par concept. Les 7 premiers fichiers sont obligatoires et doivent toujours exister. testing.md est créé lorsque le projet a une suite de tests et omis lorsqu'il n'en a pas. Des fichiers conceptuels supplémentaires sont créés selon les besoins.

.llmdocs/
  architecture.md    # Composants, interactions, flux de données (obligatoire)
  api.md             # Points de terminaison, requête/réponse, authentification, autorisation (obligatoire)
  data-model.md      # Schéma, modèles, relations (obligatoire)
  deployment.md      # Processus de déploiement, environnements (obligatoire)
  ops.md             # Runbooks, maintenance, dépannage (obligatoire)
  observability.md   # Journaux, métriques, traces, contrôles de santé, tableaux de bord, alertes (obligatoire)
  security.md        # Périmètres de confiance, gestion des secrets, authn/authz, modèle de menace (obligatoire)
  testing.md         # Disposition des tests, exécuteur, fixtures, comment exécuter la suite (quand le projet a des tests)
  <concept>.md       # Spécifique au domaine selon les besoins

Format du fichier de documentation

# <Concept>

<Objectif en 1 ligne>

## <Section>

<contenu : en-têtes, tableaux, blocs de code — pas de paragraphes en prose>

Règles .llmdocs/

• Maximum 500 lignes par fichier — divisez si plus long
• Incluez les chemins de fichiers avec des références de lignes si utile (src/auth/login.ts:42)
• Mettez à jour les documents existants de manière incrémentielle, ne les réécrivez pas de zéro
• Si un document est précis et non affecté par les changements récents, laissez son contenu tranquille. finish met toujours à jour son marqueur.
• Précision plutôt que couverture : ne documentez que ce qui est vérifiable à partir du code
• observability.md contient les signaux que le système émet, et ops.md contient les actions qu'un opérateur entreprend. Un point de terminaison de santé, un format de journal ou une alerte appartient à observability.md. Un projet sans métriques ni traces documente toujours sa sortie standard, sa sortie d'erreur et ses codes de sortie ici
• N'incluez jamais la ligne de marqueur dans le texte que vous écrivez ou modifiez. finish l'ajoute après l'écriture. Un fichier conceptuel que vous créez est le piège ici, car chaque frère que vous venez de lire se termine par un. Copier cette ligne écrit un sha obsolète prétendant que le document a été vérifié par rapport à un commit qu'il n'a jamais vu. Terminez un nouveau fichier à sa dernière ligne de contenu et laissez finish ajouter le marqueur

---

3. Finition

Exécutez finish, à chaque fois, y compris une exécution qui n'a rien écrit. plan a laissé un fichier de plan derrière et seul finish le supprime, donc une exécution qui saute finish laisse un état pour que la prochaine trébuche dessus.

bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" finish llmdocs

Il tamponne chaque document que le plan a marqué comme nouveau ou mis à jour, et chaque document créé depuis le plan, comme testing.md, avec le HEAD que le plan a vérifié. Le tampon est une ligne de marqueur à la fin du document, un commentaire HTML nommant ce commit. finish laisse les documents inchangés et les documents hors du focus tranquilles, et ne tamponne rien lorsque le dépôt n'a aucun commit. La sortie 4 signifie qu'un document planifié est manquant. Écrivez-le et exécutez finish à nouveau.

• N'appelez jamais stamp directement et n'écrivez ni ne modifiez jamais la ligne de marqueur à la main. finish l'écrit.
• Le marqueur est une métadonnée. La règle contre l'enregistrement de l'historique ne s'applique pas à lui.

---

4. Résumé de sortie

Après l'exécution, sortez ce résumé. Remplissez chaque ligne à partir de l'exécution et écrivez "none" lorsqu'une liste est vide. Sous Tamponnés, copiez les lignes de finish textuellement, une par document. N'écrivez jamais de sha ici, et n'ajoutez jamais un mot que finish n'a pas imprimé.

Une phrase reformulée pour supprimer une capacité est une suppression. Nommez-la sous Supprimés avec la formulation qui a disparu, même lorsque la même ligne existe toujours.

Exemple rempli, à partir d'une exécution où le code a supprimé le comptage de caractères.

Fichiers créés : none
Fichiers modifiés : CLAUDE.md, .llmdocs/api.md
Sections CLAUDE.md ajoutées, mises à jour ou supprimées : Concepts clés mis à jour
Supprimés car le code les contredit :
- CLAUDE.md : "ou caractères" de la ligne d'objectif, et le concept clé --chars
- .llmdocs/api.md : la ligne count_chars
Tamponnés :
- tamponné CLAUDE.md (marqueur)
- tamponné .llmdocs/api.md (marqueur)

Lorsque les changements ne justifient aucune mise à jour de documentation, écrivez "aucun changement de documentation nécessaire" au-dessus du résumé.