はじめに
デリッシュキッチンのiOSアプリ開発を担当している池田です。今回はiOSチームでADR（Architecture Decision Record）を用いてチームの意思決定の記録を残し始めた話をします。正確には個人でADRを記録していたものの、チームでの運用はしていなかったため、この機会にチームでの管理を開始しました。
背景
デリッシュキッチンのiOS開発は当初少人数で行っていたため、実装に関する詳細なドキュメントを作成するという習慣がありませんでした。しかし近年、メンバーの入れ替わりや新入社員の参加により、設計や実装の経緯を説明する機会が増えてきました。これを良い機会と捉え、私が個人で記録していたADRをチームに共有することにしました。
ADRについて
ADRとは「Architecture Decision Record」の略で、プロジェクトにおける重要な意思決定を記録するためのドキュメントです。チームでの決定事項とその経緯が不明確になり、都度確認が必要になったり、経緯を知る人が退職してしまったりした経験は多くの方があるでしょう。ADRを残すことで、このような意思決定プロセスの消失を防ぐことができます。
ADRにまとめる主な項目は以下の通りです。
- タイトル：何についての決定か簡潔に表現
- ステータス：提案中、承認済み、廃止、変更など
- コンテキスト：その決定が必要になった背景や状況
- 決定事項：採用した選択肢とその理由、検討した代替案
- 結果：この決定による影響（メリット・デメリット）
ADRの始め方
ADRを始めるにはいくつかのステップがあります。
- テンプレートの作成と合意 - 最小限の項目でシンプルに始めることが重要です。チームで合意したフォーマットがあれば、一貫性を維持しやすくなります。
- 記録場所の決定 - アクセスしやすく、気軽に編集できる場所が理想的です。GitHubやConfluenceなど、チームが日常的に使用するツールが最適です。
- 最初のADRの作成 - 完璧を目指すよりも、まずは記録することを優先しましょう。
ADRの実践例
私たちのチームではGitHub DiscussionにADRをまとめることにしました。everyではConfluenceを利用しているため、そこに記載する選択肢もありましたが、開発関連の内容とその他の情報を分離する目的からGitHub Discussionを選択しました。 ただ、振り返ってみると、PdMやデザイナーなどの非エンジニアとの共有や、複数リポジトリに対するADRの一元管理の観点からは、Confluenceでの管理の方が適していたかもしれません。
私たちのチームでは前述の5項目をベースとしたシンプルなテンプレートを作成しました。タイトルには決定事項を記載し、ステータスにはGitHub Discussionのカテゴリー機能を活用することにしました。実際のテンプレートは以下の通りです。
# 経緯 # 提案内容 # 承認した場合の結果 ## メリット ## デメリット # 備考
最初のADRはサンプルの意味合いも込めて「ADRを使って意思決定事項を残す」というテーマで作成しました。
ADRの具体例
おわりに
デリッシュキッチンのiOSチームではADRの記録を始めました。これにより、新しいメンバーが参加した際にもスムーズに開発を進められるようになると考えています。 また、近年ではAIを活用した開発が進んでいますが、明確なドキュメントがあることでAIに対しても適切な指示を出しやすくなり、プロジェクトの文脈を理解した上でより質の高い提案を得られるようになるでしょう。
重要なのは完璧を目指すのではなく、まずは小さく始めて習慣化することです。最初は簡単な記録から始め、徐々に洗練させていけば十分です。意思決定はコードと同様に重要な資産であり、チーム全体で共有・管理することで、長期的な開発効率と品質向上につながります。
皆さんもぜひADRを取り入れ、誰もが開発しやすい環境を整備していきましょう。
