はじめに
こんにちは。バイセルテクノロジーズ テクノロジー戦略本部 開発 1 部の市田です。
バイセルでは様々なプロダクトを運用しており、「アーキテクチャディシジョンレコード」(Architecture Decision Record: ADR)のようなドキュメントを活用しながら開発を進めています。今回は、その理由や背景や効果、そしてADRについて詳しく説明します。
背景・課題
バイセルでは様々なプロダクトを長い期間運用しており、チームメンバーが入れ替わることがよくあります。
そのため、メンバーがいなくなると技術選定や設計判断の経緯や根拠などの情報が失われがちでした。また、メンバーが残っていても選定した技術や設計の判断について、PRのレビュワーにしか伝わっていないこともありました。
それにより、以下のような問題が発生していました。
- 今後その技術や設計を使い続けるのか、変更するのかなどの判断が難しい
- 判断の経緯や根拠が残っていないと、後の人がその判断を分析することが難しい
- 理由があってある選択肢を避けたのに、理由が残されていないと後の人がその選択肢を選んでしまう
ADRについて
そこで上記のような課題を解決するためにアーキテクチャディシジョンレコード(ADR)のようなドキュメントを書くことにしました。
ADRは、技術選定や設計判断の結果・経緯・根拠などを記録する軽量なドキュメントです。1つの判断ごとに1つ作ります。例えば、
- Aのツールは採用しない
- Bのツールは採用しない
- Cのツールは採用する
というような形で記録します。
ADRは、GitHubなどコードに近い場所で管理することが望ましいです。これにより、ADRに触れやすくすることができ、レビューを通してチーム全体を設計プロセスに巻き込むことができます。
ADRを導入することで、技術選定や設計判断の背景や根拠が明確になり、後から参照することが容易になります。よって、今後の判断や分析がしやすくなるだけでなく、同じ過ちを繰り返さないようにすることができます。
今回導入したドキュメントはADRをチームによって少し変えた形にしたドキュメントになっています。理由は、通常のADRは負荷が高く導入しても定着しない恐れがあったので、作業を楽にして定着させることを優先させたからです。
以下の章で事例を2つ紹介します。
事例1
正社員5人、業務委託7人ほどの大規模なチームで導入した例を紹介します。
導入したドキュメントの名前は「技術選定・設計判断」で、1つのテーマについて最終判断が決まったら作成することを推奨しています。ADRは1つ1つの候補について判断をしたら書きますが、今回は候補の比較をして最終的に何を採用するか判断をしたらその時にまとめて作成します。
技術選定だけではなく、アーキテクチャ設計やテーブル設計についても記録します。
また、書くハードルを下げるためにGitHubではなくドキュメント管理ツール(バイセルだとConfluence)に書き、書いた内容についてレビューを行わないので、作成にかかる時間は判断によりますが5~10分ほどです。
ドキュメントの例として、「DBのER図ツールにschemaspyを使う」というページを載せます。
- コンテキスト
- 既存のテーブル関係を把握するために重要なER図が手動で書くもので見にくく古くなっていた
- 自動で作成されて便利で見やすいER図が欲しい
- 内容
- schemaspyを使ってER図を作成する
- 根拠
- プラス面
- 自動でER図が作成されるのでメンテナンスコストが低い
- リレーションの線が重なりにくいので見やすい
- カラムやindexの情報が見れたり、検索ができたり高機能
- dockerで動かせるので楽
- バイセルの他のシステムで使っているので慣れていた、バイセルの他の人がプロダクトにJOINしてもすぐに使える
- マイナス面
- ファイルが大量にできるのでgitで管理するのかなど管理方法が難しい
- 環境構築しないとER図が作成できないので、開発者以外が扱うのにハードルがある
- PR
- (実際は導入したPRのリンクを貼っています)
- 選ばなかった選択肢
- draw.io
- 自動でER図を作成したいので選ばなかった
- プラス面
- google drive上で作れるのでローカルで動かす必要がないので開発者以外も使いやすい
- マイナス面
- 手動で書かないといけないので、メンテナンスされず放置されがち
導入にあたって特に反対意見はありませんでした。ドキュメントを書いた方がいい判断が行われているのを見つけたら「書いていただけると嬉しいです」という感じで促していました。
毎回促していたら自然とチーム内に浸透してきて率先して書いていただけることも増えました。
メリット
GitHubにPRを出す必要がなく、作成時間も短いため、書くハードルが低くチーム内に浸透させやすかったです。このように書くハードルが低いと、メンバーが多いチームや業務委託の人がいる場合でも、ルールを効率的に浸透させることが可能となります。
また、技術選定の背景などについての質問が生じた際、ドキュメントを参照することで適切に回答することができます。
さらに、他のチームが同じ技術や設計を採用するための参照資料ともなり得ます。
今回のドキュメントは、ブログなどを書く際にその時の思考を思い出す助けにもなります。そして、エンジニア以外の人々、例えばプロダクトマネージャーなども、プロダクトでどのようなツールが使用されているかを理解することができます。
デメリット
最終判断が決まった後にまとめて書くというアプローチは、細かい内容を忘れる可能性があるというデメリットがあります。
また、内容についてのレビューが行われないため、提供される情報が正確でない可能性もあります。ただし、最終判断をした直後にその内容を本人が記述するため、間違いの可能性は比較的低いと考えられます。
事例2
続いて、正社員4人の小規模なチームで導入した例を紹介します。
事例1と異なり、ADRと同じように1つの判断ごとに1つ作成するのを推奨しており、最初にドキュメントを作成しそれをもとにチーム内で議論を行い判断結果をドキュメントに記載するという形式にしています。
ドキュメントの例として、「GraphQL エラーについて」というページの一部を載せます。
- コンテキスト
- GraphQL API から返るバリデーションエラーのメッセージをフロントエンド上でも表示したい
- 内容
- 調査内容
- 基本方針
- errors[i].message は開発者向けの文言にする。このフィールドはユーザには見せない
- 可能ならエラーのモデルも GraphQL スキーマで定義する
- ユーザに見せていいエラーかどうかレスポンスだけをみて判断できるようにしたい
- 検討
- エラーの分類
- ① GraphQL 標準の errors の extensions フィールドをアプリケーション独自に拡張
- ② Result 型を union で定義する
- ③ Result 型の中にエラー用のフィールドを作る
- 最終判断
- ② にちょっと手を加えたものにする
- 根拠
- プラス面
- ユーザエラーと例外エラーの区別が簡単
- GraphQL スキーマとしてエラーの型を提供できるので FE がエラーの型定義をする必要がない
- マイナス面
- サーバサイドのコードが少し複雑になるかも
- 他の選択肢を選ばなかった理由
- ① をやめた理由
- エラーモデルのスキーマを FE と共有できない
- ③ をやめた理由
- ② のほうが明確にエラーだとわかりやすいため
- 参考リンク
- https://spec.graphql.org/October2021/#sec-Errors.Error-result-format
メリット
都度、判断のたびに書き記すことで情報を忘れにくくなります。
また、開発の意思決定のための議論の叩き台となり、結果として意思決定の質が向上します。開発者はより納得感を持った判断を行うことが可能となります。
さらに、レビューを通じてチーム全体を設計プロセスに巻き込むことができます。これにより、チーム全体の設計レベルが向上します。そして、これらのプロセスは重要なアウトプットの材料となります。
例えば、以下のブログ記事は、上記のドキュメントを基に作成されました。
デメリット
レビューを受けるため、ドキュメントを書く側は体裁を整える必要があります。また、ドキュメントを書かない側にとっても、レビューの過程は負荷となります。
社内勉強会での反響
私のチームでまず導入して効果が見られたので社内勉強会で紹介しました。
ADRについて知らないチームや、ADRと似たようなドキュメントを書いているが書く内容が統一されていなかったチームなどがいて、反応はよかったです。
社内勉強会後に数チームで導入され、現在も継続しているチームがいくつかあり、そのチームからは「ADRを書くことで設計の議論が活発になった」「ADRを書くことで設計の経緯を残せるようになった」といった声が聞かれました。
まとめ
ADRのようなドキュメントを書くことで技術選定や設計判断の経緯や根拠などの情報を残すことができるようになりました。
使っている技術に関わらず導入が可能ですし、ドキュメントなので試しに導入して合わなかったらやめることもできシステムに悪い影響を与えることもありません。
この記事を読んで興味を持った方はぜひ導入してみてください。
最後にBuySell Technologiesではエンジニアを募集しています。興味がある方はぜひご応募ください。
