Skip to main content

ADR-005 — Agent Claude dédié docs-specialist

Date : 2026-04-23 · Statut : Accepté · Dépend de : ADR-004

Contexte​

L'adoption de Docusaurus (ADR-004) introduit un périmètre documentaire important :

  • ~75 pages MDX à créer et maintenir (fonctionnel, technique, design-system, API, business rules, guides)
  • Composants MDX custom à utiliser de façon cohérente (<PrismaModel>, <BusinessRule>, <ApiEndpoint>, <Screenshot>, <LiveExample>, <PropsTable>)
  • Section Design System à garder synchronisée avec src/components/** et tailwind.config.ts
  • Scripts de génération à exécuter (docs:screenshots, docs:generate-api, docs:generate-tokens, docs:generate-component-props)
  • i18n FR/EN à maintenir cohérent
  • Sidebar sidebars.ts à tenir à jour à chaque ajout de page

Les agents existants ne couvrent pas ce périmètre :

  • doc-writer est généraliste (JSDoc, READMEs, commentaires) et n'est pas spécialisé Docusaurus/MDX
  • architect écrit des ADRs mais pas des guides utilisateur ou du design-system live
  • ux-ui-designer conçoit mais ne publie pas
  • Aucun agent n'exécute les scripts de génération dédiés

Sans agent spécialisé : incohérence de format, composants MDX mal utilisés, sidebar désynchronisée, pages orphelines, broken links, oublis i18n, tokens design-system qui divergent du code.

Options considérées​

Option A — Nouvel agent docs-specialist dédié (retenu)

  • Pour : owner unique, garde-fous spécifiques (refus sans ADR, refus page sans sidebar, exigence de scripts pour contenu dérivable), outils limités (lecture seule sur src/)
  • Contre : 1 agent supplémentaire à maintenir

Option B — Étendre doc-writer

  • Pour : pas de nouvel agent
  • Contre : responsabilités hétérogènes (JSDoc inline ET site MDX), prompt flou, régression sur les deux usages, pas de garde-fous ciblés Docusaurus

Option C — Pas d'agent, tout dans le prompt principal

  • Pour : simplicité apparente
  • Contre : aucun garde-fou, incohérences assurées à l'échelle de ~75 pages

Décision​

Option A — Nouvel agent docs-specialist.

Le volume et la spécificité du site Docusaurus justifient un agent dédié avec périmètre clair, outils limités et garde-fous adaptés. La séparation d'avec doc-writer évite la dérive de responsabilités.

Spécification de l'agent​

Emplacement : .claude/agents/docs-specialist.md (versionné, scope projet)

Rôle : owner unique du site Docusaurus docs-site/.

Responsabilités :

  • Créer / mettre à jour les pages MDX (toutes sections)
  • Utiliser les composants MDX custom de façon cohérente
  • Maintenir sidebars.ts à jour
  • Synchroniser design-system avec src/components/** et tailwind.config.ts via scripts
  • Exécuter npm run docs:screenshots, docs:generate-api, docs:generate-tokens, docs:generate-component-props
  • Gérer i18n FR/EN (flag pages non traduites, pas de broken fallback)
  • Garantir 0 broken link et 0 orpheline avant rendu

Outils autorisés : Read, Glob, Grep, Write, Edit, Bash (restreint aux commandes npm run docs:*, docusaurus build, lint ; jamais git push, jamais rm -rf)

Restrictions strictes :

  • Lecture seule sur src/, prisma/, tests/ (ne modifie jamais le code applicatif)
  • Lecture seule sur .github/workflows/ (les modifs CI passent par devops)

Déclencheurs :

  • Modification dans docs-site/**
  • Demande de documentation fonctionnelle / technique / API / design-system / guide / business rule
  • Après merge d'une feature : régénération ciblée captures + API docs
  • Commande /doc-sync

Garde-fous :

  • Refuse de documenter un choix structurel sans ADR correspondant
  • Refuse de créer une page sans entrée sidebars.ts
  • Challenge toute demande de duplication entre sections
  • Exige un script de génération pour tout contenu dérivable du code

Impact sur les agents existants :

  • doc-writer : recentré sur JSDoc, commentaires, READMEs de sous-modules
  • architect : écrit désormais les ADRs directement dans docs-site/docs/adr/
  • ux-ui-designer : collabore avec docs-specialist (design → publication)

Conséquences​

Positives

  • Cohérence garantie à l'échelle de ~75 pages
  • Garde-fous structurels (ADR requis, sidebar requise, scripts obligatoires)
  • Séparation claire des préoccupations entre agents
  • Design system jamais désynchronisé du code

Risques acceptés

  • 1 agent supplémentaire à maintenir dans .claude/agents/
  • Nécessite mise à jour de CLAUDE.md (section agents + commande /doc-sync)
  • Coordination requise entre docs-specialist et doc-writer / architect / ux-ui-designer

Révision​

Cette décision serait à remettre en question si :

  • Le site Docusaurus était abandonné (ADR-004 révisé)
  • La documentation devenait statique (plus de mises à jour, cas peu probable)
  • Un seul agent généraliste prouvait sa capacité à maintenir la cohérence sur le volume complet sans régression