Dans presque chaque projet que je connais, il y a quelque part un wiki avec des diagrammes vieux de trois ans. Personne ne leur fait confiance, donc personne ne les lit, donc personne ne les entretient.
Les conséquences sont toujours les mêmes. Qui ne touche un projet que rarement ne sait pas quel est l'objectif, ce qui a été décidé et pourquoi. Alors il hésite à toucher au code. Et quand quelque chose tourne mal, il manque une base pour une discussion factuelle : la décision était-elle mauvaise à l'époque, ou seul le contexte a-t-il changé ?
Avec les agents de codage, cela s'aggrave, car le code change plus vite que jamais. Dans la partie 1, j'ai montré pourquoi j'ai créé mon propre harness sparc. Cette partie explique comment il tient la documentation à jour. Je voudrais commencer par une décision qui n'a pas tenu 24 heures.
Une décision qui s'est remplacée elle-même
Les Architecture Decision Records (ADR) consignent ce qui a été décidé, et avec quelles connaissances. J'en ai décrit les bases il y a deux ans dans Architecture Decision Records. Dans sparc s'y ajoute une règle stricte : le contenu d'un ADR décidé ne change plus. Un ADR « corrigé » discrètement après coup perd exactement l'information dont on a besoin quand quelque chose tourne mal.
Mais une règle ne sert que si quelqu'un la vérifie. Ma première solution (ADR-0004) était un hash sur le contenu de chaque ADR décidé, stocké dans un champ locked dédié. Cela fonctionnait. Mais après chaque décision, quelqu'un devait recalculer le hash, et ce champ ne fait pas partie du format standard MADR.
Le lendemain est venue l'évidence : git connaît déjà chaque version d'un ADR. ADR-0004 a donc été remplacé par ADR-0008, exactement comme la règle l'exige. Le nouvel ADR consigne aussi ce que la décision coûte :
Chosen option: "Compare with the first committed version that has a decided
status", because git already holds the data. The ADR files stay in the MADR format.
- Good, because there is no `--lock` step and no field outside MADR.
- Good, because the check also protects `decision-makers`, `consulted`,
`informed` and committed amendments.
- Bad, because a project without git loses the protection. The check reports this.
- Bad, because the protection starts only with the first commit of the decision.
ADR-0004 n'a pas disparu. Il est toujours dans le dépôt, avec le statut superseded by ADR-0008. Qui veut savoir pourquoi il n'y a plus de hash de verrouillage trouve toute l'histoire. Pour moi, c'est la meilleure preuve que la règle fonctionne : elle a proprement remplacé sa propre première mise en œuvre.
Amender ou remplacer
Que se passe-t-il quand quelque chose change dans une décision ? L'agent pose une seule question : la modification touche-t-elle le contexte, les options, la décision ou ses conséquences ? Si oui, un nouvel ADR est créé et l'ancien est remplacé. Si non, c'est un amendement, que je dois approuver explicitement :
### 2026-10-22: Warn one time for the same findings
Approved by: [@sventropy](https://github.com/sventropy), chat
A live test showed that a warning makes the agent reply one more time.
The hook keeps the digest of the last findings for each project.
Il n'en faut pas plus comme modèle de statuts : proposé, accepté ou rejeté, plus tard amendé, déprécié ou remplacé. Et toute décision n'a pas besoin d'un ADR. Une décision est pertinente quand elle sera difficile à changer plus tard ou qu'elle touche plus d'une partie du système.
Ce qui compte le plus pour moi, c'est le « Bad, because ». Chaque décision a un prix. L'écrire crée de l'acceptation, car lorsque ce prix tombe plus tard, il était connu et sciemment accepté.
Un foyer par fait
Les ADR ne sont qu'une partie de la documentation. Pour le reste, l'idée de base est simple : chaque fait se trouve à un seul endroit. Tous les autres documents y renvoient. Un fait présent à deux endroits finit tôt ou tard par se contredire. Avec des agents qui écrivent beaucoup et vite, plutôt tôt.
C'est pourquoi chaque projet sparc a le même ensemble fixe de documents : README, AGENTS.md, backlog, changelog, specs, diagrammes C4, canvas et ADR. Chaque document a un rôle propriétaire, et il est défini de quoi il est le foyer. La section architecture du README, par exemple, compte au plus trois phrases et renvoie aux diagrammes, au canvas et aux ADR au lieu de les répéter.
Les diagrammes C4 en texte
Pour la vue d'ensemble de l'architecture, sparc utilise deux niveaux du modèle C4 : contexte système et conteneurs. Les diagrammes sont du texte Mermaid dans le dépôt, pour que les agents puissent les modifier, que git montre les différences en review et que GitHub les affiche sans outil supplémentaire :
C4Context
title System Context: sparc
Person(dev, "Developer", "Starts changes and approves them")
System(sparc, "sparc", "Claude Code plugin for spec-driven work with agents")
System_Ext(openspec, "OpenSpec CLI", "Manages specs and changes")
Rel(sparc, openspec, "Calls")
Le prix figure dans l'ADR : Mermaid C4 est moins complet que Structurizr, et les deux diagrammes ne partagent pas de modèle commun. Pour que personne n'oublie le diagramme, chaque design de modification doit nommer son « impact C4 », ou écrire explicitement « No C4 impact ».
Le canvas : une page pour la discussion
C4 montre la structure. Pour les personnes qui ne veulent pas lire de diagrammes, sparc utilise l'Architecture Communication Canvas : objectifs, parties prenantes, exigences de qualité, décisions clés et risques sur une seule page, compréhensible aussi pour le management. J'ai décrit comment formuler des exigences de qualité mesurables dans Qu'est-ce qui rend un logiciel bon ?.
Une section joue un rôle particulier : « Core Risks and Missing Information ». Tout ce qu'un agent ne peut pas prouver y atterrit. Une hallucination cachée devient ainsi une question visible, et le canvas montre à tout moment ce que l'équipe ne sait pas encore.
Détecter la dérive plutôt que compter sur la discipline
Un ensemble fixe de documents ne sert à rien si personne ne l'entretient. Dans sparc, l'entretien fait donc partie de chaque étape : quand une modification est proposée, elle entre dans le backlog. Quand elle est terminée, changelog, README, canvas et ADR sont mis à jour.
S'y ajoute un script sans LLM et sans dépendances. Il vérifie les sections obligatoires, les placeholders, les phrases trop longues, le changelog et la version ainsi que les règles des ADR, et il donne le même résultat à chaque fois. Un hook dans Claude Code l'exécute dès qu'un agent a terminé. Là aussi, il y a une décision délibérée : le hook avertit, mais il ne bloque pas. Au milieu d'une tâche, la doc est souvent volontairement désynchronisée, et un hook bloquant forcerait l'agent dans une boucle. Le contrôle ne devient contraignant qu'à la clôture d'une modification.
À retenir : un ADR sur une page
Si vous ne retenez qu'une chose de cet article, retenez cette structure. Elle suit MADR, est réduite à l'essentiel et fonctionne avec ou sans agent :
---
status: proposed
date: YYYY-MM-DD
---
# Short title of the problem and the solution
## Context and Problem Statement
2 or 3 sentences: the situation and the question.
## Considered Options
- Option 1
- Option 2
## Decision Outcome
Chosen option: "Option 1", because <reason>.
- Good, because <consequence>
- Bad, because <consequence>
## Amendments
<!-- Only approved additions. Never change the text above after the decision. -->
Les deux règles qui vont avec : écrivez toujours au moins un « Bad, because ». Et ne modifiez jamais un ADR décidé, amendez-le ou remplacez-le.
Conclusion
Une documentation d'architecture à jour n'est pas une question de discipline, mais de structure. Quand chaque fait a un foyer, que l'entretien fait partie de chaque étape de travail et qu'un contrôle déterministe signale immédiatement la dérive, la documentation suit le rythme du code, même quand c'est un agent qui écrit le code.
La troisième partie (à paraître le 8 novembre 2026) porte sur le workflow qui se cache derrière, et sur une architecture qui semblait parfaite sur le papier et qui a pourtant disparu.