Flux de travail de documentation pour LLMs

Les agents LLM sont amnésiques par défaut : chaque session part de zéro. La seule chose qui survit à la frontière de session est ce que tu as stocké dans un système externe. La documentation n'est donc pas de la bureaucratie — c'est la façon de rester toi-même entre les sessions.

Les trois couches

Couche 1 : Mémoires

Stocke une mémoire quand le fait est nouveau, pas à la fin de la session. Les sessions plantent ; les fenêtres de contexte débordent ; un « je le noterai plus tard » est un fait qui n'a jamais eu lieu.

Choisis la bonne catégorie :

• identity — qui tu es, ton rôle, tes frères et sœurs
• project — état et décisions d'un projet
• mistake — ce qui a mal tourné et la leçon (la catégorie la plus précieuse)
• skill — comment on fait quelque chose (listes d'étapes, commandes)
• credentials — tokens, endpoints, chemins (jamais dans le chat ni le code)
• context — état de session qui mérite d'être conservé

Utilise confidence honnêtement (1.0 = vérifié, 0.5 = hypothèse) et tague de façon cohérente — les mémoires se trouvent par tag et par clé, pas par prose.

POST /memory
{ "content": "...", "category": "mistake", "key": "pg-params-42p18",
  "tags": ["postgres","dynamic-sql"], "priority": "high", "confidence": 1.0 }

Couche 2 : Worklogs

Le worklog est le journal de progression d'une tâche. Il répond à « que s'est-il passé exactement pendant la résolution ? » pour tout lecteur futur — y compris ton futur toi.

POST /worklog/my-task-123 { "kind": "start",    "content": "Bug reproduit" }
POST /worklog/my-task-123 { "kind": "progress", "content": "Fix dans src/db.ts:142" }
POST /worklog/my-task-123 { "kind": "error",    "content": "42P18 — param type undetermined" }
POST /worklog/my-task-123 { "kind": "close",    "summary": "Corrigé, 24/24 tests verts" }

Règle empirique : une entrée par décision ou découverte, pas par heure. Les erreurs vont dans le log immédiatement — ce sont les entrées les plus utiles plus tard.

Couche 3 : Changelog et commits

Les changements de code sont aussi de la documentation :

• Message de commit : ce qui a changé et pourquoi, avec la référence tâche/utilisateur entre parenthèses. Première ligne sous 72 caractères, mode impératif.
• CHANGELOG.md : une entrée par changement visible par l'utilisateur, regroupée en Added / Changed / Fixed / Removed, avec la version et la date.

Un fix sans entrée de changelog est invisible pour tous ceux qui n'ont pas lu le diff.

Anti-patterns

• Dumps de mémoire en fin de session. Le contexte est déjà parti — stocke en continu.
• Mémoires en prose. « Peut-être que la base de données était quelque part dans la config » est introuvable. Utilise des clés précises, des tags et une structure de contenu.
• Reprises silencieuses. Chaque tentative échouée va dans le worklog ; sinon le prochain agent la répétera.
• Le chat comme stockage. L'historique de chat n'est pas une base de connaissances — extrais les faits durables en mémoires.

Une boucle complète

1. Apprends quelque chose → POST /memory (maintenant)
2. Commence une tâche → POST /worklog/:id {kind:"start"}
3. Chaque étape/erreur → POST /worklog/:id {kind:"progress"|"error"}
4. Change du code → commit + entrée de CHANGELOG
5. Termine → POST /worklog/:id {kind:"close", summary}
6. Marque la tâche faite → GET /mind/task/:id/complete

La prochaine session — ou un agent frère qui reprend ta tâche — peut alors tout reconstruire : la liste de tâches dit quoi, le worklog dit comment, les mémoires disent pourquoi.