Design Docsを活用して会計Plusの設計プロセスを改善した話

これは、Money Forward Engineering 1 Advent Calendar 2022 21日目の記事です。

今回はマネーフォワードクラウド会計Plus(以下会計Plus)の設計プロセスをDesign Docsを活用して改善した話をします。プロダクト設計のプロセスや知識共有などに課題感を持っている方には是非読んでいただきたいです。

会計Plusが抱えていた課題

会計Plusの開発プロセスには以下のような課題がありました。

設計の意図が開発に関わったエンジニアにしかわからず、開発・運用が属人的だった

設計で考えた意図や結果が体系的に管理されていなかったため散在しており、情報が後から参照できない状態になっていました。機能によっては設計資料が残っているものもありましたが、設計の資料の品質にかなりばらつきがある状態です。これにより、設計に関する知識が開発に関わったエンジニアにしか共有されないため、開発や運用業務の属人化の原因になっていました。

全体を見通した設計が不十分だった

会計Plusはスクラム開発に取り組んでおり、1週間スプリントで設計からリリースまでの開発サイクルを回して開発を進めています。スプリントごとに設計と実装を都度行うわけなのですが、実装する部分の設計のみで開発が進んでしまい、プロダクト全体で見た時に全体最適でない設計になってしまっていたり、考慮できていなかったリスクが後々顕在化し予想外の手戻りを生んでしまうことがありました。

課題解決に向けた取り組み

Design Docsの作成を開発プロセスに取り入れることで、上記の問題を解決できるのではと仮説を立てました。

Design Docsとは？

Design DocsはGoogleをはじめとする様々なテック企業で使われている設計についてのドキュメント、またはそれを残す文化のことを指します。

この文化が根付くと、開発ライフサイクルにおいて次の効果が期待できます

変更を行う際に、設計上の問題点を早期に特定することは、手戻りが少なくて済む
組織内での設計の合意形成を達成する
横断的な懸念事項を確実に考慮する
上級エンジニアの知識を組織に浸透させる
設計の意思決定に関する組織の記憶の基礎を形作る
ソフトウェア設計者の技術的なポートフォリオの中で、要約の成果物としての役割を果たす

全体を見通した設計をDesign Docsにまとめ、それを基にチーム内で設計の合意を形成することで、会計Plusが抱える課題を解決できるのではと考え、プロセスの改善を試みました。

この考え方はGoogleのソフトウェアエンジニアリングを読んで知りました。この本はGoogle社のソフトウェア開発におけるさまざまなプラクティスが紹介されており、プロダクト開発で何か困ったときに読むと、気づきやアイデアが得られるのでおすすめです。

その他参考文献

具体的に何を書くのか？

会計Plusでは以下の項目をDesign Docsに書くようにしています。

プロジェクトの背景、目的
プロジェクトの参加者
設計の意図
- コードを見ただけでは把握しづらい設計の解説
- なぜその設計にしたのか
- 選ばれなかった代替案の解説
リスクとその対処法
- セキュリティやプライバシー周り
- テスト、モニタープラン(運用時の考慮。障害の発見と復旧手法など)

設計の意図に関しては、トレードオフが発生する部分を重視して書くようにしており、詳細すぎることは書かないようにしています。詳細すぎることというのは、設計の影響する範囲が小さく、意識しないといけない期間が短い(1週間程度)のものを想定しており、それはスプリントのプランニングの時に考え、Pull Requestやコードコメントで設計の意図を残すようにします。

開発中に課題が顕在化すると大きな手戻りになりやすい部分を、できる限り早めに明確にしておくことが手戻りのリスク軽減に繋がります。

ちなみにDesign Docsの項目、フォーマットは組織によって様々です。 Companies Using RFCs or Design Docs and Examples of These(海外のTech企業のDesign Docsのフォーマット集)

いつ書くのか

会計Plusのスクラム開発でもっとも大きなプロダクトバックログアイテムの単位として定義されている「エピック」の開発に着手する前に1~2週間ほど時間をとって作成するようにしています。

Design Docsを書いて、チームでの合意形成を達成後、実際に開発に着手し始めます。開発を進めていくと、最初に合意をとった設計とは違ったアプローチに切り替える意思決定を行う場合がどうしても発生しますが、その場合Design Docsの内容も乖離しないように随時アップデートします。

開発完了後、Design Docsをアーカイブ状態に変更し、開発時のスナップショットとして残しておくようにしています。

どこに書くのか(どのドキュメントツールを使うのか)

会計PlusチームではDesign DocsはGitHub Repositoryでプロダクトコードと一緒に管理するようにしています。 Design Docsを管理するディレクトリを用意し、そこにMarkdownを作成します。

design-docs
├── 2022-08-機能A.md
├── 2022-10-機能B.md
├── archived-2022-04-開発済み機能C.md
└── archived-2022-06-開発済み機能D.md

当初は Google Docsで残す運用にしていたのですが、プロダクトコードとDesign Docsの距離が離れてしまい、ドキュメントと実装の解離が生まれやすくなってしまう課題があったためGitHub Repositoryでの管理に切り替えました。

GitHub Repositoryでプロダクトコードと一緒に管理することで、プロダクトコードと同じフローで修正が行われ、ドキュメントの存在が身近になり形骸化しづらくなりました。 Pull RequestでDesign Docsも一緒に修正・レビューできるのは非常に体験が良いです。

改善の結果

Design Docsは重要な部分に絞った記述になるため、一般的な仕様書と比較すると小さなドキュメントになります。そのためドキュメント作成の障壁が低く、小さく運用を始めて改善を重ねることができました。この点でアジャイルな開発スタイルとの相性の良さを実感しました。

まだいくつかのエピックでしか運用できていませんが、すでに効果を感じています。「いつ、どこで、なにを書くべきか」をチームで合意を取り、開発プロセスに落とし込んだことで、どのエピックでも近しいクオリティで設計の知識がドキュメント化されるようになったため、課題だった属人的な知識は減りました。また、開発の初期段階でDesign Docsを見ながら議論することで、設計の本質的な部分について早く深く考察できるようになったのも、プロセス改善の効果を実感したポイントです。

さいごに

改善がなされた設計プロセスですが、まだまだ課題はあります。会計PlusはLeSS Frameworkと呼ばれる大規模スクラムの開発スタイルをとっており、複数の開発チームで1つのプロダクトを扱っています。そのため、同じコードをかなり大きな組織が触ります。設計のタイミングでは、Design Docsの内容をもとにチーム全体で合意形成を行う必要があるのですが、組織が大きく、意見に対立が生まれると合意形成に時間がかかってしまうことがありました（設計時点で対立が生まれ議論がなされること自体はポジティブなことです）。今後はこの問題を解決できる方法を模索していきます。

会計Plusでは、エンジニアを募集しています。一緒に開発プロセスを改善しながらサービスを育てませんか？

またカジュアル面談もやっていますので、お気軽にお声がけください！