ADR : donne enfin de la mémoire à tes agents IA

Ton agent IA redémarre à zéro à chaque session. Sans trace écrite, il te re-propose une approche que tu as déjà testée et jetée la semaine dernière. Tu réexpliques le même contexte, tu réécartes les mêmes fausses bonnes idées. En boucle.

La solution existe déjà côté dev, et elle n'a rien de nouveau : les ADR (Architecture Decision Records) pour les décisions, et un journal de contexte pour le reste. Markdown, versionné dans git, requêtable par ton agent.

Le vrai trou de mémoire : décisions et contexte

Le contenu, tout le monde le stocke : du code, des notes, de la doc. Ce qui manque presque toujours, ce sont les décisions (« on a choisi X plutôt que Y, et voici pourquoi ») et le contexte (« ce module existe pour telle contrainte »).

Or c'est exactement ce dont ton agent a besoin pour ne pas tourner en rond. Un modèle ne devinera jamais que tu as déjà rejeté une approche il y a trois sessions. Il faut l'écrire.

L'ADR : une décision, un fichier

Un ADR, c'est un fichier = une décision, avec trois blocs :

• Contexte : le problème, les contraintes.
• Décision : ce qu'on a choisi.
• Conséquences : ce que ça implique, les compromis acceptés.

Deux règles importantes :

1. Un ADR a un statut : proposed, accepted, superseded.
2. Un ADR est immuable. On ne modifie pas une décision passée : on en écrit une nouvelle qui remplace l'ancienne (superseded_by). L'historique reste lisible.

Le format vient de Michael Nygard et est documenté par Martin Fowler ; le template Markdown MADR est un bon point de départ.

Le journal de contexte : garder les approches rejetées

À côté des décisions, je tiens un journal de contexte qui garde aussi les approches rejetées et pourquoi. C'est ce qui empêche l'agent de te reproposer une idée déjà écartée. La règle est simple : tout ce qui doit survivre entre deux sessions vit dans un fichier, pas dans le chat.

La structure que j'utilise (dans Obsidian)

Décisions/
  2026-07-14 - Stocker les dates en UTC.md
Contexte/
  paiements - contexte.md

Avec un frontmatter clair sur chaque décision :

type: decision
status: accepted        # proposed | accepted | superseded
date: 2026-07-14
tags: [archi, timezone]
superseded_by:

Je suis la convention de Steph Ango (CEO d'Obsidian) : le dossier = le type de contenu, le frontmatter = les métadonnées. Un fichier ne change jamais de dossier ; on change son statut. Résultat : le tout est directement indexé et requêtable par le graphe, donc exploitable par mes agents.

Ce qu'il faut retenir

Le contenu, tout le monde le stocke. Les décisions et le contexte, presque personne — et c'est précisément ce qui manque à tes agents. Écris-les en Markdown, versionne-les, rends-les immuables. Ton agent arrête de tourner en rond.

Je montre tout le workflow en vidéo : regarder sur YouTube.

Et je t'ai préparé un kit ADR prêt à l'emploi (templates + structure) : récupérer le kit.