diagram

Les diagrammes sont porteurs, pas décoratifs. Utilisez-les seulement lorsque la prose force le lecteur à garder une forme entière en tête en même temps — choisissez alors la vue la plus petite qui lui permet de voir la forme plutôt que de la reconstruire à partir de phrases. Tout ceci s'affiche dans la conversation sous forme de blocs de texte ou de Mermaid ; au maximum un fichier artefact est jamais écrit.

Le vocabulaire

Choisissez une vue ; deux au maximum. Plus est du bruit.

Pseudocode — logique sans bruit de langage. Réduit une décision à sa forme de branchement :

on(request)
  if state file locked by another writer
    queue and return pending
  acquire lock
  write
  release

Arbre d'appel — flux de contrôle à l'exécution. La profondeur montre qui possède le flux ; annotez où se trouve la bordure intéressante :

acquireStateFileLockSync()
  resolveLockPath()
  openExclusive()
  writePid()

Arbre de composants — structure UI ou module, avec les limites importantes annotées en ligne :

<SettingsPage> (src/routes/settings)
  <SessionList> (possède ses propres fetchs)
  <DangerZone>
    <ConfirmButton> (désactivé jusqu'à confirmation tapée)

Arbre de fichiers — où se trouve la responsabilité ; gardez-le peu profond, une annotation par répertoire :

src/
├── hooks/        # registre de hooks + types
├── tools/        # gestionnaires d'outils MCP
└── workflow/     # registre + projections

Mermaid — interaction entre parties, flux de données ou transitions d'état :

sequenceDiagram
    participant CLI
    participant Hook
    participant State
    CLI->>Hook: PreToolUse
    Hook->>State: read mode
    Hook-->>CLI: allow / deny + facts

Diff — la forme d'un changement lorsque la structure environnante existe déjà. Faites correspondre le diff au sujet :

un changement de composant :

 <SettingsPage>
   <SessionList />
   <DangerZone>
+    <ConfirmButton />
   </DangerZone>

un changement de disposition de fichiers :

 src/tools/
-└── state-tools.ts
+└── state-tools/
+   ├── handlers.ts
+   └── schema.ts

un changement de flux de contrôle :

 commit()
   stage()
     hashBlobs()
+  writeObject()
   updateRef()
+    acquireStateFileLock()

un changement de machine d'état :

 on(request)
-  write immediately
+  if locked
+    queue and return pending
+  acquire lock
+  write
+  release

Le bloc complet — lorsque l'élision cacherait qui possède quoi ou l'ordre d'exécution, montrez l'unité complète une fois, copiable :

export function isRegistryEnabled(): boolean {
  const flag = process.env.OMC_WORKFLOW_REGISTRY;
  return flag !== '0' && flag !== 'false';
}

Quand le texte ne suffit pas

Une disposition UI, une comparaison avant/après, ou un concept trop dense pour Mermaid : écrivez un fichier HTML ciblé — un diagramme, une infographie ou quelques diapositives — stylé avec les couleurs, la typographie et les composants du produit, rempli de libellés et de données réels, fonctionnant sur desktop et mobile. Ouvrez-le avec l'ouvreur de la plateforme (start sur Windows, open sur macOS, xdg-open sur Linux) et arrêtez-vous là : un artefact, pas une galerie.

Discipline

• Placez chaque visuel directement à côté des deux ou trois phrases qu'il soutient.
• Ne conservez que les appels, fichiers, props, états et limites qui répondent à la question courante — chaque nœud supplémentaire est une taxe de décodage pour le lecteur.
• Si la réponse honnête tient en une phrase, écrivez la phrase.