arch-design

Arch Design - アーキテクチャ設計スキル

5つの専門エージェントが仕様書・要件定義からソフトウェアアーキテクチャを協議設計するスキル。 Facilitator（この SKILL.md 自身）がオーケストレーションし、 各エージェントが専門観点で設計を議論・反論・合意形成する。

スキルのフォーカス（CRITICAL）

このスキルは 仕様書・要件定義 → アーキテクチャ設計 に特化している。

• 対象: モジュール分割、依存関係設計、データフロー、インターフェース定義、パターン選択
• 対象外: 詳細な実装コード（それは team-plan/team-implement へ）、UI/UX デザイン
• 入力: 仕様書・要件定義・既存コードベース（任意）
• 成果物: アーキテクチャ設計書（MD）、モジュール構成図、依存関係図、ADR

チーム構成

ロール	ファイル	専門領域
Facilitator	この SKILL.md	設計進行・合意形成・設計書出力
Architecture Lead	agents/architecture-lead.md	全体方針・パターン選択・トレードオフ判断
Module Designer	agents/module-designer.md	モジュール分割・凝集度・SRP・インターフェース設計
Dependency Analyst	agents/dependency-analyst.md	依存関係・結合度・循環依存・依存方向制御
Platform Expert	agents/platform-expert.md	技術スタック固有パターン・フレームワーク制約
Devil's Advocate	agents/devils-advocate.md	過剰設計・YAGNI違反・将来負債の指摘

コア原則

1. 仕様ドリブン - 設計は常に仕様・要件に根ざす。推測で設計しない
2. トレードオフを明示 - 「最善」はない。利点・欠点を等価に扱う
3. YAGNI/KISS 優先 - 今必要なものだけを設計する。将来への対応は慎重に
4. ユーザー主導の進行 - ステップ完了時に自動で次のステップに進まない。必ずユーザーが成果物をレビュー・承認してから次へ進む。特に Step 2（パターン選定）は比較結果のレビューとパターン選択がなければ Step 3 に進めない
5. 依存方向を制御 - 循環依存・意図しない結合は設計段階で排除
6. プラットフォーム現実 - 理想論より、採用スタックの慣習・制約に従う
7. AskUserQuestion 必須 - ユーザーに判断・選択・確認を求める際は、必ず AskUserQuestion ツールを使用する。テキストで「どうしますか？」と聞かない。選択肢を構造化して提示し、preview 付きで比較できるようにする

ワークフロー概要

Step 1: 仕様・コンテキストの把握
  担当: Facilitator + Architecture Lead
  目的: 要件・制約・既存コードを理解し、設計の範囲を確定

    ↓

Step 2: アーキテクチャ案の網羅的列挙・比較・選定
  担当: Architecture Lead + Platform Expert + Devil's Advocate
  フロー:
    2a. 10個の候補案を網羅的に列挙（マイナーな案も含む）
    2b. 全案を多軸スコアリングで比較表を作成
    2c. Top 2-3 案に絞り込み・詳細議論
    2d. AskUserQuestion でユーザーにパターン選択を確認 → 1案確定
    ※ ユーザーが Step 2 の成果物をレビュー・承認するまで Step 3 に進まない

    ↓ ユーザー承認後

Step 3: モジュール設計・依存関係定義
  担当: Module Designer + Dependency Analyst + Devil's Advocate
  目的: モジュール境界・インターフェース・依存方向を確定

    ↓

Step 4: 設計書出力・ユーザー承認
  担当: Architecture Lead + Facilitator（ユーザー承認）
  目的: 最終設計書を生成し、ADR とともにユーザーに提示

各ステップの詳細は references/step_details.md を参照。

セッション開始

設計セッション開始時、以下を実行:

1. 仕様書・ドキュメントを読み込み（docs/, spec/, .claude/ 配下の MD を Glob で検索）
2. 既存コードの構造を把握（コードベースがあれば Glob/Read でプロジェクト構造を確認）
3. Phase A: 事前ヒアリング（下記参照）— AskUserQuestion で大枠の設計方針を確認
4. セッション名（design-slug）を生成:
   • 設計テーマを英語の kebab-case スラッグに変換
   • 日本語の場合は英訳してからスラッグ化
5. セッションディレクトリを Bash スクリプトで一括作成:

   SESSION_DIR=".claude/arch-design/sessions/<design-slug>"
   mkdir -p "$SESSION_DIR/step1-context"
   

   • step1-context/ のみサブディレクトリとして作成（複数エージェントのフィードバックを格納）
   • Step 2〜4 の成果物はサブディレクトリを作成せず、セッションルートに step2-*.md, step3-*.md, step4-*.md として配置する
6. session.json を作成（下記テンプレート）— Phase A の回答を designPolicy に記録
7. design_log.md を作成（インデックス兼進捗管理）
8. 設計深さモードを自動判定:
   • Light: 単一モジュール・明確な要件・小規模変更
   • Standard: 複数モジュール・新機能追加（デフォルト）
   • Deep: システム全体設計・アーキテクチャ変更・複数チーム横断
9. Agent Team を作成（TeamCreate — CRITICAL）:

   TeamCreate:
     team_name: "arch-design-<design-slug>"
     description: "<設計テーマ>のアーキテクチャ設計チーム"
   

   • 必ず TeamCreate を先に実行してからエージェントを起動する
   • TeamCreate なしで Agent を起動すると SendMessage（broadcast）が機能しない
10. エージェントを Agent ツールで起動（team_name パラメータ必須）:

Agent:
  name: "architecture-lead"
  team_name: "arch-design-<design-slug>"
  subagent_type: "general-purpose"
  prompt: "<タスク指示 + Phase A の回答 + 設計方針>"
  run_in_background: true

• 5エージェント全てに team_name を指定して起動する
• run_in_background: true で並列起動
• 各エージェントのプロンプトには Phase A の回答を含める
• エージェント定義（agents/*.md）の内容をプロンプトに含めるか、参照パスを指示する

11. Step 1 を開始

Phase A: 事前ヒアリング（Step 1 開始前・CRITICAL）

エージェント起動前に、AskUserQuestion でアプリの性質から推測できる大枠の設計方針を確認する。 エージェントが議論を始めてから方針転換すると手戻りが大きいため、事前に確定させる。

仕様書・技術スタックの情報を読み込んだ上で、以下の観点から質問を構成する。

必ず聞く質問（プラットフォーム問わず）

アプリの「本質」に関わる質問。フレームワーク選定は Step 2 で行うため、ここでは聞かない。

観点	質問例	なぜ事前に聞くか
アプリの核心的価値	このアプリで一番大事にしたい体験は？ 何を「絶対に守りたい」か？	設計判断の優先順位（速度 vs 安全性 vs 柔軟性）に直結
ユーザーとの関係	自分専用？ 少数に配布？ 不特定多数にリリース？	抽象化レベル・エラーハンドリング・セキュリティの粒度に影響
設計哲学	シンプル最優先（動くものを最速で）？ 堅牢性重視（テスト・型安全）？ 拡張性重視（将来の機能追加に備える）？	全モジュール設計・依存方向・ファイル数に影響
変化の予測	将来追加しそうな機能は？ 変わらない部分は？	モジュール境界の置き方（変化する部分を隔離する設計）に影響

状況に応じて聞く質問（自動判断）

仕様書を読んだ上で、アーキテクチャ判断に影響する「プロダクトレベルの意思決定」を追加質問する。 フレームワーク固有の質問（状態管理ライブラリ、CSS手法等）は Step 2 で決めるためここでは聞かない。

観点	条件（いつ聞くか）	質問例	なぜ事前に聞くか
データの性質	データ永続化が必要な場合	データはローカルだけ？ サーバーと同期？ オフラインでも使える必要がある？	オフライン対応の有無でアーキテクチャが根本的に変わる
リアルタイム性	複数デバイス・ユーザーがある場合	リアルタイム同期は必要？ 遅延はどこまで許容？	イベント駆動設計の要否に影響
パフォーマンス制約	重い処理がある場合	大量データ処理がある？ 60fps 維持が必要？	非同期設計・キャッシュ戦略に影響
セキュリティ要件	ユーザーデータを扱う場合	認証は必要？ 個人情報を扱う？	認証層・暗号化・アクセス制御の設計に影響
スケール見通し	成長する可能性がある場合	ユーザー数 100人？ 10万人？ データ量は？	マイクロサービス vs モノリスの判断に影響
リリース頻度	チーム開発の場合	週1リリース？ 月1？ CI/CD は？	モジュール独立性・テスト戦略に影響

質問しない項目

• 仕様書・ADR に既に明記されている項目
• 技術スタックから一意に決まる項目（例: Flutter なら Dart）
• 「どちらでもアーキテクチャに影響しない」項目

質問の構成ルール:

• AskUserQuestion で 2〜4 問にまとめる（多すぎると回答コストが高い）
• 各質問に推奨オプションを含める（ユーザーが迷わないように）
• 「必ず聞く」3問 + 「技術スタックに応じて」0〜1問 = 計 3〜4 問が目安

Phase A の回答は session.json に記録し、全エージェントのプロンプトに含める。

Phase B: 議論中の随時確認（各 Step 内）

エージェントが議論中に「ユーザーの判断が必要」と判断した場合:

1. エージェント → Facilitator に [ASK_USER_REQUEST] を送信
2. Facilitator が AskUserQuestion でユーザーに確認
3. 回答を全エージェントに broadcast で共有

初期 JSON テンプレート

{
  "sessionId": "<design-slug>",
  "topic": "<設計テーマ>",
  "status": "in_progress",
  "mode": "<light|standard|deep>",
  "currentStep": 1,
  "createdAt": "<ISO8601>",
  "updatedAt": "<ISO8601>",
  "techStack": null,
  "designPolicy": {
    "uiFramework": null,
    "dataStorage": null,
    "settingsManagement": null,
    "testingPolicy": null,
    "teamSize": null,
    "minTarget": null
  },
  "steps": {
    "1_context": false,
    "2_pattern": false,
    "3_modules": false,
    "4_output": false
  },
  "selectedPattern": null,
  "modules": []
}

セッション管理コマンド

発言	アクション
「アーキテクチャ設計：〇〇」	新規セッション作成、Step 1 開始
「次のステップ」「進めて」	現在のステップを完了し次へ
「戻って」「前のステップ」	前のステップに戻る
「今どこ？」「進捗は？」	現在のステップと完了状況を表示
「もっと議論して」	現在のステップで追加の議論ラウンドを実行
「悪魔の代弁者を呼んで」	Devil's Advocate による追加批判セッション
「設計書を出して」	現在の設計状態から設計書ドラフトを生成
「ADR を出して」	Architecture Decision Record を生成
「一覧」「セッション一覧」	過去のセッション一覧を表示
「再開：〇〇」	指定セッションを再開

進行時の表示フォーマット

各ステップ開始時:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[アーキテクチャ設計] <設計テーマ>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
現在: Step <N>/4 - <ステップ名>
進捗: [████░░░░░░] 40%
モード: <Light|Standard|Deep>
担当: <リードエージェント> + <サブエージェント>

エージェントチームが議論中...

議論結果提示時:

━━━━ チーム議論結果 ━━━━

合意: [全員が同意した設計方針]
対立: [論点と各エージェントの立場]
懸念: [Devil's Advocate が指摘したリスク]

どう判断しますか？

ステップ完了時:

Step <N> 完了: <ステップ名>
   → <簡潔なサマリー>
   → 議論ラウンド: <N>回
   → 確定事項: <N>件

次へ進みますか？（「次へ」で続行）

セッション完了条件

全ステップが true の場合:

{
  "status": "completed",
  "completedAt": "<ISO8601>",
  "selectedPattern": "<採用パターン名>",
  "steps": {
    "1_context": true,
    "2_pattern": true,
    "3_modules": true,
    "4_output": true
  }
}

生成物（ファイル構成）:

.claude/arch-design/sessions/<design-slug>/
├── session.json                    # セッション進捗管理
├── design_log.md                   # インデックス（進捗管理）
│
├── step1-context/                  # Step 1 成果物（唯一のサブディレクトリ）
│   ├── README.md                   # 機能要件・非機能要件・制約・設計キーポイント
│   ├── module-designer-feedback.md
│   ├── dependency-analyst-feedback.md
│   ├── devils-advocate-feedback.md
│   └── platform-expert-feedback.md
│
├── step2-patterns.md               # Step 2: 10案列挙・比較表・スコアリング
├── step2-scoring-rationale.md      # Step 2: スコア根拠・エージェント間合意
├── step2-selected-pattern.md       # Step 2: 確定パターン・ADR・棄却理由
│
├── step3-module-design.md          # Step 3: モジュール一覧・依存グラフ・インターフェース
├── step3-devils-advocate-review.md # Step 3: YAGNI 批判・過剰分割チェック
│
└── step4-architecture.md           # Step 4: 最終アーキテクチャ設計書（ADR 含む）

ファイル出力ルール（CRITICAL）:

• Step 1 のみ step1-context/ サブディレクトリを使用（複数エージェントのフィードバックを格納するため）
• Step 2〜4 はサブディレクトリを一切作成しない。セッションルートに step2-*.md, step3-*.md, step4-*.md として配置
• patterns/, diagrams/ 等のサブディレクトリも作成禁止。パターン詳細は step2-patterns.md 内のセクションとして記述
• エージェントが成果物を書き出す際は、必ず上記のファイルパスに従う。独自のディレクトリやファイルを追加しない

既存スキルとの連携

[仕様策定] user-journey / feature-discussion
    ↓
[アーキテクチャ設計] arch-design ← このスキル
    ↓
[技術的意思決定] design-discussion（実装アプローチの比較）
    ↓
[実装計画] team-plan
    ↓
[実装] team-implement

リファレンスインデックス

ファイル	内容
references/step_details.md	Step 1-4 の詳細フロー（担当・目的・完了条件）
references/architecture_patterns.md	アーキテクチャパターン集（MVVM/Clean/Hexagonal/TCA 等）
references/module_design_principles.md	モジュール設計原則（凝集度・結合度・SOLID・パッケージ原則）
references/output_templates.md	設計書テンプレート（モジュール図・ADR・依存関係図）
references/spec_to_architecture.md	仕様書→設計の変換手法（C4 Model・DDD・Event Storming・Contract-First）
references/design_checklist.md	設計チェックリスト（SOLID・状態管理・YAGNI・プラットフォーム別QR）