【ITニュース解説】System Design Docs for Flutter Mobile Teams: A Brutal Guide

システム開発におけるシステム設計ドキュメント（SDD）は、これから作るシステムの概要や動作をまとめた資料だが、しばしば現場で課題となる。多くの開発者は新しい機能の実現を望む一方で、実際には誰も読まない、あるいはすぐに古くなるドキュメントの作成に時間を費やしている。これは、ドキュメントが書き手の自己満足のために作られ、読者の視点に立っていないためだ。結果として、情報が曖昧で冗長になり、最終的にはプロジェクトの混乱や無駄な時間、責任転嫁につながってしまう。

システム設計ドキュメントは、あらゆる変更や機能追加に必要となるわけではない。いつドキュメントを作成し、いつコードを直接書くべきかを見極めることが重要だ。例えば、アイコンの変更やラベルの調整といった軽微な修正、デバッグ画面やテーマ切り替え機能のようにシステムにほとんど影響を与えない独立した機能の場合、ドキュメントは不要である。新しいアイデアを素早く試すプロトタイプ開発の段階では、完璧なドキュメントよりも開発速度が優先される。もし、変更内容をチャットツールで簡単に説明できる程度であれば、ドキュメント作成よりもすぐにコードを書き始める方が効率的だ。

しかし、ドキュメントの作成が不可欠となる場面もある。例えば、システムの認証機能、データの状態管理、バックエンドとの連携方法といったシステムの根幹に触れる変更の場合、その影響が広範囲に及ぶため、詳細な記録が必要となる。モバイルチームだけでなく、バックエンドチーム、品質保証（QA）チーム、プロダクトマネージャー（PM）など、複数のチームが連携して機能を作り上げる場合も、共通認識を持つためにドキュメントが役立つ。特定の状態管理手法や新しい外部ライブラリといった新しいアーキテクチャパターンを導入する際も、その理由や使い方を明記することで将来の混乱を防ぐことができる。セキュリティ上のリスク、法的な要件、性能に関わる重要な変更がある場合や、特定の機能について開発者間で意見が対立し議論が必要な場合も、ドキュメントに記録を残すことが解決の糸口となる。将来的にその設計について責任を問われる可能性があると感じるならば、その時に備えてドキュメントを残しておくべきだ。

本当に役立つシステム設計ドキュメントは、短く、明確で、具体的な行動につながるものだ。それは、「何を作るのか？」「なぜこの方法で作るのか？」「それが正しく機能すること、どうやって確認するのか？」という三つの基本的な質問に簡潔に答えることを目的とする。

例えば、ユーザー認証システムを新しく構築する場合、ドキュメントにはまず「安全で高速なログイン機能、特にパスワードレス認証の導入が必要である」という「問題」を明確にする。次に「Firebase Authを利用し、パスワードとメールアドレスでの認証を予備とし、対応デバイスでは生体認証も導入する」という「解決策」を提示する。アーキテクチャとしては「ステートレスなバックエンド、セッション管理にJWTトークンを使用し、デバイスに安全に保存する」と記述する。さらに「JWTトークンが24時間で期限切れになること」や「パスワードハッシュにbcryptを使用すること」といった「リスク」も記載する。最後に「ログイン時間は2秒未満、認証失敗率は5%未満とする」といった「成功基準」を具体的に示すことで、何を目指し、どう評価するのかを明確にする。

別の例として、決済システムと連携する機能を開発する場合、複数のチームが関わるプロジェクトとなる。この場合、モバイルチーム、バックエンドチーム、QAチームが連携すること、決済に関するAPIはRESTful形式で、セキュアなトークン交換とエラー処理戦略が必要であるという「アーキテクチャ」を共有する。さらに、API仕様の策定、フロントエンド開発、QAテストそれぞれの「タイムライン」を明記することで、各チームの役割とスケジュールを明確にする。

システム設計ドキュメントの理想的な構成は、シンプルで整理された単一のディレクトリ構造に収まることだ。「FlutterSystemDocs」という大元のディレクトリの下に、「Architecture」（アーキテクチャ設計の決定事項や状態管理、アプリの構造図）、「Features」（各機能の詳細な仕様やシーケンス図）、「UI-Kit」（UIコンポーネントのカタログやテーマに関する情報）、「Platform」（iOSとAndroid固有の違い）といったサブディレクトリを配置し、その他にリリースに関する情報などをまとめる「RELEASE.md」ファイルを置く。このシンプルな構造を保つことで、必要な情報に素早くアクセスでき、余計なものが増えるのを防ぐ。

具体的に何をドキュメントに記録すべきかというと、まず「アーキテクチャの決定事項」だ。なぜ特定の技術を選んだのか、その理由をファイルごとに明確に記述する。次に「システムの流れ」を、シーケンス図やデータフロー図、エラー処理の方法などを用いて分かりやすく表現する。各「機能の仕様」については、その問題点、解決策、起こりうる例外（エッジケース）、そして達成度を測るための指標を具体的に記述する。また、再利用可能なUIコンポーネントである「ウィジェットのカタログ」を作成し、スクリーンショット、コード、プロパティ、使用例をまとめることで、チーム全体のUIの一貫性を保つ。iOSとAndroidといった「プラットフォーム間の違い」については、両者で実装が異なる場合にのみ記述し、共通の部分は不要だ。

逆に、ドキュメントに書くべきではないこともある。例えば、Flutter開発における一般的な慣習（画面の土台となるScaffoldや汎用コンテナのContainerの使い方など）は、開発者にとって自明な情報であるため、わざわざドキュメント化する必要はない。一時的なコードの変更や回避策（ハック）についても、コードのコメントとして残すのが適切であり、ドキュメントに含めるべきではない。また、長期的な影響を持たないような些細な決定の全てを記録する必要もない。本当に重要な、長期的に影響を及ぼす決定に絞ってドキュメントを作成することが肝心だ。

作成したドキュメントは、一度作って終わりではない。常に「生きた情報」として維持していく必要がある。最も効果的な維持方法は、コードの変更を伴うプルリクエスト（PR）と同時に、関連するドキュメントも更新することだ。これにより、コードとドキュメントの間にずれが生じるのを防ぐ。古くなったドキュメントは、「非推奨」とマークするのではなく、思い切って削除するべきだ。情報が多すぎたり、古い情報が残っていると、かえって混乱を招くからだ。また、コードレビューのプロセスにドキュメントのレビューも組み込むことが重要だ。もしドキュメントが不明確だったり、情報が不足していたりすれば、それがマージをブロックする理由となる。これにより、常に質の高いドキュメントを維持できる。

このアプローチがうまく機能する理由はいくつかある。第一に、本当に重要な情報に「集中」しているため、無駄が少ない。第二に、iOSとAndroidのような「クロスプラットフォーム」開発において、両者の違いを適切に扱いつつ、共通の理解を促進できる。第三に、ウィジェットカタログのように、ドキュメントがデザインシステムの一部となり、再利用可能な資産として機能する。最後に、ドキュメント自体が重いプロジェクトにならないため、「軽量」に運用できる。

最後に、厳しい現実を認識する必要がある。もしシステム設計ドキュメントが開発の負担になっているのなら、そのやり方は間違っている。良いドキュメントとは、更新する方が、それを無視して後で問題になるよりもずっと速いものだ。チームメンバーが共通の疑問を抱く前に、その答えをあらかじめ提供してくれる。そして、新しい開発者がプロジェクトに参加した際に、何週間もかかるようなオンボーディング期間を数日に短縮してくれる。もし、あなたのチームのドキュメントがこれらの利点をもたらしていないなら、一度全てを削除し、このアプローチに基づいて最初から作り直すことを検討すべきだ。

システム設計ドキュメントは、書いたあなた自身のためだけのものではない。それは、次にそのシステムを触ることになる未来の開発者のため、もしかしたら半年後のあなた自身のためなのだ。もしドキュメントがなければ、そのシステムの混沌とした状態を受け入れるしかなくなる。しかし、ドキュメントがあるのなら、それを短く、厳しく、そして具体的な行動につながるものに仕上げるべきだ。あいまいな表現は排除し、「もしかしたら」といった可能性の話ではなく、明確な「決定」を記述する。そして、過度に文書化することにとらわれず、本当に役立つものを構築するために行動を始めることこそが最も重要だ。