はじめに

この記事は CARTA アドベントカレンダー2024まとめ - CARTA TECH BLOG の 12/17 の記事です！

はじめまして。株式会社DIGITALIO でエンジニアをしている mittsu です。

私が所属するチームでは今年の7月頃から ADR（Architecture Decision Record）を利用しています。
ADR とは、「アーキテクチャ決定を文書化する最も効果的な方法の1つ」であり、意思決定の背景や理由を明確に残す仕組みを提供します。
「引用元: O'Reilly Japan - ソフトウェアアーキテクチャの基礎」

基本的な ADR の構造は以下の通りです。

この記事では、ADR 導入・運用時に取り組んだことについて紹介します。

対象読者

ADR について関心のある方
ADR の導入を検討している方
ADR に限らず、新しい手法やツールを導入したい方

課題の本質を見つめ直す

以前、チームはドキュメント管理に対して、以下の課題を抱えていました。

口頭での確認が多く、記録が残らないことがある
記録が1箇所にまとまっておらず、調査に時間がかかる
記録の書き方やテンプレートがなく、書くハードルが高い

具体的に、以下のような問題が発生していました。

過去の設計や実装がどういう方針で行われたのか調べたが情報が見つからないケース
複数のリポジトリをまたぐ実装の際、どのリポジトリの Issue、PR に記載したか分からず、情報が見つけにくい
チームミーティングで議論した内容や意思決定が議事録に残っていないことがある。残っていたとしてもいつ話したか分からず情報を見つけるのが大変

コンテナ化やバッチ基盤の移行など、インフラに関わる対応が多いチームのため、過去の設計内容を遡れないことや、検討中の設計をレビューしにくいことが大きな課題でした。
また、今年4月に私を含めた新しいメンバーが加わりチームが大きくなったことで、より効果的に情報を共有する必要性が高まりました。

そこで、解決策の1つとしてADRの導入を進めました。
しかし、導入を進める中で、ADRの書き方に合わせた運用フローを作成してしまいました。
ツールの導入が目的化してしまうケース、心当たりありませんか。
導入準備を担当した私は、一時的にこの状態に陥りました。

そこで改めてチームで課題を再確認し、課題解決に有効な ADR の特徴を取り入れる姿勢で進め直しました。
その際にチームに合わせて工夫した点は以下です。

アーキテクチャに限らず、意思決定が発生したら記録して良い
書くハードルを下げるため、項目を絞ってテンプレートを用意
- ADR のステータス・コンプライアンス項目は導入初期では採用しない
意思決定のレビューをしやすくするため、GitHubで管理する

その結果、意思決定が記録として残っており、振り返りが可能になりました。
書くハードルを下げた結果、約5ヶ月で19の ADR が作成されました。

改善サイクルを回す

ツールや施策は、導入して終わりではありません。
改善サイクルを回して、より良いものにしていく必要があります。

日々のチームミーティングで、「もっとこうしたら良いのでは」といった意見が出ることがあり、いくつかの改善を実施してきました。
今回はその内の2つを紹介します。

1つ目は、意思決定の結論をファイル名にするという変更を行ったことです。
それまでは「xxxの設計について」や「xxxの検討」といったファイル名が多く、ファイルを開かないと意思決定の結論がわからない状態でした。
後から振り返りしやすいように検索性を上げることが大事と考え、改善しました。
改善後は、ファイル名に意思決定の結論が含まれるようになり、情報をより探しやすくなりました。

2つ目は、検討した選択肢を記載する際、利点と懸念点を必ず記載するようにテンプレートに追加したことです。
最近チームでは、約8年前に構築したバッチ基盤の移行をしていました。
しかし、初めに現状調査をしたところ、ドキュメントが十分に残っておらず、詳細を知っている方がほとんどいない状態でした。
なぜベストプラクティス通りにしなかったか、どんな課題があってその意思決定をしたのかが後々振り返ることができると、数年後の意思決定の機会に役立ちます。
そのために、採用したかどうかに限らず、検討した内容に利点と懸念点を明記し、なぜその意思決定をしたのかが詳細に分かることを心がけるようにしました。
今後は、ADR に意思決定が残っており、将来の開発の意思決定の参考になることを期待しています。