Claude Codeでdesign docをレビューさせる — 観点別サブエージェントで未決事項を洗う

design docは、実装に入る前に穴を見つけるための文書です。Claude Codeには、設計の途中と書き上げた後の両方で使える仕組みが2つあります。書く前は、聞き取り役として論点を引き出させます。書いた後は、観点ごとに分けたサブエージェントに読ませ、未決事項と未検証の前提を挙げさせます。

この記事では、後者のレビュー役を4つ定義し、並列で走らせ、指摘を仕分けるところまでを手順にします。コード実装のレビューではなく、文章としての設計に対する指摘が対象です。

書く前と書いた後で、Claudeの役を変える

書く前の段階では、設計の全体がまだ頭の中にしかありません。ここでレビューさせても、見る対象がありません。必要なのは、決めていないことを洗い出す聞き取りです。

聞き取りには、ベストプラクティスのページにある「インタビューさせる」型がそのまま使えます。例を示します。

オーダー履歴APIの再設計をしたいが、まだ整理できていない。
design doc(docs/design/order-history.md)を書けるところまで、
私に質問してほしい。書き上がったらファイルに保存して。

Claudeは選択式の質問を返し、答えがそろうまで聞き続けます。仕様が書き上がったら新しいセッションを始め、まっさらな文脈から作業に入る進め方もあります。レビューも同じ考え方で、書いた本人の文脈を持たない相手に読ませるほうが穴を見つけやすくなります。

書いた後の段階で役に立つのが、サブエージェントです。

レビューをサブエージェントに任せる理由

サブエージェントは、新しい独立したコンテキストウィンドウで始まります。会話の履歴も、メインのClaudeが読んだファイルも見えません。見えるのは、メインのClaudeが書いた依頼文と、自分のシステムプロンプトなどです。

書いた本人のセッションにレビューを頼むと、設計に至った経緯を知っている分だけ甘くなります。ベストプラクティスのページも、サブエージェントが役立つ場面の1つに「コードの書かれ方を見ていないレビュアーが得られること」を挙げています。

注意点が2つあります。

• CLAUDE.mdは読み込まれます。プロジェクトの規約や制約はサブエージェントにも届くので、チームの設計原則をCLAUDE.mdに書いてあれば、レビューの基準として働きます
• 会話の中だけで決めた内容は届きません。設計の前提をチャットで話しただけなら、design doc自体に書き出す必要があります。レビューで「前提が書かれていない」と指摘されるのは、むしろ狙いどおりの結果です

サブエージェントで得られるのは並列と新しい目で、答えそのものが賢くなるわけではありません。観点の分け方と指示の質が、結果の質を決めます。

4観点のレビュアーを定義する

プロジェクトの .claude/agents/ にMarkdownファイルを置くと、そのプロジェクトのサブエージェントになります。リポジトリに入れておけば、チームで共有して育てられます。必須のfrontmatterは name と description だけです。

観点は、セキュリティ・運用・移行・コストの4つに分けます。1体に全観点を任せると、指摘が浅く広くなりがちです。観点を絞ると、その観点で必要な問いを細かく書けます。

まず、セキュリティ担当の例です。以下は筆者が組み立てた一例で、公式のテンプレートではありません。

---
name: design-review-security
description: design docをセキュリティの観点で読み、未決事項と未検証の前提を挙げる。design docのレビューを頼まれたときに使う。
tools: Read, Grep, Glob
---
 
あなたはdesign docのセキュリティレビュアーです。
渡されたパスの文書を読み、コードは変更しません。
 
見る点:
- 認証・認可の境界がどこにあり、誰が何を呼べるか
- 機密データの保存場所、送信先、ログへの混入
- 外部入力の検証と、信頼境界をまたぐ呼び出し
- 文書が暗黙に置いている前提(「内部からのみ呼ばれる」など)
 
出力は次の4区分だけにする。各区分は最大3件。
該当がなければ「該当なし」と書く。スタイルの指摘はしない。
1. 論点: 文書が答えていないセキュリティ上の問い
2. 未決事項: 決めると書かれているが、期限も担当もない項目
3. 未検証の前提: 文書の主張で、根拠(コード・計測・契約)が示されていないもの
4. 欠落した代替案: 検討されていない選択肢と、検討すべき理由

tools を Read, Grep, Glob に絞り、EditとWriteを持たせていません。レビュアーが文書やコードを書き換える余地をなくすためです。Grep と Glob があるので、「このサービスはすでに認証済み」という文書の記述を、実コードで裏取りさせることもできます。

残る3つは、見る点だけが違います。出力の4区分は共通にしておくと、後で指摘を並べて比べられます。

description は、Claudeがいつ委譲するかを決める文です。短く、他のレビュアーと区別できる文にします。サブエージェントの説明文の合計が大きくなりすぎると、起動時に警告が出ます。上限は15,000トークンです。

4体を並列で走らせる

定義したら、メインのセッションから呼びます。サブエージェントは名前で指定できます。確実に特定のエージェントを動かしたいときは、@ で選ぶ方法もあります。

依頼文の例です。

docs/design/order-history.md を、design-review-security、
design-review-ops、design-review-migration、design-review-cost の
4つのサブエージェントで並列にレビューして。
各レビュアーの報告をそのまま見出し付きで並べ、最後に
重複する指摘と、観点間で食い違う指摘をまとめて。

ここで注意したいのは、サブエージェントに渡る依頼文は、あなたの文面そのものではない点です。メインのClaudeが依頼内容を組み立てて渡します。そのため、出力の区分や件数の上限は、依頼文でなくエージェントのシステムプロンプトに書いておくほうが確実です。先の例で4区分と「最大3件」をファイル側に置いたのはこのためです。

同時に動かせるサブエージェントは、既定で20までです。4体なら余裕があります。ただし、各サブエージェントが自分のリクエストを送るので、トークンは4体ぶん消費されます。大きな設計書を何度も回すと使用量に響くので、観点を増やす前に、本当に別の目が要るかを考えます。

サブエージェントは、メインのClaudeから起動した場合、既定でバックグラウンドで動きます。報告は後の完了通知として届きます。待っている間に、別の作業を進められます。

返ってきた指摘を仕分ける

レビュアーに指摘を求めれば、必ず何かが返ってきます。指摘を探す役は必ず何かを見つけます。すべてを直すと、不要な抽象化や起きないケースのテストが増えます。そこで、指摘をそのまま直さず、扱いを決めてから動きます。

4観点の報告が食い違う場合もあります。たとえば、セキュリティは「すべての呼び出しにトークン検証を入れるべき」と指摘し、運用は「検証サービスが落ちたときの影響が大きい」と指摘する、といった具合です。この食い違いは、設計の本当のトレードオフがある場所を示しています。メインのClaudeに食い違いの一覧を作らせ、人間が判断する材料にします。

修正はメインのセッションが担当します。レビュアーに Edit を持たせていないので、文書を勝手に書き換える心配はありません。

直した後は、再度レビューを回します。前回の指摘がどう解消されたかを、メインのClaudeに要約させ、その要約を添えて新しく生じた穴だけを探すよう頼むと、同じ指摘の繰り返しを避けられます。

条件が違うときの変え方

観点は、4つで固定する必要はありません。社内の事情に合わせて足し引きします。

• データ基盤の設計なら、データ品質と再処理の観点を加えます
• 外部公開APIなら、バージョニングと互換性の観点を加えます
• 小さな設計なら、4体を1体にまとめ、観点を箇条書きで列挙します

レビュアーの数は、設計の大きさに合わせます。小さな変更に4体を回すと、コストが見合いません。

文書の記述を実コードと突き合わせさせたいときは、設計に関係するコードの場所を、サブエージェントのプロンプトに書いておきます。たとえば「認証の実装は src/auth/ にある」と書いておけば、探す範囲を絞れます。

サブエージェントは、別のサブエージェントを呼ぶこともできます。既定では、メインの会話から数えて3層下までです。観点ごとに調査役を呼び分ける構成も取れますが、報告が増えて読む側の負担が増えるため、まずは1層で足りるかを試します。

レビュー後に、決定を記録する

レビューで論点が出そろい、未決事項が片付いたら、決まった内容を記録に残す段階に入ります。技術選定の決定を書き残す手順は、Claudeのarchitectureスキル(ADR)で技術選定の決定記録を書くで説明しています。design docは検討の過程を含む文書で、ADRは決まった内容を短く残す文書、という使い分けです。

サブエージェントの権限をさらに細かく絞りたい場合は、Claude Codeサブエージェント権限ルール設計が参考になります。レビュー専用のエージェントを複数動かす構成が増えたときの、並列実行の考え方はClaude Codeのサブエージェント並列設計にあります。

まとめ

design docのレビューで効果が出るのは、観点を分け、出力の形を固定し、指摘を仕分ける3点がそろったときです。サブエージェントはあくまで読み手を増やす仕組みで、設計の判断は人間に残ります。

最初は、セキュリティ担当1体だけを定義し、直近のdesign docに回してみてください。4区分の出力に有用な指摘が出れば、運用と移行とコストを足していく進め方が現実的です。指摘が浅ければ、観点の書き方を直すほうが先です。