チームの意思決定の経緯を DR（Decision Record）で残す、顧客の選択の自由を奪わないコミュニケーション設計

デスク周辺機器はこれだと決めてから数ヶ月。舌の根も乾かぬうちに新しいガジェットを購入してしまいました…。たにもとです。

さて、Gaji-Labo はクライアントの事業成長を支えるためプロダクトチーム支援を行なっています。
今回は Gaji-Labo のビジョン「すべての人々にとって選択の自由があることが当たり前な世界をつくる」ために行なっている顧客とのコミュニケーションについて紹介します。

DR を中心とした意思決定コミュニケーション

DR とは、ADR から A をとった造語です。
ADR（Architecture Decision Record） は、プロダクトの技術的な意思決定やその経緯を文書化したものです。

ADR とはなにか？

プロダクトのアーキテクチャ上の重要な決定を、後からプロジェクトに加わるメンバーや将来の自分自身のために、明確かつ簡潔に記録するものです。

ADR には下記のような内容が記載され、活用されます。

• 決定の背景：「なぜその技術/パターンを選んだのか」「なぜ別の選択肢を排除したのか」という背景やトレードオフを理解するのに役立つ
• 意思決定までの経緯・議論の内容：チーム全体でアーキテクチャの意思決定の経緯を共有し、新しいメンバーへのオンボーディングを容易にする
• 一貫性の維持：時間の経過とともに、アーキテクチャの原則や方向性がブレるのを防ぎ、一貫性を維持する
• レビューと監査：後で決定が問題を引き起こした場合に、その判断の根拠を振り返り、レビューや監査を可能にする

スキーマライブラリに「Zod」を採用すると仮定した場合の記述例を紹介します。

## Decision：実際に決定した内容

- Headress CMS からデータをフェッチしてくる際に利用するスキーマのライブラリに「Zod」を採用する

## Context：決定の背景

- TypeScript との親和性が高い
- 広く利用されているライブラリでリファレンスや知見が多いため
- 現時点で開発が活発で長期的なメンテナンスが見込まれる（安定が見込める）
- 社内の他プロジェクトでも利用が確認できたため、社内に知見があると考えたため

## Consideration：比較検討や議論内容

1. Zod
GitHub スター数: 38.7k
最新の更新が2025年6月
TypeScript で書かれている
https://github.com/colinhacks/zod

2. Yup
GitHub スター数: 23.4k スター
最新の更新が2023年2月
TypeScript で書かれている
https://github.com/jquense/yup

3. Joi
GitHub スター数: 21.1k スター
最新の更新が2024年の6月
JavaScript 用のデータ検証ツール
https://github.com/hapijs/joi

4. Valibot
GitHub スター数: 7.7k スター
最新の更新が2025年5月
TypeScript で書かれている
バンドルサイズが小さい（700バイト未満）
https://github.com/fabian-hiller/valibot

5. TypeBox
GitHub スター数: 5.7k スター
最新の更新が2025年3月
TypeScript で書かれている
https://github.com/sinclairzx81/typebox

更新が安定的で、TypeScript の恩恵を受けやすいという観点で「Zod」と「Valibot」で検討することにしました。
Zod には Zod mini というバンドルサイズを抑えたものが存在します。
Zod mini は Zod と比べるとバンドルサイズが 10kb ほど小さいですが、インターネット環境が整備されている前提での 10kb 少くすることは大きな意味を持たないとされています。
バンドルサイズが小さい分機能が制限されます。
機能を制限したのを選んでしまうとサービスを広げていくときの障害になる可能性が高いと考えて Zod の方で検討をしました。

次に Valibot はバンドルサイズがさらに小さく Zod と比較してパフォーマンスは定評があります。
サーバーレスなどの限られた環境ではかなり魅力的です。
人員の流動性もプロジェクトの課題になることを予測するとできるだけ学習コストが低いライブラリを選ぶのが良いと考えました。

## Consequences：この決定によって予測される結果
- Zod を利用してスキーマの定義を行う

## References：参考情報
※あれば記載する。

決定だけでなく、調査した内容やその時の思考を残しておくことがポイントです。
なぜその判断をしたのか後の開発者が詳細な意図を把握することができ、その後の判断の糧となります。

また、書くだけでなくチームでレビューし複数の視点から妥当性を判断することが重要です。

ADR ではなく DR と呼称する理由

ADR は、言葉の通りアーキテクチャの意思決定やその経緯をテキストとして残すものです。

• アーキテクト以外の意思決定も残してほしい意図を汲み取りやすくするために
• プロダクトやプロジェクトがスタートした段階ではアーキテクト以外の意思決定が多くの暗黙知が発生することの懸念があったため

記載する内容は同じですが、上記の理由から「ADR」ではなく「DR」と呼称することに決めました。

DR を残すことのメリット

Gaji-Labo は顧客のプロダクト開発を支援をしているので「いなくなると困る」と頼っていただくのは嬉しい反面、Gaji-Labo のメンバーが暗黙知を抱えてしまうと顧客が Gaji-Labo 以外を選択できない状況になってしまいます。

これは、冒頭に書いたGaji-Laboのビジョンや顧客を支援するスタイルとは真逆のものです。

プロダクト、デザイン、アーキテクト全ての意思決定の経緯を DR（Decision Record）として残すことにで新しいメンバーが加わった時のドキュメントとして活用することも可能です。

その時の開発だけでなく、中長期的にプロダクトチームが成長して Gaji-Labo が支援を終えられるようにしていくことを大切にしています。

DR 文化を醸成させるための具体的なステップ

文化を醸成させるためには粘り強く、継続して取り組むことが重要です。

浸透するまでの期間はチームの状況によって様々ですが、「DR に書いてあったよね？」など DR を主語に会話が生まれ始めたらDR ってなんかいいねフェーズの成功だと言えると考えています。

下記に浸透させるまでの具体的なステップを記載しました。

DR ってなんかいいねフェーズ

1. DR の導入意図と今後やることについてチームに説明をする
2. 意思決定を DR にまとめて情報が DR に集約されていることを認知させる
3. 書いた DR を承認するフローに顧客側の意思決定者を巻き込み、DR をテキストコミュニケーションの中心に据える

次に自分以外のメンバーに DR を書いてもらえるようになる必要があります。
ここでは「書いてもらう」ことを最優先に DR を残すことの習慣化を目指していきます。
下記が具体的なステップです。

DR をみんなで残していこうフェーズ

1. チーム内で DR のステータス確認や DR を書くべき事案について確認する時間を作る
2. 旗振り役以外の人にも DR を書いてもらう
   • とにかく議論すべきことを漏らさないことを最優先にする
   • 内容の過不足はチームで埋めるようにして書き手の負担を最小限に保つ
   • DR を書いた時のペインポイントをメンバーにヒアリングして解消する
3. DR を書く基準を決めて、メンバーから DR を書くことに声を上げやすい環境を整える

大きく2つのフェーズを紹介しましたが、ここまでくると自発的に動いてくれるメンバーが多くなり、チームメンバー全員が DR を意識して業務に取り組んでいる状態になると考えています。

DR を残すプラットフォームは、チームに馴染みのあるものが望ましいです。
新しいツールを導入することは、操作が増え DR を書くことの障害になります。

慣れ親しんだツールに検索できる機能があれば十分ではないかと考えています。
Notion なら データベースを作成することをオススメしますし、GitHub なら GitHub Discussions を利用するのがオススメです。

DR 導入の失敗する時のパターン

どれだけ負担が少ないとはいえ、これまでやったことがないものに対しては実施のハードルが感じる人が多いのも事実としてあります。

• 書くことへのハードルが高い
• 更新されず形骸化する

などの問題が発生する可能性は高いです。
そんな時は発信の仕方を工夫してみると良いでしょう。

書くことへのハードルをとにかく下げる

書くことへのハードルを低くなるように発信をします。
特に DR として残すべき事柄を取りこぼさないことが重要であることを伝えると良いでしょう。

DR のテンプレートがあることは前提として、とにかく残すことが大切で 1 人ではなくチーム全員で書いていくものであることをチームに伝えることが大切だと考えています。

文化として定着させるためにまずは意識の中に DR の存在を大きくしていくことを第一として活動をしていくことが重要です。

更新されず形骸化することを防ぐ

• 忙しくて更新できなかった
• 意思決定に記載できるようなものがなく更新頻度が減ってしまった

などが原因で DR が形骸化してしまうことがあります。

原因は、DR を書くことを上手くワークフローへ組み込めてないことだと考えています。
意識できていないと形骸化し、本来の意味すら失われてしまいます。

よって、DR に対して意識を向ける機会を増やすことで解消できると考えています。
例えば、定例会議にて DR の状況や DR にすべき事案がなかったかを確認する時間を設けるなどが挙げられます。

まとめ

DR は暗黙知になりやすい意思決定やその経緯を可視化し、コンテキストを共有することで、チームは Gaji-Labo や特定の人に依存せず自走できるようになります。

Gaji-Labo はビジョンを達成のため顧客の「選択の自由」を守ることが使命です。
よって、プロダクトに参画した時からチームを離脱した時のことを考えて活動します。
顧客が Gaji-Labo に依存しないための活動の一環として DR を中心としたコミュニケーションについて紹介しました。

もしチームが「特定のメンバーに依存している」「過去の判断が分からなくなる」という課題を抱えているなら、完璧な DR を書くことより、まずは残すことから始める DR 文化の導入を検討してみてはいかがでしょうか。

Gaji-Labo フロントエンドエンジニア向けご案内資料