「設計書を作って」とClaude Codeに頼んでみたものの、要件定義レベルの内容しか出てこなかった、あるいは画面仕様と処理ロジックが混ざった文書になってしまった、という経験をした人は少なくないのではないでしょうか。
設計書作りが噛み合わない原因の多くは、工程の指定が曖昧なことにあります。要件定義書は「何を作るか」を固める上流工程の文書であり、要件定義書の作り方で扱いました。これに対して本記事が扱う基本設計書・詳細設計書・DB設計書・API設計書は、要件を「どう実装するか」に落とし込む下流工程の文書です。プロンプトで工程名を明示するだけでも、Claude Codeの出力精度は大きく変わります。
本記事では、下流工程の設計書に絞って、種類別のプロンプト例、既存コードから設計書を逆生成する手順、出力形式の使い分け、レビュー時の注意点を整理します。
なお、本記事はclaudecode道場（malna株式会社が独自に提供する学習サービス）のブログ記事であり、Anthropic公式の製品・見解ではありません。
目次
- 基本設計書・詳細設計書はどこが違うのか
- 基本設計書をClaude Codeで作る
- 詳細設計書をClaude Codeで作る
- 既存コードから設計書を逆生成する
- 出力形式の使い分け（Markdown／Mermaid・PlantUML／Excel）
- レビュー時に必ず確認すること
- よくある質問（FAQ）
- まとめ
1. 基本設計書・詳細設計書はどこが違うのか
設計書という言葉は現場によって指す範囲が異なりますが、一般に次の順で粒度が細かくなっていきます。
- 基本設計書（外部設計書）：システム構成、機能一覧、画面遷移、他システムとの連携方針など、利用者やチーム全体が見る「システムの全体像」を定義する
- 詳細設計書（内部設計書）：クラス構成、メソッド単位の処理ロジック、データの流れなど、実装担当者がコードに落とし込むための「内部構造」を定義する
- DB設計書：テーブル定義・ER図・インデックス設計など、データの持ち方を定義する
- API設計書：エンドポイント仕様・リクエスト/レスポンス形式・認証方式など、システム間・画面-サーバー間のインターフェースを定義する
Claude Codeに依頼するときは、この4分類のどれを作るかを最初に宣言すると、余計な情報が混ざりにくくなります。「基本設計書として」「詳細設計書のレベルで」と一言添えるだけで、粒度のミスマッチはかなり防げます。
2. 基本設計書をClaude Codeで作る
基本設計書では、システム全体の構成と技術選定の理由を記録することが重要です。
以下の要件定義書をもとに、基本設計書のたたき台を作成してください。
【要件定義書（抜粋）】
（要件定義書の該当部分を貼付）
【出力してほしい構成】
1. システム構成図（Mermaid形式）
2. 機能一覧（大機能・中機能の階層構造）
3. 使用技術とその選定理由（代替案と比較した上での理由も含める）
4. 他システムとの連携方式（同期/非同期、プロトコル）
5. 想定される技術的リスクと対応方針
技術選定の理由は「なんとなく」ではなく、性能・保守性・チームの技術習熟度のいずれを重視したかを明記してください。
技術選定の理由を明文化させておくと、後から「なぜこの構成にしたのか」を担当者に聞かずに済むようになります。数年後にメンバーが入れ替わった際の引き継ぎ資料としても機能します。
3. 詳細設計書をClaude Codeで作る
詳細設計書では、基本設計で決めた機能を「どのクラス・メソッドで実現するか」まで落とし込みます。
以下の機能仕様から、詳細設計書を作成してください。
【機能仕様】
発注確定処理：発注データを検証し、在庫を引き当て、発注先へ通知を送る。
権限（担当者/係長/部長）によって承認要否の分岐がある。
【出力してほしい構成】
1. クラス構成（責務ごとにクラスを分割し、依存関係を明記）
2. 主要メソッドのシグネチャと処理概要
3. 処理フロー（Mermaidのシーケンス図で、正常系・異常系を分けて表現）
4. 例外処理方針（どの層でどの例外を捕捉し、どう扱うか）
5. 排他制御・トランザクション境界の考え方
Mermaidのシーケンス図は、呼び出し元（コントローラ）から永続化層まで一連の流れが追えるようにしてください。
詳細設計書は実装担当者が読む前提の文書なので、「正常系だけ」ではなく異常系・排他制御まで含めて依頼すると、実装後の手戻りを減らせます。
4. 既存コードから設計書を逆生成する
新規開発の場面だけでなく、設計書が残っていない既存システムを保守・改修する場面でも、Claude Codeは活用できます。事実（出典あり）：Claude Codeはコードベース全体を読み取り、複数ファイルを横断して理解できるツールとして公式に説明されており（Claude Code Docs「Overview」）、大規模なコードベースの探索に最適化された読み取り専用の組み込みサブエージェント（Explore）も用意されています（Claude Code Docs「Create custom subagents」）。
これを踏まえると、既存コードから設計書を逆生成する依頼は次のような形になります。
このリポジトリの src/order/ 配下のコードを読み込み、
現状の実装内容から詳細設計書を「as-is」として作成してください。
【確認してほしい観点】
1. クラス構成と各クラスの責務
2. 主要な処理フロー（Mermaidのシーケンス図）
3. 想定と異なる実装・改善余地があると思われる箇所（懸念点として別枠で記載）
4. コード上のコメント・命名から読み取れる設計意図（推測の場合はその旨を明記）
コードに存在しない情報を断定せず、読み取れなかった部分は「要確認」として残してください。
逆生成のポイントは、最後の一文にあります。設計書が残っていないコードは、当時の意図が失われていることが珍しくありません。Claude Codeにコードから断定的に意図を作文させず、「読み取れた事実」と「推測」を分けて出力させることで、誤った設計書が独り歩きするリスクを抑えられます。
5. 出力形式の使い分け（Markdown／Mermaid・PlantUML／Excel）
設計書の出力形式は、渡す相手と用途で使い分けるのが実務的です。
- Markdown：GitHub・GitLab・Notionなど、社内のドキュメント管理基盤にそのまま格納できる形式です。差分管理（Gitでのレビュー・変更履歴の追跡）と相性が良く、詳細設計書のような頻繁に更新される文書に向いています
- Mermaid・PlantUML：ER図・シーケンス図・クラス図を「テキストで書く」ための記法です。Claude Codeはこれらの記法に沿ったテキストをコードとして出力できます。事実（出典あり）：GitHubはMarkdown内のMermaid記法を公式にサポートしており、コードブロックとして貼るだけで図として表示されます（GitHub Blog）。PlantUMLはGitHub標準では表示されませんが、対応プラグインやNotion埋め込み、専用レンダラーで図に変換できます
- Excel：既存の設計書テンプレートがExcel運用の現場では、テーブル定義書などをExcelに貼り付けやすい形式（タブ区切り）で出力させる方法が手軽です。加えてClaude Codeには「Skills」という拡張の仕組みがあり、スプレッドシート生成に特化したSkillを有効にした環境では、罫線やセル書式まで含めた.xlsxファイルを直接生成させることも可能です（Skillsの利用可否は導入環境の設定に依存します）
どの形式で出力するかは、依頼の冒頭で明示するのが確実です。「Mermaid形式で」「Excelに貼り付けられるタブ区切りで」のように一言添えるだけで、後工程の変換作業を減らせます。
6. レビュー時に必ず確認すること
Claude Codeが生成した設計書は、そのまま提出・実装に使う前に必ず人の目で検証する必要があります。
- 存在しない機能や仕様を書いていないか：AIは文脈から尤もらしい仕様を補完することがあります。要件定義書・既存コードと突き合わせ、根拠のない記述がないか確認します
- 非機能要件（性能・セキュリティ）が抜けていないか：機能面の設計は充実しやすい一方、性能要件やセキュリティ要件は指示しないと省略されがちです
- 命名規則・粒度がプロジェクトの既存資産と揃っているか：既存の設計書テンプレートやコーディング規約をCLAUDE.mdなどの形でプロジェクトに渡しておくと、初回から揃った出力になりやすくなります
- 図とテキストの記述内容が矛盾していないか：シーケンス図の呼び出し順序と、本文の処理説明が食い違っていないかは、AI生成物特有の見落としポイントです
これらの検証を省略すると、体裁だけ整った設計書が承認されてしまうリスクがあります。設計書のレビュー工程そのものは、AIを導入しても人が担う前提で運用するのが安全です。
7. よくある質問（FAQ）
Q: 基本設計書と詳細設計書を1回のプロンプトでまとめて作ってもらえますか？
A: 技術的には可能ですが、粒度の異なる情報が混ざりやすく、後から使う場面（顧客レビュー用か、実装担当者向けか）が異なるため、工程ごとに分けて依頼する方が実務では扱いやすくなります。
Q: Claude CodeでUML図（クラス図・シーケンス図）は作れますか？
A: Claude CodeはMermaidやPlantUMLの記法に沿ったテキストを生成できます。ただし画像そのものを描画する機能ではなく、生成したテキストをGitHubやNotion、対応レンダラーに読み込ませて図として表示する形になります。
Q: 既存システムの設計書が残っていない場合、どこから手をつければよいですか？
A: いきなり全体を対象にせず、改修予定のモジュール単位でコードを読み込ませ、「as-is」の詳細設計書を逆生成するところから始めると負担が小さくなります。読み取れなかった設計意図は「要確認」として残してもらい、有識者へのヒアリングで埋める進め方が現実的です。
Q: 設計書をExcelで納品する必要がある場合、どう対応すればよいですか？
A: タブ区切りテキストで出力させてExcelに貼り付ける方法と、Skillsを使って.xlsxファイルを直接生成させる方法の両方があります。既存の設計書テンプレート（罫線・書式が決まっているもの)がある場合は、そのテンプレートの構成をあらかじめ伝えておくと近い体裁で出力されやすくなります。
Q: AIが作った設計書をそのまま顧客に提出してもよいですか？
A: 推奨しません。要件定義書・既存コードとの整合性確認、非機能要件の抜け漏れ確認、命名規則の統一確認は、提出前に必ず人が行う工程として残すべきです。
8. まとめ
設計書作成でClaude Codeを活かすポイントは、次の4点に整理できます。
- 基本設計書・詳細設計書・DB設計書・API設計書のどの工程を依頼しているかを、プロンプトの冒頭で明示する
- 詳細設計書では処理フローだけでなく異常系・排他制御まで依頼し、実装後の手戻りを減らす
- 設計書が残っていない既存システムには、コードから「as-is」を逆生成する使い方が有効。事実と推測を分けて出力させることが重要
- 出力形式（Markdown・Mermaid・PlantUML・Excel)は依頼時に指定し、生成後は必ず人がレビューする
要件定義書の作り方は要件定義書の作り方、資料作成全般の進め方はClaude Codeで資料作成を10倍速にする方法で解説しています。あわせて参照してください。
