Design Docのススメ —— 「スムーズなプロジェクト進行」を支える共通言語 – SmartHR Tech Blog

こんにちは！SmartHR スキル管理チームでプロダクトエンジニアをしている @oku_yu です。

私たちは日々、ユーザーの課題解決につながるフィーチャー開発に取り組んでいます。しかし、特に不確実性の高いプロジェクトにおいて、何度も同じ壁にぶつかっていました。
本記事では、プロジェクトのスムーズな進行を阻む壁を乗り越えるべく、開発サイクルの中にDesign Docを取り入れたので、そこで得られた学びを紹介します。

プロジェクトのスムーズな進行を阻んだ壁

Design Doc導入前、私たちのチームには次のような課題があり、「プロジェクトがスムーズに進まない」状況を生み出していました。

プロジェクト中盤での「設計の巻き戻し」

開発がある程度進行し、実装の深い部分に入ってから「あれ？この仕様、どうするんだっけ？」という疑問が噴出し、根幹の設計に立ち戻ることがしばしば発生していました。これが工数のロスとなり、プロジェクトの進捗が思わしくないと感じる場面がありました。

チケット単位で発生する仕様の議論

「どう作るか」という実装フェーズになると、個別のチケット（タスク）ごとに「このAPIの設計はどうする？」「このデータの持ち方は？」といった議論がしばしば発生していました。この議論が、チケットの修正・分割、手戻りへと繋がっていました。

チーム全体の共通認識の欠如

技術的なトレードオフや設計上の重要な決定事項がドキュメントとしてまとまっていませんでした。そのため、チームメンバー間で共通認識を持てず、この認識のズレが手戻りの根本原因となっていました。

Design Docとは

チームが抱えていた課題を改善するために導入したものがDesign Docです。
Design Docとは、開発前に作成する機能を「どう作るのか？」をまとめたドキュメントで、プロジェクトの背景や目的、設計、検討した代案が記録されています。

私たちのチームでは、「なぜ、この設計で、このゴールを達成するのか？」という問いに全員が納得感をもって答えられる状態を作るため、Design Docを開発の最初のステップと位置付けています。

スキル管理チーム流Design Docの運用ルール

運用がうまく回るよう、いくつかのルールを決めています。

どんなときに書くか

私たちのチームでは、全ての機能開発でDesign Docを書くわけではありません。明確な基準を設けてはいませんが、以下のような要素を含んだ開発でDesign Docを作成しています。

• 開発する機能の不確実性が高いとき
• 開発期間に数スプリントを要するとき
• 既存のアーキテクチャに大きな変更を加える必要があるとき

何を書くか

ドキュメント作成の心理的障壁を下げるため、テンプレートを整備しています。しかし、テンプレート通りに書く必要はなく、不要な項目の削除や項目の追加は自由としています。

Design Docの目的は「どう作るか？」を合意することなので、「PRD（プロダクト要求仕様書）の要件を技術的にどう実現するか」「代替案も明記する」の2点を特に重視しています。

レビュー体制と進め方

私たちは、Design Docの最も重要な役割は「議論の起点」となることだと考えています。
レビュアーは開発者、および関連する機能に影響を受けるメンバーを複数名アサインしています。
レビューを通してドキュメント上に議論の記録を残し、明示的に「承認」を得ることで、「この設計で進める」というチームの共通認識を確定させ、開発中に迷ったらDesign Docへ戻るというルールを徹底しています。

開発後の管理

プロジェクトが完了したDesign Docについては、原則としてその後のメンテナンスは行っていません。ただし、アーカイブはせず、参照資料として残しています。メンテナンスを実施しないことをチームの共通認識として持つことで、別のメンバーがプロジェクト完了後のDesign Docを参照した際、これが必ずしも最新のドキュメントではないことを認識できるようにしています。

導入後に感じた効果

Design Docの導入から数ヶ月が経過し、チームとして以下のような変化を感じています。

仕様の共通資料ができ、認識のズレが減少した

誰もが参照できる共通資料ができたことで、「あれ、この仕様どうだっけ？」という会話が激減しました。資料が一箇所にまとまっているため、疑問が生じたらDesign Docを確認するという習慣が定着しました。

設計上の問題点を早期に特定できるようになり、手戻りがなくなった

以前はコードを書き始めてから見つかっていた設計上の問題点が、Design Docのレビュー段階で特定できるようになりました。これにより、早い段階で修正が完了し、手戻りによるロスを大幅に削減することができました。

タスクの分割精度や見積もり精度が上がった

Design Docで設計全体が確定してから具体的な実装チケットを作成するため、タスクが適切な粒度で分割されるようになりました。その結果、タスクの漏れが減り、開発着手前の見積もり精度が向上しました。

AIエージェントの精度が向上した

私たちのチームでは、コード生成などの作業にAIエージェントを活用しています。Design Docにどう作るかを記述していることで、AIエージェントにタスクを依頼したときの曖昧さがなくなり、エージェントから出力される成果物の精度が向上しました。

まとめ

Design Docを導入することで、「どう作るか」を全員が納得し、着実に進められる開発へと変わりました。今やDesign Docは、私たちのチームにおける「スムーズなプロジェクト進行」を支える共通言語となっています。

これらのアプローチが、皆さんの開発にも役立てば幸いです。

We Are Hiring!

SmartHR では、一緒にプロダクトを作りあげていく仲間を募集中です！

アジャイルな開発スタイルで継続的に開発プロセスを改善することに興味がある方をお待ちしています！

少しでも興味を持っていただけたら、カジュアル面談でざっくばらんにお話ししましょう！
hello-world.smarthr.co.jp