この記事はHTアドベントカレンダー13日目の記事です。
はじめまして。博報堂テクノロジーズ CREATIVE BLOOM 開発部の今藤です。
開発業務の中で、要件定義書から詳細設計を書き起こす作業は属人化や時間のばらつきが課題でした。そこで生成 AI（Claude Code）を導入し、カスタムスラッシュコマンドを作成することで、作業時間の短縮と粒度の標準化を目指しました。本記事ではそのプロセスに関してまとめます。
はじめに
体制
- チーム規模: エンジニア 3名 / 企画 2名
- 管理ツール:
- ドキュメント（要件定義書 / 詳細設計）は Notion
- コードは GitHub（フロントエンド / バックエンド / インフラ 等別々のリポジトリで管理）
現状の開発ステップ
- 企画が要件を要件定義書にまとめる
- 開発が要件定義書を基に詳細設計を書き起こす（今回、特に改善したいステップ）
- 詳細設計をもとにチームで工数を見積もってから開発を行う
現状課題
- 詳細設計の作成にかかる時間が、要件や担当者によってばらつきがある
- スプリント計画時の見積もりにも、詳細設計にかかる時間の不確実性が影響することがある
- 設計の粒度や書きぶりに差があり、今後メンバーが入れ替わった際にも不安がある
詳細設計の定義
ここで本記事における「詳細設計」は以下を対象とします。
- 機能要件をタスク粒度に分解
- DB 設計
- インフラ設計
- API 仕様
- 処理フロー
- 実装時の懸念点の洗い出し
チームにおける「詳細設計」の目的
「開発業務を遂行するためのドキュメント」として位置付けています。主な目的は以下の2点です。
- 開発工数の見積もり精度を高めるための、タスク分解と必要作業の明確化
- チーム内での実装方針のすり合わせ
取り組み
Claude Code のカスタムスラッシュコマンドを使用して、コマンド一つで詳細設計が作成できるように試しました。
Notion の要件定義を読み込むための Notion MCP の導入
詳細設計を書き起こす際のもととなる要件定義書や既存の詳細設計を読み込みたかったので Claude Code から Notion MCP を使えるようにしました。
Claude Code のカスタムスラッシュコマンドによる詳細設計の作成
詳細設計を書き起こすにあたって意識していることを1からまとめてプロンプトにするのは難しかったので既存の詳細設計から詳細設計を書く際の構成、粒度、書き方をカスタムスラッシュコマンドへ抽出・言語化してもらいました。
また、詳細設計を書き起こすにあたって既存の実装を参照する事が重要だとも考え、各リポジトリで実装パターンやルール等をカスタムスラッシュコマンドに追記してもらうようにしました。
最後にコマンドを実行すると Notion リンクを受け取って詳細設計を作成するようなコマンドにするような指示をすることで暫定的にカスタムスラッシュコマンドが完成です。
カスタムスラッシュコマンドの改善サイクル
設計書に起こしていない実際の要件定義書を使って実際に使いながら改善を加えました。
カスタムスラッシュコマンドのテキスト量も膨大だったため、コマンドの修正自体も Claude Code に依頼しながら進めました。事例を2つ挙げます。
粒度が細かすぎて実装例が多すぎる
各リポジトリの実装パターンを入れた影響かサンプルコードが散見されました。これまでに使っていないようなライブラリを使う場合などはありがたいのですが、そうでない場合は見積もりをしたいのにレビューのようになってしまい、設計書としては好ましくない印象です。この点について詳細設計を作成する意図とあわせて明示的に指摘することで、カスタムスラッシュコマンドに下記の文言が追加されて改善されました。
**重要：詳細設計は「実装コードを書くこと」ではなく、「工数見積もり」と「タスクの進め方のすり合わせ」が目的です。**
- ✅ 記述すべきこと：**何を実装するか**、**どのファイルを変更するか**、**各タスクの工数**、**実装の順序と依存関係**、**相談事項**
- ❌ 避けるべきこと：実装コードの詳細、コードスニペットの大量記述、実装手順の詳細な解説
要件定義書に書かれていないこともまとめる
要件定義書に書かれていないことや曖昧なことに関して Claude Code が推測した上で設計を進めるケースが散見されました。これに関しては Claude Code による推測が間違っていた場合に全然違う方向に設計が進んでしまい、後から修正が必要になります。この対策として仕様を読み込んだ際に不明点があれば質問をするように指摘しました。それによって詳細設計作成前にインタラクティブなやり取りを行うようになり、見当違いな設計はほとんど見られなくなりました。
まとめ・課題・今後の展望
最終的には詳細設計を作成する際の叩きとしてはある程度使用できるコマンドになったと思います。
特にDBの設計や実装方針の大枠を自動で作成してもらえるのは、詳細設計のハードルが大きく下がりました。設計書を書く前の検討段階で色々と調査検討する時間は短縮されるので、詳細設計にかかる時間の不確実性が軽減できると感じました。
一方、コマンド一つで行う課題として、以下の点が挙げられます。
- タスク粒度で分割してほしいが、機能単位での分割になってしまうので人手による分割が必要
- すべてのリポジトリの情報を入れてはいるものの、実行しているリポジトリによってその対象の設計だけ詳しくなってしまう
- すべてのリポジトリの情報を入れていることで情報の更新も困難な上、カスタムスラッシュコマンド自体が長い
タスクの分割粒度に関しては、大きすぎず小さすぎずを意識しつつ、タスクごとの依存関係も踏まえて適切な粒度で分けたいところです。一方で感覚的な部分が大きく、言語化が難しいため、この部分については人手を挟まざるを得ないのかなとも考えています。詳細設計の中でも個人的にはこの分割にそこまで工数が取られるとは感じていないので大きな問題にはならなさそうだと感じています。
コマンドの中にすべてのリポジトリの情報を入れていることに関しては対応策としてモノリポ（monorepo）を作成してその中で今回作成したカスタムスラッシュコマンドを実行したり、必要に応じてリポジトリを参照しに行けるような仕組みを作ってみることを検討しています。
補足
コマンドを実行するとこのような形で始まります。
