ENECHANGE所属のエンジニア id:tetsushi_fukabori こと深堀です。
長期間の休業直前（なんならこの記事を書いているタイミングは最終稼働日）のため絶賛ブログエンジニアをやってます。
ブログを書いて生きていくことはできないなと分からせられつつあります。
ENECHANGEではアウトプットは奨励され称賛されるものなのですが、他の業務にリソースを割いていると中々アウトプット作業の優先順位は上げづらいものです。
誰かが定期的にアウトプットしていることでアウトプットしていこうという空気が醸成できたら良いなと思いながら文章を書いています。
（書き溜めをしているものが予約投稿で自動的に出ていっているだけの状況でその空気が生まれるかは難しいかもしれませんが…。）
今回は「既存アプリケーション基盤のコンテナ化プロジェクト」でアーキテクチャの検討に使ったArchitectural Decision Records (ADRs)という手法のご紹介です。
またADRの記録場所として2021/08に正式版となったGitHub Discussionsを使ってみましたのでこれについても少し触れてみます。
背景
2022年3Qで行ったアプリケーション基盤のコンテナ化プロジェクトは言ってしまえばアプリケーションを動かす環境をXからYに変えただけですが、XにはXに、YにはYに適したアプリケーションアーキテクチャというものがあります。（というより、基盤も含めてアプリケーションアーキテクチャです。）
このためアプリケーションには大なり小なり変更が入ることが事前に予想されていました。
一方で今回のプロジェクトではアプリチーム（別記事参照）は直接的にコード変更を行う役割としては参画しておらず、インフラチームに所属する私がアプリケーションのコード修正も行う方針で推進しました。
とは言えアプリケーションの運用保守をするのはアプリチームですので、私の一存でアーキテクチャを決定してアプリチームの今後の運用保守が困難になってしまうことは避けなければいけません。
このような状況のため、
- アプリチームとインフラチームでアーキテクチャについて議論ができる
- アーキテクチャについての議論の結果や結論が管理でき後追いできる
方式で議論を進める必要があります。
またアプリチームは当然他プロジェクトで稼働しているため、議論の方式には「アーキテクチャの議論がアプリチームの負荷にならない」という非機能要件が存在します。
Architectural Decision Records (ADRs)
Architectural Decision Records (ADRs)は軽量な設計ドキュメントです。
重厚長大な設計書を書くのではなく、Markdownのような軽量な方式で以下のような内容を記載します。
- タイトル (title)
- ステータス (status)
- コンテキスト (context)
- 決定 (decision)
- 影響 (consequences)
1つのADRはあくまで「レコード」ですので、何か決定を行うたびにレコードを追加します。
推奨される方式ではADRにはユニークな連番を採番して付与します。RDBのレコードにつけるシーケンシャルなidカラムみたいなものですね。
レコードにはステータスがあります。
よく使われるものは「提案」「承認」「非承認」「置き換え」でしょうか。
ライフサイクルは（読めばわかるかもしれませんが）以下のとおりです。
→→→→→→→→→ 提案┳承認━置き換え ┗非承認
特徴的なのは「置き換え」かと思います。
これは「あるADRの決定が別のADRにより破棄・変更となった場合」のステータスです。
ADRでは過去の決定も「決定」であるので削除したり変更したりしません。
新たな決定が発生し、古い決定が置き換えられた…として扱うわけです。
コンテキストが記載され提案されたレコードは議論（これも記録します）され、決定が下ったらステータスとともに決定を残します。
決定による影響が発生するのでそれもレコードに残します。
ADRについては解説している書籍が日本語でも複数あります。
またいくつかのテンプレートが存在します。
https://adr.github.io/#existing-adr-templates
ここまでの説明でもさほどクリアに定義を書いていませんが、個人的には「正しいADR」にとらわれずチームが運用しやすいフォーマットで運用すると良いと思います。
軽量な書きやすいドキュメントを使って意思決定を残すためにはチームによって必要なフォーマットは異なると思います。
正しさよりもまずは動く「アーキテクチャ設計活動」を実装することが大事かと思います。Done is better than perfect !
ADRの導入で目指したこと
ADRを導入したのは私が実業務で使ってみたかったから…だけではなく、簡便なドキュメンテーションという考え方が忙しいアプリチームと一緒に検討を進めて記録を残す作業にフィットしそうだと考えたからです。
プロトコルが単純なので導入時の学習コストが低く、Markdownであれば書き方も手慣れたものです。
しっかりとした守備範囲の広い1枚のリッチなドキュメントを作るのでなければ良い選択肢になりうると思います。
ADRをどこに実装するか？
ADRという「方式」を導入するとして、次はその「実装」が必要になります。
具体的には
- ADRを何に（どこに）記録するか
- ADRの意思決定までの議論をどう記録するか
- ADRの議論をどのように円滑にすすめるか
などなどを決めて実際に記録できる場所を作らなければいけません。
今回はタイトルにもある通りGitHub DiscussionsにADRを実装して運用することにしました。
GitHub Discussionsの説明は以下のとおりです。
GitHub Discussions は、オープンソースまたは内部プロジェクトに関するコミュニティの共同コミュニケーション フォーラムです。 コミュニティメンバーは、質問をしたり、質問に答えたり、最新情報を共有したり、自由形式の会話をしたり、コミュニティの動向に影響を与える決定をフォローしたりすることができます。
GitHub DiscussionsはissueのようにMarkdownで記述することができ、コメントをつけ、コメントツリーを作る事ができます。
またラベルを設定することもできます。
ここまで見ていただけるとわかると思うのですが
- 普段遣いのgithub
- 議論したい単位でDiscussionを作成できる
- IssueやPRと同様に自動でユニークなインクリメンタルIDが付与される
- Markdownが使える
- 議論ができる
- 記録が残る
- ラベルがつけられる
といった特徴がADRにだいぶ向いています。向いているんだと思います。
これを逃す手は無いなと考え、今回はADRをGitHub Discussionsに実装することにしました。
実際のADRと運用
実際のADRは以下のようなものです。
テンプレートは用意していませんが、ADRに必要な要素は残すことができます。
ステータスはラベルを使うことで実現しました。
issueなどと共通のラベルになってしまうのでここの運用はやや無理があるのですが
Discussionのトップページで一覧表示したときにステータスがわかりやすいのとフィルタリングできる便利さがあります。
Slackを使ったアプリチームとのコラボレーション
上記に加え、GitHub DiscussionsはSlackのGitHubアプリを使ってSlack連携が出来ます。
これによりDiscussionの作成時にSlackに連携ができますし、Discussion本文にGitHubアカウントへのメンションを含める必要がありますが、関係者にメンションをすることが可能です。
こうすることでアプリチームにADRの作成を伝え、アプリチームに議論に参加してもらうことが出来ます。
Slack workflowという感じですね。
現時点でGitHub DiscussionsのSlack連携で出来ないこと
かなり便利なSlack連携ですが、本記事執筆時点では以下のようなことは出来ません。
- コメントのSlack連携
- コメントのReplyのSlack連携
この辺があるとworkflowが充実するのですが、こちらは機能実装待ちとなります。関連するDiscussionがあります。
現状この辺は泥臭くやらざるを得なくて、今回は当面コメント時にSlackに貼りに来るなどしていました。
うまくやる方法（ノー/ローコストで）があれば試したいです。
まとめ
GitHub DiscussionsにADRを実装することで軽量にアプリチームと議論し、アーキテクチャ設計をすすめることが出来ました。
実際の所どのようなことを書くべきかは会社ごと、プロジェクトごとで異なると思いますが、書き味は良く開始が楽でした。
みなさんもぜひアーキテクチャ設計をやっていきましょう！
