Aller au contenu principal

Docs-as-code : comment cette doc ne ment jamais

Le risque numéro un d'une doc, c'est qu'elle périme : le code bouge, la prose reste. Comme la quasi-totalité du code ici est écrite via des agents Claude Code, on retourne ça à notre avantage — un verrou de hook force la mise à jour de la doc dans la même PR que le code qu'elle décrit.

Le contrat : front-matter sources:​

Chaque page qui documente du code déclare les surfaces qu'elle couvre, en chemins ou globs relatifs à la racine du repo :

---
title: Le pipeline /match
sources:
  - apps/api/src/routes/match.ts
  - apps/api/src/match/**
---

C'est tout ce qu'un auteur doit faire. Le reste est mécanique.

La boucle complète​

Les pièces​

1. Le détecteur — apps/docs/scripts/docs-drift.mjs​

Node pur, sans dépendance. Il :

  1. parse le front-matter sources: de toutes les pages → index inverse glob source → [pages] ;
  2. calcule les fichiers changés (git diff vs origin/dev + working tree) ;
  3. pour chaque source changée qui matche le glob d'une page, marque cette page « attendue en changement » ;
  4. drift = une page attendue dont le fichier .md n'a pas changé dans le même diff → sortie non-zéro + liste source → page périmée ;
  5. avertissement couverture (non bloquant) : une source changée sous une racine surveillée qui ne matche aucune page → « surface non documentée » (suppressible via apps/docs/.drift-ignore).
node apps/docs/scripts/docs-drift.mjs   # exit 0 = OK, exit 1 = drift

2. Le verrou — git-guard.sh​

Dans la branche gh pr create, après le check PAMBE_REVIEW_OK, le hook lance le détecteur. En cas de drift sans .git/PAMBE_DOCS_OK == HEAD, il bloque (exit 2). Même logique sentinelle-vs-HEAD que la revue conventions (voir Git & gates).

3. Le réparateur — agent docs-sync + skill /sync-docs​

  • L'agent .claude/agents/docs-sync.md lit chaque source changée, réécrit les pages affectées (prose + Mermaid régénéré), lance le typecheck docs, puis écrit la sentinelle PAMBE_DOCS_OK au SHA courant.
  • La skill .claude/skills/sync-docs/SKILL.md orchestre tout : drift-check → docs-sync → typecheck → sentinelle. C'est ce qu'un dev (ou son agent) lance avant la PR :
/sync-docs

Ajouter une nouvelle page documentée​

  1. Crée apps/docs/docs/<...>.md avec un front-matter sources: pointant les fichiers/globs décrits.
  2. Ajoute-la à apps/docs/sidebars.ts.
  3. C'est tout — dès le prochain diff touchant ces sources, le détecteur saura qu'il faut rafraîchir ta page.
Bonne granularité de sources:

Vise un glob assez large pour capturer les évolutions (apps/api/src/match/**) mais assez ciblé pour ne pas déclencher de drift à chaque commit non lié. Une page = un sujet cohérent = un petit ensemble de globs.