Maintenir un enregistrement de décision d’architecture (ADR)

Un enregistrement de décision d’architecture (ADR) est l’un des livrables les plus importants d’un architecte de solution. Votre architecture est l’accumulation de ses décisions, de sorte que l’ADR est effectivement un enregistrement de la façon et de la raison pour laquelle le système est venu être sa forme actuelle.

L’ADR documente toutes les décisions clés, y compris les alternatives que vous avez exclues, pour des exigences architecturalement significatives. Incluez uniquement les choix qui affectent la structure du système, les attributs de qualité clés ou sont difficiles à inverser. Chaque entrée capture le contexte, les justifications et les implications d’une décision, en intégrant les exigences et les contraintes dans les effets documentés de la décision.

Implémenter une ADR

Démarrez l’ADR au début d’une charge de travail et maintenez-la tout au long de la durée de vie de la charge de travail. Une ADR doit être démarrée pour les charges de travail brownfield et, si les données sont disponibles, elles doivent être générées rétroactivement en fonction des décisions passées connues. L’ADR sert de journal d’ajout uniquement. Ne revenez pas en arrière et modifiez les enregistrements acceptés. Si une décision change, écrivez un nouvel enregistrement qui remplace l’original et liez les deux ensemble. Cette approche préserve l’histoire de votre pensée et le rend clair quand et pourquoi la direction a changé. Le dossier s'étend au-delà de la conception initiale pour inclure des éléments de conception visant à répondre aux futures exigences fonctionnelles et non-fonctionnelles.

Caractéristiques suggérées d’un enregistrement individuel

• Soyez cohérent avec l’anatomie de chaque enregistrement. Concevez un modèle d’enregistrement et suivez-le de manière cohérente.

  Un enregistrement doit inclure des éléments cohérents tels que :

  • Instruction de problème avec le contexte
  • Options prises en compte
  • Résultat de la décision
    • Inclure des compromis importants pris avec cette décision
    • Enregistrez le niveau de confiance de la décision. Parfois, une décision architecturalement importante est prise avec une confiance relativement faible. Documenter que le statut de confiance faible pourrait s’avérer utile pour les décisions de reconsidération futures.
  • État, tel que Proposé, Accepté ou Remplacé. Le suivi de l’état rend l’état actuel de chaque décision clair, en particulier lorsque le nombre de décisions augmente.

• Divisez une décision en plusieurs si une décision architecturale va entraîner plusieurs phases, telles que des approches à court terme, à moyen terme et à long terme. Consignez chaque phase comme propre dossier de décision.

• Évitez de masquer les conséquences des décisions intentionnellement ou accidentellement.

• Incluez toujours le contexte et la logique. Un enregistrement sans justification perd sa valeur au fil du temps, car les parties prenantes ne peuvent pas évaluer si la décision s’applique toujours lorsque les circonstances changent.

• Conservez les enregistrements succincts, assertifs, pertinents et factuels.

• Évitez de transformer les enregistrements de décision en guides de conception. Si davantage de justification ou d’idées de conception sont disponibles, fournissez un lien vers un document en tant que matériel supplémentaire, mais la décision doit être claire et autonome sans ce matériel.

Référentiel de documentation de charge de travail

Ce journal doit être facilement disponible et stocké de manière ouverte avec la documentation de la charge de travail. Une décision prise mais jamais enregistrée sera probablement oubliée, ce qui entraînera des débats répétés ou des changements ultérieurs qui contredisent inconsciemment l’intention originale.

Un architecte peut aider une équipe de charge de travail à obtenir des recommandations d’excellence opérationnelle en aidant à établir et à maintenir un référentiel de documents et de ressources. Les architectes aident les équipes à placer toutes leurs ressources dans le référentiel, comme ce journal des décisions. Ils encouragent également l’adoption unifiée des équipes d’une seule source de vérité à utiliser pour référence, audits et réponse aux incidents.

Étapes suivantes

Liste de contrôle de l’architecte

Plus de ressources

Pour obtenir des exemples de modèle, visitez l’organisation Architectural Decision Records GitHub.