Écrire des ADR (Architecture Decision Records) avec Claude Opus 4.7

Opus 4.7 est sorti hier 16 avril 2026. L’un des usages discrets mais à fort impact : la production d’ADR (Architecture Decision Records), ces documents courts qui capturent les décisions techniques importantes. Beaucoup d’équipes disent qu’il faudrait en écrire, peu le font. 4.7 retire la friction.

Pourquoi les ADR restent une bonne idée

Un ADR documente une décision technique avec son contexte, les alternatives considérées, le choix retenu, et les conséquences. Quelques pages par décision. Pas un gros document d’architecture, mais une trace traçable.

Les bénéfices quand tu en as :

• 6 mois plus tard, tu te souviens pourquoi vous avez choisi Postgres et pas MongoDB
• Un nouveau dev comprend le raisonnement passé sans demander à tout le monde
• Les décisions qu’on veut challenger plus tard ont leur point de départ documenté

Les raisons pour lesquelles peu d’équipes en font : ça prend du temps, le format reste flou, l’impulsion initiale retombe vite.

Comment 4.7 change la donne

Le travail de formulation (structurer, rédiger, lisser) est ce qui prend du temps dans un ADR. La décision elle-même, l’équipe la prend. La mise en mots est souvent la friction.

4.7 prend en charge cette mise en mots. Tu décris la décision en bullets, tu obtiens un ADR formaté.

Le workflow en 15 minutes

1. Tu ouvres une session Claude avec un template ADR.
2. Tu décris en 5-8 bullets : le problème, les options considérées, le choix retenu, les conséquences.
3. Claude produit un ADR structuré (1-2 pages).
4. Tu révises (5 minutes), tu ajoutes le contexte interne que le modèle ne pouvait pas deviner.
5. Tu publies dans ton repo /docs/adr/ ou ton wiki.

Total : 15 minutes pour un ADR propre là où il en fallait 45-60 à la main.

Le template à utiliser

Format classique en 6 sections :

Title. Courte phrase qui résume la décision.

Status. Proposed / Accepted / Deprecated / Superseded.

Context. Quel problème on résout.

Decision. Ce qu’on a décidé.

Consequences. Positive et négative, on ne cache pas les trade-offs.

Alternatives considered. Ce qu’on a écarté, avec le pourquoi.

Le prompt qui marche

“Écris un ADR au format Michael Nygard pour la décision suivante : [bullets]. Le style doit être factuel, le format doit être markdown, le document doit tenir sur 1-2 pages max.”

4.7 produit un ADR exploitable en un prompt. Tu itères éventuellement sur un point précis si tu veux plus de détail sur les conséquences ou les alternatives.

Les limites

Claude ne connaît pas l’historique de ton projet. Tu dois fournir le contexte. Si tu as des décisions précédentes qui impactent la nouvelle, référence-les dans ton brief.

Claude ne sait pas quelles sont tes contraintes métier non explicitées. Tu dois les poser clairement.

Claude peut produire un ADR joli mais léger en contenu si ton brief est léger. La qualité est proportionnelle à l’input.

Intégrer les ADR au flow d’équipe

Une pratique qui marche : chaque décision technique importante déclenche un ADR. Critère pour “important” : tout ce qui concerne plusieurs services, plusieurs équipes, ou qui aura un impact long-terme.

Les PR qui mettent en oeuvre la décision référencent l’ADR. La revue de la PR inclut la revue de l’ADR.

Le wiki ou le repo /docs/adr/ devient la source de vérité. Les nouveaux arrivants le parcourent à l’onboarding.

Un exemple concret

Brief que j’ai passé à Claude récemment :

“Décision : passer de Redis à Dragonfly comme cache applicatif. Raison : besoin de plus de perf sur les pics de traffic, sans changer de modèle de programmation. Alternatives : rester sur Redis avec sharding, passer à Memcached, utiliser Valkey (fork OSS Redis). Choix : Dragonfly parce que compatible Redis API, perf validée en bench, support commercial dispo. Risques : maturité moindre que Redis, dépendance à un seul vendor. Plan : migration progressive sur 6 mois.”

L’ADR produit : 1.5 pages propres, exploitables, avec le format attendu. Je révise, j’ajoute 2 paragraphes sur le contexte business interne, je publie.

Les ADR rétroactifs

Si ton équipe n’a jamais fait d’ADR, ne rattrape pas l’historique. Commence par les décisions futures.

Pour les décisions passées critiques (stack principale, choix d’architecture fondamentaux), tu peux faire un ADR rétroactif si le besoin se présente. Mais ne t’infliges pas un rattrapage massif.

FAQ

Quel outil pour stocker les ADR ? Dans le repo git avec les autres docs, format markdown. Ou dans un wiki interne (Notion, Confluence). Le git a l’avantage du versionning.

Combien d’ADR par mois en équipe de 10 devs ? Typiquement 2 à 5. Pas toutes les PR ne méritent un ADR, seulement les décisions structurantes.

Peut-on laisser Claude écrire l’ADR et ne pas reviser ? Non. La révision humaine est obligatoire. Elle prend 5 minutes, elle valide que le doc reflète vraiment la décision de l’équipe.

---

Je dirige Linkuma, plateforme de netlinking low cost avec 40 000 sites au catalogue et 15 000 clients. On maintient un stock d’ADR produits avec Claude pour tracer nos décisions. Retours terrain sur linkuma.com, promos hebdo sur deals.linkuma.com.