Design Docを導入し開発効率を向上させた話

はじめに

こんにちは。ウォンテッドリーでiOSエンジニアをしている湊です。

2026/01/20に開催されたMobile勉強会にて、Design Docで開発効率を向上させるというテーマで登壇しました。本記事では、実務の中で直面していた開発効率の課題と、それを解決するために導入したDesign Docの運用、そして導入によって得られた知見について紹介します。

本記事が、私と同じように実装後の手戻りが多い、レビューのリードタイムが長くなってしまうといった悩みを抱えるエンジニアの方々にとって、解決の一助となれば幸いです。

直面していた2つの大きな課題

実務に入り、複雑なタスクに取り組む中で、私は主に2つの課題に直面していました。

1. マージまでのリードタイムの長期化

実装を終えてプルリクエスト（Pull Request、以下PR）を出した後、レビューの段階で仕様の考慮漏れや、エッジケースでの挙動不明点が発覚するケースが頻発していました。その結果、関係者への再確認やコードの修正、再レビューというサイクルが繰り返され、1つのタスクを完了するまでに想定以上の時間を要していました。

2. 原因特定が不十分なままの実装開始

バグ修正や機能変更の際、詳細な調査をスキップしておそらくここを直せば動くだろうという推測に基づき実装を始めてしまうことがありました。しかし、PRの段階で根本的な原因は別にあるのではないかといった指摘を受け、設計レベルでの大きな手戻りが発生する事態を招いていました。

Design Doc：実装前に勝負を決める

これらの課題を上長に相談した際、解決策として提案されたのがDesign Docの導入です。

Design Docとは、機能実装やシステム変更の前に、その目的や設計方針、懸念事項などをドキュメントとして言語化し、関係者間で合意形成を行うための手法です。プロダクト開発においては「なぜ、何を、どうやって作るか」を事前に整理・共有するための羅針盤のような役割を果たします。

私はまず、生成AIを活用してDesign Docの定義や一般的な項目を整理することから始め、自身の開発フローに組み込むことにしました。

具体的な運用方法と4つのステップ

私は現在、GitHub IssueをベースにDesign Docを運用しています。具体的には、実装用のIssueを作成した直後、以下の4つの項目をコメント欄に書き起こし、上長にレビューを依頼するようにしています。

• STEP 01：背景と目的 
• • その変更がなぜ必要なのか、ユーザーにどのような価値を届けるのかを記載します。ここを明確にすることで、実装の妥当性を再確認できます。
• STEP 02：仕様の不明点 
• • 実装を進める上で疑問に思っていることや、現在の仕様定義だけでは判断できないエッジケースをすべて洗い出します。
• STEP 03：設計方針
• •  具体的な実装アプローチを記載します。使用するクラスやデータ構造、既存コードへの影響範囲を言語化します。
• STEP 04：完了条件
• •  何をもってこのタスクが完了したと見なすかを定義します。テスト項目や期待動作を明文化し、ゴールを明確にします。

私は以下のテンプレートを用いてdesign docの作成を行っています。

# docs

## 背景,目的

### 機能説明

### 機能スコープ
- 対応すること
- 対応しないこと

### 仕様
- デザイン仕様
- backendインターフェース設計仕様
- 設計上の決定事項

## 仕様の不明点

## 設計方針（クラス図や影響範囲）

- 変更対象ファイル
- 変更内容

## 完了条件

言語化による不確実性のセルフチェック

これらの項目を埋める際、私が最も大切にしているのは自分の言葉で書き起こすことです。

AIに下書きを手伝ってもらうことはありますが、最終的には必ず自分の言葉で再構築します。なぜなら、頭の中では理解しているつもりでも、いざ文字にしようとすると言葉に詰まってしまう箇所があるからです。その言葉に詰まる瞬間こそが、自分の理解が曖昧なポイントや、設計の穴が潜んでいる場所です。

実装に入る前にこの不確実性に自ら気づき、調査し直すことができる。これこそが、Design Docが手戻りを防ぐ最大の防波堤になっていると感じています。

導入後の変化と得られた知見

Design Docを運用し始めてから、開発プロセスには明確な変化が現れました。

1. レビュー負荷の軽減とリードタイム短縮

最も大きな効果は、PRのマージまでのスピード向上です。実装前にどう書くかの合意が取れているため、コードレビューではロジックの妥当性確認に集中できるようになりました。上長からは事前に設計意図が共有されているため、レビューの負荷が大幅に下がったというフィードバックを得ています。

2. 上長視点でのシミュレーション

自分の言葉で整理する習慣がついたことで、ドキュメントを書き終えた段階で「ここはきっとレビューでこう聞かれるだろう」と、上長の視点をシミュレーションできるようになりました。以前は指摘されるまで気づけなかったことが、書くプロセスを通じて事前に自問自答できるようになったことは、エンジニアとしての視座を高める一歩になったと感じています。

3. トレードオフとしての作成コスト

一方で、Design Docを書くこと自体に一定の時間がかかるというトレードオフも存在します。スピードが求められる微細な修正において、すべてのステップを踏むことが過剰な負荷になる可能性もあります。しかし、現在の私にとっては、このプロセスこそが結果的に最も早く品質の高い成果物を届ける近道でありました。

おわりに

Design Docは単なる設計書ではありません。それは、実装という答えを出す前に、問題の定義が正しいかを検証するための思考のプロトタイプです。

実装してみないとわからないという不安を抱えたままコードを書くのではなく、一度立ち止まって言語化する。この小さな習慣の積み重ねが、エンジニアとしての信頼を築く基盤になると感じています。開発効率や手戻りに悩んでいる方がいれば、まずは小さなIssueからDesign Docを始めてみることをお勧めします。

参考リンク

• 登壇資料