ZOZOFITにおけるADRを利用した意思決定を残す文化作り

ogp

はじめに

こんにちは。計測プラットフォーム開発本部バックエンドチームの佐次田です。普段はZOZOMATやZOZOGLASSなどの計測技術に関わるシステムの開発、運用に携わっています。去年の夏に、ZOZOFITというサービスを北米向けにローンチしました。

本記事では、ZOZOFITのローンチまでに遭遇した意思決定における課題と、ADRというドキュメンテーション手法を用いた解決までの取り組みについて紹介します。

目次

計測プラットフォーム開発本部 バックエンドチームとは

計測プラットフォームバックエンドチームは、ZOZOGLASS/ZOZOMAT/ZOZOSUITによって採集される計測データにまつわるバックエンド開発を担うチームです。アプリやブラウザに対するクライアントAPIや、ZOZOTOWN内部のマイクロサービスのAPIにおいて、徹底的に低レイテンシにこだわりを持つことと、高可用性を保つことを目指しています。

ZOZOFITとは

ZOZOFITは2022年に発表した体型管理を目的としたフィットネスアプリです。ZOZOSUITの計測技術を利用したサービスであり、2023年3月時点では、体型計測および身体3Dモデルのデータ・体脂肪率の表示機能を提供しています。

zozofit

開発中に直面した課題

ZOZOFITの開発を進めるにあたり先んじてアーキテクチャを選定する必要がありました。選定基準として、過去に運用実績があるZOZOSUITやZOZOMATなどの知見は重要なものでした。実際に私たちのチームではスピードと品質を担保するために過去実績があるアーキテクチャを採用することに決め改善する必要があるものは新しいチャレンジを行うことに決めました。その後、開発を進めるにあたり以下の課題に直面しました。

過去の背景が分からず決断しにくい

私たちのチームはメンバーの半数が新しく参画したメンバーであり、過去の決定はまばらに文書化されている状態でした。メンバー内でも過去の意思決定を把握できているメンバーが偏っている状態であり、新規メンバーは決定の背後にある動機を理解できていない状態でした。新規事業においてはスピード感も重要となるため、ローンチまでに過去の決定をキャッチアップするための同期的なコミュニケーションも取りにくい状態でした。そのため、新規メンバーは新しい意思決定に踏み込みにくい状態となっていました。

意思決定の結論が追いにくい

ZOZOFITにおける意思決定はアジャイルに何度も行われ、意思決定の機会は数多くありました。しかし、過去の決定はSlackでの会話やGitHubでのコミュニケーションなどに点在しており、最終的な結論を理解するためには多くの議論を遡って見ていく必要がありました。議論が追いきれなかった場合は再度同じ提案をする必要があり、何度も同じテーマについて会話する状況となっていました。

意思決定の認識合わせに時間がかかる

私たちのチームはフルリモートでの業務を主としており、海外チームと共に開発を進めています。そのため非同期でのコミュニケーションを重要視しており、SlackやGitHub等のツールを使って積極的に会話をしています。

ZOZOFITにおける海外チームとの協業についてはブログ記事が公開されていますので、気になる方はこちらの記事をご参照ください。

technote.zozo.com

より良い決定のためには、背後にある動機や判断材料が重要となります。しかし、背景などの情報が伝わっていない状態で会話を進めていたため、情報を集めるために各チームと都度コミュニケーションが発生していました。また、非同期でのコミュニケーションはレスポンスがすぐに返ってくるとは限らないため、別作業とコミュニケーションでのスイッチングコストも課題となっていました。

ADRの導入

私たちは上記の課題を解決するためにADRという手法を導入することにしました。

ADRとは

ADRとはArchitecture Decision Recordの略称であり重要なアーキテクチャの意志決定を、背景、結果と共に記録したドキュメントです。

Micheal Nygard氏は「DOCUMENTING ARCHITECTURE DECISIONS」においてADRの思想について言及しており、意思決定の理由と背景を追跡することは難しいため記録しておくべきだと述べています。

One of the hardest things to track during the life of a project is the motivation behind certain decisions. A new person coming on to a project may be perplexed, baffled, delighted, or infuriated by some past decision. Without understanding the rationale or consequences, this person has only two choices:

  1. Blindly accept the decision.
  2. Blindly change it.

プロジェクトの中で最も追跡が困難なことの1つは、ある決定の背後にある動機である。
プロジェクトに新しく参加した人は、過去の決定に戸惑い、困惑し、喜び、あるいは激怒するかもしれません。
このような場合、その理由や結果を理解できないまま、以下のどちらかを選択することになります。

  1. 決定を盲目的に受け入れる
  2. やみくもに変更する

実際に私たちのチームにおいても決定の背景や動機を読み取れない問題が起きており、導入することで課題解決に繋がると考えました。

しかし、ADRは決定のドキュメントを記録していく手法であり、Agile Manifestoにおいては包括的なドキュメントより動くソフトウェアを重視すると記載されています。その問題については、以下のように述べています。

Agile methods are not opposed to documentation, only to valueless documentation. Documents that assist the team itself can have value, but only if they are kept up to date. Large documents are never kept up to date. Small, modular documents have at least a chance at being updated.

アジャイルな手法は文書化に反対しているわけではなく、価値のない文書に反対しているだけである。 チーム自身を支援する文書は価値を持つことができますが、それは最新の状態に保たれている場合に限られます。 大きなドキュメントは決して最新の状態に保たれません。小さく、モジュール化された文書であれば、少なくとも更新される可能性があります。

ドキュメントを小さい単位で記録していくことで、より扱いやすく色々な人にとって価値のあるものとなります。ADRは仕様書のように最新の状態に更新し続ける必要はなく意思決定のログとして扱えるため、後追いで見た時に読み手が解釈しやすく、価値があるドキュメントとなります。

上記を踏まえて、以下の項目を意識してADRの導入を行うこととしました。

  1. 意思決定の背景・動機が残っている状態となること
  2. ドキュメントは小さな粒度で残していくこと
  3. ADRは仕様書ではなく、決定のログとして残していくこと

展開

ADRのフォーマットは展開のしやすさを考慮してシンプルなものを採用することにしました。テンプレートは数多く公開されていますが、私たちのチームでは下記のテンプレートを参考にすることにしました。

https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/templates/decision-record-template-by-michael-nygard/index.md

ADRのフォーマット

実際の運用では上記テンプレートの一部解釈を変更して運用しています。使用しているテンプレートは以下となります。

YYYY/MM/DD ADR Title

# Status
# Situation
# Context
# Material for decision
# Decision
# Consequences

セクションごとの詳細は以下となります。

  • Status
    • 意思決定のステータス
    • proposed/accepted/rejected/deprecated/
    • この項目があることで、ドキュメントの状態が一目で分かるようになります
    • ステータスの更新は忘れがちなので注意が必要です
  • Situation
    • 決定時のビジネスにおける制約や会社、チームの状況
    • 重要な決定ほど外的要因に左右されるため、決定に作用した状況を記載します
    • 意思決定の状況があることでテクノロジー以外の部分で決定に作用した内容を把握できるようになります
  • Context
    • 決定が必要となった背後にある動機や理由
    • 決定内容は記録が残っていなかったとしても最新のプロダクトからある程度把握が可能ですが、決定の背後にある動機や理由は記録がなければ読み取ることは非常に困難です
    • 読み手に対して何故この意思決定が必要となったのかを伝える上でとても重要な項目です
  • Material for decision
    • 決定時に参照した材料
    • 決定の材料を記載します。意思決定をスムーズに行うために必要な項目です
  • Decision
    • 最終的な決定内容と理由
    • 最終的な決定を簡潔に記述します
    • 決定に至った背景・理由も記述することで、後追いで見た時により価値が高いドキュメントとなります
  • Consequences
    • 最終的な結果
    • 意思決定が及ぼす結果を記載します
    • 決定時に結果を記入できるものは記録し、振り返りが必要なものに対しては後追いで記述します

使用ツール

私たちのチームではドキュメントツールとしてConfluenceを採用しており、ADRの記録先としてもConfluenceを採用することに決めました。対抗馬としてGitHubを採用するかどうか迷いましたが、以下の理由から見送ることとしました。

  1. Confluenceの方がよりカジュアルにドキュメント作成が可能
  2. 開発者以外の方からも気軽にアクセス可能な状態としたかった

一方でGitHubを使用することで、ソースコードと同列にADRを管理できるようになります。この決定についてはどちらが最適か結論が出ていないため後ほど振り返る予定です。

チームへの展開

チーム展開時にはADRを残していきたい旨をADR形式でチームに展開し相談しました。私たちのチームではADRを記録する対象をアーキテクチャのみに絞らず、チームで残すべきと判断した意思決定は全て記録するようにしました。これにより、アーキテクチャに関する内容やチーム内のルールなど、多くのカテゴリのADRが記録されることになり煩雑になることも懸念しましたが、運用がスムーズにいくまでは考えることを少なくするため全ての決定を記録する体制を取っています。また、過去の意思決定も思い出しを含めて可能な限りADRとして起票するようにしました。ZOZOFITは新規事業なため、開発に携わっている私たちが記録しなければ後で参加したメンバーが困ると判断したためです。起票に時間はかかりましたが、これにより過去の殆どの意思決定がADRとして残っている状況を作りました。

ADRの一例

ADRの一例を紹介します。ZOZOFITの開発を進める中で私たちはIDaaSとしてCognitoを採用することに決めました。しかし、メールアドレスの変更処理において意図していない挙動となることが判明したため以下のADRを記録しています。

# 2022/05/16 Cognitoのメールアドレス変更の処理を自作する

# Status
- proposed/ **accepted**/ rejected/ deprecated/ superseded

# Situation
- ZOZOFITの開発初期のタイミング
- IDaaSとしてCognitoを採用しており、Cognitoを使ったPoC実装が完了している
- チームメンバーにCognitoについて詳しいメンバーはいない
- ZOZOFITのリリースタイミングの目処は決まっている

# Context
- 2022年5月の時点においてCognitoを使用する場合に「変更後のメールアドレスが未検証の状態でも、Cognitoのユーザーのメールアドレスが更新されてしまう」問題が起きることが判明した
- これによって以下の問題が発生する
  - ユーザーはリフレッシュトークンの有効期限が切れた場合、変更前のメールアドレスが使えない状態となり、ログインできなくなる
  - ユーザーは他人のメールアドレスを自身のメールアドレスとしてZOZOFITに登録できてしまう
- 上記は許容できないため、対応策を決定する必要がある

# Material for decision
- 問題が発生するまでの操作フロー
  - ユーザーはZOZOFITのアプリ上でメールアドレスの変更を行う
  - サーバーはCognitoのUpdateUserAttributesのAPIを呼び出しメールアドレスを更新する
  - Cognitoはメール未検証状態でユーザーのメールアドレスを更新する
    - このタイミングで過去のメールアドレスと書き変わる
- 以下の記事において、この問題について言及されています
  - https://kohei1116.hateblo.jp/entry/2020/02/16/aws-cognito#1-UpdateUserAttributes
  - https://zenn.dev/dove/articles/78ecf08b51ee0c
- 対応策としては2つ考えられそうです
  - Cognitoのメールアドレス変更の処理を自作する
    - Cognitoにおけるユーザーのメールアドレスの検証処理を自作し、ZOZOFITサーバー側の責務とする
  - 別のIDaaSを利用する
    - 別のサービスの調査を行い、同様の事象が発生するかどうか確認する
    - 起きないのであれば、メールアドレス変更処理を自作した場合と比較し、どちらを選択するか決めた方が良さそう

# Decision
- Cognitoのメールアドレス変更の処理を自作する
  - 新規でAPIを書く必要があるが、既にCognitoを用いての開発が進んでおり別のIDaaSを選択するのに比べて工数が低いと判断

# Consequence
- 結果として
  - メールアドレス変更処理を行うAPIを自作する
  - 認証周りの実装をCognitoの外に持つことになるが許容する
- 2023/03
  - ADRに対して振り返りを行いました
    - 背景にある事象はCognitoにおいて解決されており、メールアドレス変更処理を自作する必要はない状況となりました
    - メールアドレス変更処理フローを変更するかどうかについては後続のADRで起票します
    - 参考
      - https://docs.aws.amazon.com/ja_jp/cognito/latest/developerguide/user-pool-settings-email-phone-verification.html

上記のADRについては後日振り返りを行い、2023年3月時点で問題が起きないことが分かっています。

過去の意思決定を記録しておくことで振り返りの実施をスムーズに行えるようになり、次の意思決定に繋げることができました。

振り返り

結果としては、ZOZOFITにおいて約40件のADRが記録されています。

課題はどう解決されたのか

  • 過去の背景が分からず決断しにくい
    • ADRを残すことで、新規の意思決定が行いやすい状態となりました
    • 最も効果があった部分は、意思決定に対して振り返りを行うことが容易となった点です
      • 当時のタイミングでは最適だったとしてもタイミングによっては選択肢が変わることもあると思います。ADRを残すことで過去の知見を再利用しながら新しい意思決定に繋げることが可能となりました
    • 実際にZOZOFITローンチ前の意思決定に対して振り返りを行い、新しいアクションが生まれました
  • 何度も同じテーマを議論する
    • あれ、これ何でしたっけ?となった時に記録が残っていることで同じことを議論する回数が減りました
  • 意思決定の認識合わせに時間がかかる
    • ADRを運用していく中で認識合わせのスピードが上がりました
    • 意思決定のフローを事前にADRをproposedな状態で記入した後に議論する運用とすることで、必要な背景・材料が揃った状態で会話を開始できるようになり、認識合わせに必要な時間が削減されました

メリット

導入してみて感じたメリットをまとめると以下となります。

  • 透明性の向上
    • チーム内における情報量がフラットとなった
    • チーム外からも気軽にドキュメントを参照できるようになり、APIやアーキテクチャ選定の思想や理由を伝えやすくなった
  • 集約性の向上
    • 過去の情報を遡るときはADRを参照すればOKとなった
  • 可読性の向上
    • 議論が提案状態なのか、結論が出ているのか一目で判断できるようになった
    • ADRはフォーマットに沿っており結果の把握が行いやすくなった

デメリット

デメリットではないですが、ADRを記録する対象には向き不向きがあると感じました。例えば仕様書のようなものは最新の状態に合わせるために何度も更新が必要なためADRとして扱うには不向きだと感じました。また、運用面においても文書化は意識しないと行われないため、導入当初は旗振り役が意識して啓蒙活動をしなければ、浸透までは行き着きにくいと感じました。

最後に

ADRを導入することで過去にローンチした計測技術・アーキテクチャの知見を活かし、新しい価値を素早く生み出すように努めています。ADRを導入することで過去の意思決定を気軽に参照できるようになり、会話が発生し、学びを得る機会が増えたと感じています。

計測プラットフォーム部バックエンドチームでは、ZOZOFITのように、日本国内に限らず新しいサービスを開発していくバックエンドエンジニアを募集しています。

ご興味のある方は、以下のリンクからぜひご応募ください!

hrmos.co

カテゴリー