ADR（アーキテクチャ・デシジョン・レコード） というものが codegine の記事で紹介されていました。

https://codezine.jp/article/detail/18736

ADR とは、アーキテクチャ上の設計判断を記録したもので、MD等の軽量なドキュメント形式で蓄積しようというものです。 記事中でも、参照がありますが、Michael Nygard氏がブログで紹介したところから広まっていったようです。 この記事も、Google翻訳して、読んでみることをお勧めします。

https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions

アジャイル開発では、体系的にまとめられた大きなドキュメントを作成することは行いません。 ドキュメントをまったく作成しないわけではないけれども、必要最小限なドキュメント構成になります。

この場合に問題になるのが、例えば、プロジェクトに新しく誰かが参加したときです。

システムの仕様だけではなく、過去の経緯なども、知らないので、アーキテクチャーの変更に迫られたときに、 過去の経緯に関係なく、盲目的に変更するしかありません。 このような変更は、地雷を踏んでしまったり、過去の問題が再燃する可能性があったり、とても怖い決断になります。

ADR は、なぜそのアーキテクチャーが必要なんだっけ？とかの導入経緯や、どういう影響があるんだっけ？を記録として残していきます。 体系的で重厚なドキュメントを書くのではなくて、なぜその決定がなされたかを記録します。

このやり方は、ThoughtWorks社のMartin Fowler氏も、technology radar で評価していました。 そして、現在の radar では、ADR を拡張して設計変更も同じ方式で管理する 「Design system decision records」（設計・デシジョン・レコード） を評価しています。

https://www.thoughtworks.com/radar/techniques/design-system-decision-records

Google や Amazon も取り入れています。

• https://cloud.google.com/architecture/architecture-decision-records?hl=ja
• https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/adr-process.html
• https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/appendix.html

そして、この ADR のドキュメントは、その検討がされていた一時期だけ更新されるドキュメントで、それ以降のメンテナンスは、不要だというのがいいです。 後々、同じ領域の設計話題が出たときには、新しい ADR を作成して、過去の ADR へのリンクを張るだけで、過去の決定をたどることが可能となります。

直観的に、これは良いなと感じました。そして、アーキテクチャーの枠を超えて設計変更の経緯を追跡する「設計・デシジョン・レコード」がもっといいです。 設計書は書かないけど、設計変更の経緯は残すというのは、継続的なエンハンスの開発がされているアジャイルのプロジェクトに最適です。

サンプルです。例えば docs/ADR/adr-NNNN.md で追加していきます。

```markdown
## Title
勤怠管理システムにおけるクラウドベース認証サービスの採用

## Status
Proposal

## Date
2024-01-26

## Context
既存の勤怠管理システムは、オンプレミスでの認証メカニズムを使用している。
しかし、リモートワークの増加とスケーラビリティの要求により、より柔軟かつセキュアな認証システムが求められている。

## Decision
AWS Cognitoのようなクラウドベースの認証サービスを導入して、ユーザー認証プロセスを管理する。

## Consequences
### Positive
スケーラビリティと可用性が向上し、リモートワークに対応しやすくなる。

### Negative
既存のシステムとの統合には初期コストがかかり、スタッフのトレーニングが必要。

## Compliance
- 新しい認証プロセスはGDPRおよびその他のデータ保護法規に準拠する必要がある。

## Notes
- Author: hoge
- Version: 0.1
- Changelog:
    - 0.1: Initial proposed version

```

とても、シンプルです。ADR に関して、このサンプルを読む以上の学習は不要です。独自にルールを追加して運営するのも寛容です。

ドキュメントがなくて、システムの仕様理解が進まないというプロジェクトは、たくさんあります。 だからと言って、今から、体系的にドキュメントを作れるわけでもないので、特段、対応策が講じられないのが現状ですよね。作ってしまうとメンテナンスに工数を取られるし。

でも、ADR なら、すぐに始められるし、とてもライトで強力な施策になるのではないでしょうか？

うちの会社の開発標準としても、組み込んで然るべきな気がしてます。