記事

Claude Codeで大規模開発の設計相談をするときの進め方

Claude Codeを設計の壁打ち相手として使うときの進め方を、要件整理・制約の言語化・複数案の比較・リスク洗い出し・ADR記録・人間レビューの順で整理します。設計判断は人間が持つ前提で、公式のExplore→Plan→Implementとインタビュー機能に沿った実務手順です。

Claude Codeはコードを書くだけでなく、設計の壁打ち相手としても使えます。ただし「いい設計を考えて」と丸投げすると、もっともらしいが前提のずれた構成が返ってきます。本記事は、大規模開発の設計相談をClaude Codeとどう進めるか、要件整理から人間の意思決定までの手順です。

結論：設計はAIに決めさせず「案出し」と「叩き」に使う

Anthropic公式のBest Practicesは、実装に飛びつく前に「Explore（調査）→ Plan（計画）→ Implement（実装）」を分離することを推奨しています（Best practices for Claude Code）。設計相談はこのうちExploreとPlanを厚くするフェーズです。

要点は5つです。

要件整理：曖昧な要望を、AIにインタビューさせて言語化する
制約の明示：技術制約・運用制約・チーム制約を先に渡す
複数案：1案ではなく2〜3案をトレードオフ付きで出させる
リスク：各案の失敗モードと検証方法を書かせる
記録と決定：採否は人間が決め、理由をADRとして残す

最終的な設計判断はAIではなく人間が持ちます。AIは選択肢と論点を広げる役で、決定者ではありません。

ステップ1：要件をAIにインタビューさせて言語化する

設計が失敗する最大の原因は、要件が曖昧なまま実装に進むことです。最初から計画を求めず、まずClaude Codeに質問させます。公式Best Practicesも、大きめの機能ではAskUserQuestionツールで先にインタビューさせ、合意した内容をSPEC.mdに書き出し、別セッションで実装に入る進め方を勧めています。

読み取り専用で安全に進めるため、plan modeで起動します。

claude --permission-mode plan

最初の依頼文の例です。

新しい通知基盤を作りたい。AskUserQuestionツールで詳しくインタビューして。
技術実装・UX・エッジケース・運用・トレードオフについて、
私が見落としていそうな難所を掘り下げて質問して。
当たり前のことは聞かなくていい。合意できたらSPEC.mdに仕様をまとめて。

ここで重要なのは、AIに答えさせるのではなく、AIに「問い」を出させることです。自分が即答できない質問が出てきたら、それが設計の本当の論点です。

ステップ2：制約を先に渡す

制約を渡さない設計相談は、教科書的な理想論しか返ってきません。次の3カテゴリを依頼文かSPEC.mdに明示します。

技術制約：使用中の言語・フレームワーク・DB・クラウド、既存アーキテクチャ
運用制約：チーム人数、運用体制、SLO、デプロイ頻度、監視の有無
チーム制約：学習コストの許容度、レビュー体制、保守できる人数

既存コードベースが大きい場合は、設計相談の前にコードの全体像を読ませる必要があります。読ませすぎを防ぐ進め方は「大きなコードベースをClaude Codeに理解させる手順」に分けてあります。設計相談では、その要約結果を入力として渡します。

ステップ3：1案ではなく複数案をトレードオフ付きで出させる

設計でAIが一番役立つのは、選択肢の幅出しです。1案だけ求めると、その案の正当化に進んでしまいます。比較表の形で要求します。

通知基盤の方式案を3つ出して。各案について次を表で比較して。
- 概要と主要コンポーネント
- 初期実装コストと運用コスト
- スケール特性と既知のボトルネック
- チームの学習コスト
- この案が向かないケース
最後に「現時点の制約だと私ならどれを推すか」と、その理由・前提・覆る条件を書いて。

返ってきた比較表は、結論ではなく論点リストとして読みます。Claude Codeの推奨は参考意見であり、採用判断の根拠は自分で確認します。

観点	案A	案B	案C
初期コスト	低	中	高
運用コスト	高	中	低
スケール上限	早く頭打ち	中規模まで	大規模対応
学習コスト	低	中	高
向かないケース	高トラフィック	厳密な順序保証	小規模・短納期

ステップ4：各案のリスクと検証方法を書かせる

設計の良し悪しは、うまくいく前提ではなく、壊れ方で決まります。各案について失敗モードと検証手段を書かせます。

推し案について次を出して。
- 想定される失敗モード上位5つと、それぞれの初期兆候
- 本番投入前に検証すべき項目と、その検証方法
- 後から変更が高コストになる決定（一方通行ドア）はどれか
- 段階的に導入する場合の最小の第一歩

「一方通行ドア（後戻りしにくい決定）」を切り分けるのは設計相談の核心です。後から変えやすい決定はAIの提案で前に進め、後から変えにくい決定は人間が時間をかけて判断します。

ステップ5：決定をADRとして記録する

相談しただけで記録しないと、3か月後に「なぜこの構成にしたか」を誰も説明できなくなります。決定はADR（Architecture Decision Record）として残します。Claude Codeに雛形を書かせ、判断部分は人間が埋めます。

今回の決定をADRとして docs/adr/0001-notification-architecture.md に書いて。
形式は「背景・検討した案・決定・理由・却下した案とその理由・想定リスク・見直し条件」。
未確定の数値や前提は「要検証」と明示して、断定しないで。

設計の前提や禁止事項のうち、毎回効かせたい短いものだけをCLAUDE.mdに残します。公式Best Practicesも、CLAUDE.mdに入れるべき内容として「プロジェクト固有のアーキテクチャ上の決定（Architectural decisions specific to your project）」を挙げています。長い検討経緯はADR側に置き、CLAUDE.mdは短く保ちます。