設計書を書くたびに「フォーマットがバラバラになる」「前回と書き方が違う」と感じていませんか？要件定義書、基本設計書、詳細設計書、DB設計書……それぞれ求められる粒度や観点が違うのに、毎回ゼロから指示を書き直すのは正直しんどい作業です。この記事では、Claude Codeで設計書作成専用のサブエージェントを作る方法を、設計フェーズ別の具体例つきで紹介します。
結論：設計フェーズごとに専用サブエージェントを分けると、フォーマットも品質も安定します
結論から言うと、設計書作成は「要件定義」「基本設計」「詳細設計」「DB設計」「図表生成」のようにフェーズごとにサブエージェントを分けて作るのが効果的です。1つのサブエージェントに全部任せようとすると、結局そのつど指示を細かく書き直す羽目になります。設計書のたびに同じ説明を繰り返していませんか？フェーズ別に分けるだけで、その手間はかなり減ります。
なぜフェーズ別に分けるのが効くのか
理由は、設計書のフェーズごとに「読む人」と「書くべき粒度」が違うからです。要件定義書は発注者やPMが読む前提で業務要件を中心に書きますが、詳細設計書はエンジニアが読む前提で処理フローやクラス構造まで踏み込みます。これを1つのサブエージェントに混在させると、どうしても粒度がブレてしまいます。私は最初、1つの汎用サブエージェントにまとめて任せていましたが、フェーズごとに分けたほうが出力の精度も読みやすさもはっきり安定すると感じました。
エンジニアなら読むべき本を30冊以上紹介しています。
正直、私の仕事のやり方をガラッと変えた神本やSQLのチューニングに悩んだ時にめちゃくちゃ役に立ったもあります👇
→記事を読む
設計書作成に使えるサブエージェント一覧
まずは全体像を表にまとめました。設計フェーズに沿って5つ用意するのがおすすめです。
| フェーズ | サブエージェント名 | 主な読者 | 出力する内容の例 |
|---|---|---|---|
| 要件定義 | requirements-writer | 発注者・PM | 業務要件、機能要件、非機能要件 |
| 基本設計 | basic-designer | PM・リードエンジニア | システム構成、機能一覧、画面遷移概要 |
| 詳細設計 | detailed-designer | 実装担当エンジニア | 処理フロー、クラス設計、入出力仕様 |
| DB設計 | db-designer | 実装担当エンジニア | ER図、テーブル定義書 |
| 図表生成 | diagram-writer | 全員 | シーケンス図、フローチャート（Mermaid） |
サブエージェントは.claude/agents/（プロジェクト単位）または~/.claude/agents/（ユーザー単位）にMarkdownファイルとして置きます。/agentsコマンドで対話的に作ることもできますが、設計書系は型が決まっているので手書きのほうが早い場合も多いです。
1. requirements-writer：要件定義書作成サブエージェント
要件定義は「誰のどんな業務課題を解決するか」が抜けがちです。テンプレートを固定して、抜け漏れを防ぎましょう。
---
name: requirements-writer
description: 新機能やシステムの要件定義書を作成する。背景・業務課題・機能要件・非機能要件を含む。
tools: Read, Write, Edit
model: sonnet
---
あなたは要件定義書の作成担当です。次の構成で出力してください。
1. 背景・目的
2. 対象ユーザーと業務課題
3. 機能要件（一覧表形式）
4. 非機能要件（性能・セキュリティ・可用性）
5. スコープ外の事項
不明点があれば仮置きせず「【要確認】」として明記してください。
❌ 「要件定義書を書いて」とだけ依頼する
✅ 構成をサブエージェント側に固定しておき、毎回同じ粒度で出力させる
2. basic-designer：基本設計書作成サブエージェント
基本設計は、実装の詳細に踏み込みすぎず「全体像」を伝えるのが役割です。
---
name: basic-designer
description: 要件定義をもとに基本設計書を作成する。システム構成図、機能一覧、画面遷移の概要を含む。
tools: Read, Write, Edit
model: sonnet
---
要件定義書の内容を踏まえ、基本設計書を作成してください。システム構成（利用するミドルウェア・外部連携含む）、機能一覧表、画面遷移の概要を中心に記述し、実装レベルの詳細（クラス名や関数名）には踏み込まないでください。
3. detailed-designer：詳細設計書作成サブエージェント
ここからはエンジニアが読む前提の粒度になります。既存コードを参照しながら作成できるのがClaude Codeの強みです。
---
name: detailed-designer
description: 基本設計をもとに詳細設計書を作成する。処理フロー、クラス設計、入出力仕様を含む。
tools: Read, Write, Edit, Grep, Glob
model: sonnet
---
基本設計書と既存コードを確認し、詳細設計書を作成してください。各機能について、処理フロー（ステップ単位）、関連するクラス・メソッド、入出力パラメータの型と制約を記述してください。既存コードと矛盾する内容は書かないでください。
◎ 既存コードを参照させる設計書は、ReadやGrepなどの読み取り権限だけ与えておくと安全です。
4. db-designer：DB設計書作成サブエージェント
ER図とテーブル定義は、既存のマイグレーションファイルやスキーマから逆算してもらうのが効率的です。
---
name: db-designer
description: マイグレーションファイルやスキーマ定義からDB設計書を作成する。ER図とテーブル定義書を含む。
tools: Read, Write, Grep, Glob
model: sonnet
---
マイグレーションファイルまたはスキーマ定義を読み込み、テーブル定義書（カラム名・型・制約・備考）とER図（Mermaid記法）を出力してください。命名規則に一貫性がない箇所は指摘してください。
5. diagram-writer：図表生成専用サブエージェント
設計書の中でも、文章だけでは伝わりにくいシーケンス図やフローチャートは専用サブエージェントに任せると効率的です。
---
name: diagram-writer
description: 処理フローやAPI連携をMermaid記法のシーケンス図・フローチャートとして出力する。
tools: Read, Write
model: haiku
---
指定された処理内容をMermaid記法で図にしてください。シーケンス図が適切な場合はsequenceDiagram、処理分岐が中心の場合はflowchartを使い分けてください。図のコードのみを出力し、説明文は最小限にしてください。
さらに深掘り：設計書サブエージェントを運用するときのコツ
5つに分けただけでは、実際の現場で「使いやすい」状態にはなりません。私が運用してみて気づいたコツをまとめます。
| つまずきポイント | 原因 | 対策 |
|---|---|---|
| フェーズ間で内容が矛盾する | 各サブエージェントが前段の設計書を見ずに作っている | 前フェーズのファイルパスをプロンプトで明示的に渡す |
| 用語の表記がフェーズごとに違う | 用語集が共有されていない | プロジェクトのCLAUDE.mdに用語集を書き、全サブエージェントに参照させる |
| 詳細設計が実装と食い違う | コードを読まずに想像で書いている | detailed-designerにはGrep/Globなど読み取り権限を必ず付与する |
| 図が複雑になりすぎる | 1つの図に全処理を入れようとしている | 「機能単位で図を分けて」と依頼時に指示する |
私自身、最初は要件定義書と基本設計書で同じ用語が違う言い回しになってしまい、レビューのたびに指摘される、ということがありました。今はCLAUDE.mdに用語集（例：「ユーザー」と「会員」は同義で「ユーザー」を使う、など）を書いておき、すべてのサブエージェントがそれを参照する形にしています。この一手間だけで、フェーズ間の表記ズレがほとんどなくなったと感じています。
設計書も最終的には人がレビューする前提で
サブエージェントが出力した設計書も、そのまま提出するのではなく、必ず人の目でレビューしてください。特に【要確認】タグが付いた箇所は、仮置きせずに必ず関係者へ確認を取ることをおすすめします。
まとめ
- ✅ 設計書作成は「要件定義・基本設計・詳細設計・DB設計・図表生成」のフェーズ別にサブエージェントを分けると安定する
- ✅ 詳細設計やDB設計は、既存コードやマイグレーションを読ませて矛盾のない内容にする
- ◎ 用語集をCLAUDE.mdにまとめ、全サブエージェントで共有する
- ✅ 図表生成は軽量モデルに任せてコストを抑える
- ◎ 出力された設計書は必ず人がレビューし、不明点は仮置きせず確認する
エンジニアなら読むべき本を30冊以上紹介しています。
正直、私の仕事のやり方をガラッと変えた神本やSQLのチューニングに悩んだ時にめちゃくちゃ役に立ったもあります👇
→記事を読む