こんにちは。LINEでAndroidアプリの開発を担当しているMoriです。先日、After DroidKaigi 2025 at LINEヤフー & ZOZOというイベントで、「モバイルアプリ開発のためのDesign Doc実践ガイ ド」というテーマで登壇しました。このセッションでは、「どんなDesign Docを書けばチームにとって役立つのか？」をテーマに、サンプルアプリを題材にして具体的な書き方を紹介しました。
この記事では、発表内容をもとにDesign Docの目的や効果的な活用法、そして実践的な書き方のポイントをまとめます。
Design Docの目的
Design Docは設計書の一つで、開発者間のコミュニケーションのために用いられます。設計書には詳細設計書、APIドキュメント、コーディング規約などさまざまな種類が存在しますが、Design Docは開発者自身が主体となって作成し、プロジェクトの全体像や方針についてチーム内で議論するために作られます。
主な目的は以下の3つです。
大きな手戻りを防ぐ
開発の後半で重大な問題が見つかると、その修正には膨大なコストがかかります。最近はプルリクエスト単位で細かくレビューする流れが一般的ですが、個々の変更はよくても全体を組み合わせると破綻するケースがあります。事前にドキュメントを作って全体像を確認することは、安定した開発を支える重要なステップです。
品質改善
ここでいう品質とは、使い勝手やパフォーマンスといった外部品質、メンテナンスのしやすさといった内部品質の両方を含みます。設計段階でチーム全体で議論することで、改善点を早期に発見し、品質を底上げできます。
情報を残す
コードを読めば最終的な実装は理解できますが、「なぜこの設計にしたのか」はわかりません。一見別のアプローチのほうがよさそうなので修正しようとしたら、実はその方法には問題があった、という経験はよくあると思います。Design Docに経緯を残しておくことで、過去の判断を踏まえてよりよい選択ができるようになります。また、コードを読むよりも全体像がつかみやすくなるというメリットも存在します。
Design Doc運用のコツ
Design Doc は書くことが目的ではなく、チームの思考を整理し、開発の質を高めるための道具です。以下のポイントを押さえておくと効果的に運用できます。
チームで議論しながら作る
最初から完璧なドキュメントを目指す必要はありません。いったんラフに全体像を書いたら、チームで議論しながら細部を詰めていきましょう。一人では気づけない点をチームの知見で補うことで、より質の高いドキュメントになります。
開発途中でも方針を変更する
開発を進めるうちに、最初の想定と違ってくることはよくあります。「一度決めたから変えられない」ではなく、よりよい方向に柔軟に修正していく姿勢が重要です。
追加の開発時は新しいDesign Docを作る
仕様変更のたびに既存のドキュメントを更新し続けるのは手間がかかります。Design Docは使い捨てのドキュメントとして、プロジェクトごとに新しいページを作ることをおすすめします。そうすることで、過去の意思 決定を履歴として残しつつ、ドキュメント作成のコストを減らすことができます。一方で、アーキテクチャ図や仕様書のように常に最新であるべき情報は、Design Docとは別に管理するとよいでしょう。
サンプルアプリを例に考えてみよう
ここからは、実際のサンプルアプリを例に、どのようにDesign Docを構成していくかを紹介します。
このアプリは、ユーザが画像の任意の位置にメモを書き込めるモバイルアプリです。この記事ではAndroidアプリを例にDesign Docの書き方を紹介しますが、iOSなど他のプラットフォームでも基本的な考え方は同じです
最初のDesign Doc
Design Docは書きやすいところから書き始めましょう。目的は最初に書きやすいパートの一つだと思います。今回のアプリであれば、以下のような説明を最初に書いておくとよいでしょう。
画像メモアプリ MVP
目的
ユーザが任意の画像に対して簡単かつ直感的にメモを付与できる環境を提供する。これにより、スクリーンショットや写真に対して補足説明や気づきを直接残すことが可能になる。
MVP (Minimum Viable Product)フェーズ として、まずはローカル完結で動作するアプリケーションを作成する。
明記しておくことで、今回のフェーズでは何にフォーカスしているのか、どこは今回の対象外かがわかりやすくなり、議論がスムーズになります。
次は、システムの全体像を図に起こしておくと便利です。データの流れや依存関係を一目で理解できるようになります。
全体像
また、重要な箇所については詳細設計として書いておきます。
例えば、Androidだと画像を選択する方法が複数あります。このアプリではどのように画像を選択するかを記しておくとよいでしょう。
その際、他に検討した方法についても残しておくとよいでしょう。そうすることで、重複した議論を避け、あとから見返したときもその時の意思決定を知ることができます。
詳細設計
画像の取得
画像の取得はAndroidが提供するPhoto Pickerを利用する。これにより、特別な権限なく画像の取得が可能になる。
共有ストレージから画像が消されたり移動されるリスクを考慮し、アプリ固有のストレージにコピーしてから利用する。
画像の取得の代案
アプリにandroid.permission.READ_MEDIA_IMAGES権限を付与すると、ContentResolverを使って共有ストレージの画像ファイルにアクセスできるようになる。 これはプライバシーおよびセキュリティ上のリスクや、ユーザからの拒否・離脱の可能性を高めるため、本アプリでは採用しない。
参考：https://developer.android.com/training/data-storage/shared/media?hl=ja
データベースなど永続化する情報や、外部との通信など、あとから修正するのが困難な箇所はあらかじめ議論しておくとよいでしょう。
データベース
Roomを使って管理する。
チームで議論する
ここまで書けたら、一度チームで議論してみましょう。1人では気づけない観点が得られることが多く、ドキュメントの質を大きく向上させられます。
たとえば、吹き出しの三角形の部分の位置をどう決定するのか聞かれるかもしれません。
こうしたフィードバックをもとに、どんどんドキュメントをブラッシュアップしていきましょう。吹き出しの位置については以下のようなフローチャートを書くと明瞭になります。
吹き出しの位置決定ロジック
例：
バックアップ機能を作ってみよう
ここまで一通り書いてみましたが、新しい機能開発として、バックアップ機能を追加したいとします。バックアップされた項目は複数のデバイスで確認できるようにします。
この後に私の例を紹介しますが、その前に「どんな観点をDesign Docに含めるべきか」ぜひ一度考えてみてください。
画像メモアプリ: バックアップ機能 Design Doc
目的
現行の「画像メモアプリ」はローカルデータのみを扱っている。本開発では、画像およびメモのバックアップと複数デバイス間での同期を提供する。同期はリアルタイム共同編集を目的とせず、アプリ操作のタイミングに応じて実行される。
全体像
画像およびメモは、次のタイミングで同期される。
- アプリを開いたタイミング
- 特定の画像を開いたタイミング
- 特定の画像を編集し、その画像を閉じたタイミング
同期のデータフロー
同期はAndroidXのWorkerを使って行う。
メモは1件ずつではなく画像単位でスナップショットとして送受信し、意図しない差分ズレを防ぐ。
アップロードしたデータとサーバ側で保持したデータに差分があれば、サーバ側でマージし保存される。サーバ側でのマージは、メモ単位で最新のタイムスタンプのものが優先される。
ダウンロード時にローカルのデータが変わっていたら、上書きせずにアップロードからやり直す。これにより、予期せずローカルのデータが消えることを避ける。
ネットワークエラーなどで同期に失敗した場合、AndroidXのWorkerにより、バックオフ遅延を使って自動でリトライされる。最初のリトライは10秒後とする。例：10秒後、20秒後、40秒後、80秒後…
DB設計
新たにImageMetaテーブルを追加する。
Memoテーブル
削除に関する同期を正確に行うため、削除されたメモはis_deletedをtrueにして残しておく。その際、textなどコンテンツの内容は空にする。
ImageMetaテーブル
上記はあくまで概要のみにとどめています。チームの方針などにより、より深く議論する点はあるでしょう。例えば、簡略化のため本記事では各メモIDはクライアント側でUUIDを発行していますが、サーバ側でより厳密なID採番を行う方が望ましい場合もあるでしょう。
Design Docを書こう
ここまで、Design Docの書き方や運用の仕方について、サンプルアプリを例に紹介してきました。「しっかりしたドキュメントを作らないと」と身構えてしまうと、どうしても時間がかかりすぎてしまいます。本当に重要なポイントにフォーカスし、気軽にチームで議論できる状況を作ることが理想的だと考えています。
この記事が、Design Docを気軽に活用しながら開発をよりスムーズに進めるための一助になれば幸いです。
参考文献
- M. Ubl, Design Docs at Google, Industrial Empathy, https://www.industrialempathy.com/posts/design-docs-at-google/ （参照2025年4月19日）
- 石川宗寿, Design Doc の書き方 / How to Write a Design Doc (Ja ver.), Speaker Deck, https://speakerdeck.com/munetoshi/how-to-write-a-design-doc-ja-ver-dot （参照2025年4月19日）
- 森 篤史,「よいコードの道しるべ 変化に強いソフトウェアを作る原則と実践」,マイナビ出版
