オーケストレーション設計

オーケストレーションパターンとは

Claude Codeの3つの拡張機構（Command、Agent、Skill）を階層的に組み合わせる設計パターンです。 それぞれの役割を明確に分離することで、複雑なワークフローを管理しやすい単位に分解できます。

• Command — エントリーポイント。ユーザーとの対話とワークフロー全体の調整を担当
• Agent — データ取得や自律処理。分離コンテキストで独立して動作
• Skill — 出力生成や特定の処理。独立した手順としてコンテキストからデータを受け取る

この3層構造により、各コンポーネントは単一責任を持ち、 テストや修正が容易になります。

アーキテクチャの全体像

オーケストレーションの全体的な流れを整理します。

ユーザー
  │
  ▼
/command（エントリーポイント）
  │  ユーザー対話・ワークフロー制御
  │
  ├──▶ Agent tool → agent（データ取得・自律処理）
  │                    ├── preloaded skill（ドメイン知識）
  │                    └── 結果を返却
  │
  └──▶ Skill tool → skill（出力生成）
                       └── ファイル出力・レンダリング

Commandがオーケストレーターとして全体を制御し、 必要に応じてAgent toolやSkill toolで各コンポーネントを呼び出します。 Agentは分離コンテキストで自律的にデータを取得し、 Skillは受け取ったデータを元に出力を生成します。

天気システムの具体例

公式ドキュメントで紹介されている天気システムを例に、各コンポーネントの役割と配置場所を見ていきます。

# ファイル配置
.claude/
  commands/
    weather-orchestrator.md   # Command: エントリーポイント
  agents/
    weather-agent.md          # Agent: データ取得
  skills/
    weather-fetcher/
      SKILL.md                # Agent Skill: API手順（プリロード）
    weather-svg-creator/
      SKILL.md                # Skill: SVG出力生成

各コンポーネントの設定を見てみましょう。

Command: weather-orchestrator

---
description: Fetch weather data and create an SVG weather card
model: haiku
---

# 天気カード作成ワークフロー

1. AskUserで温度単位（摂氏/華氏）を確認
2. Agent toolでweather-agentを呼び出しデータ取得
3. Skill toolでweather-svg-creatorを呼び出しSVG生成

Agent: weather-agent

---
name: weather-agent
description: "Use this agent PROACTIVELY when you need to fetch weather data"
tools:
  - WebFetch
  - Read
  - Write
  - Edit
model: sonnet
color: green
maxTurns: 5
permissionMode: acceptEdits
memory: project
skills:
  - weather-fetcher
---

# 天気データ取得エージェント

weather-fetcherスキルの手順に従い、天気APIからデータを取得します。

Agent Skill: weather-fetcher

---
name: weather-fetcher
description: Instructions for fetching current weather temperature data
user-invocable: false
---

# 天気データ取得手順

1. Open-Meteo APIにリクエスト
2. レスポンスから温度データを抽出
3. 構造化されたJSON形式で返却

Skill: weather-svg-creator

---
name: weather-svg-creator
description: Creates an SVG weather card showing the current temperature
---

# SVG天気カード生成

受け取った温度データを元に、視覚的な天気カードをSVG形式で生成します。

実行フローの7ステップ

天気システムの実行フローを、ステップごとに追いかけてみましょう。

1. ユーザーが/weather-orchestratorを実行 — Commandが起動し、ワークフローが開始されます
2. CommandがAskUserで温度単位を質問 — 「摂氏と華氏、どちらで表示しますか？」とユーザーに確認します。 ユーザーインタラクションはCommandの役割です
3. CommandがAgent toolでweather-agentを呼び出し — ユーザーの回答を含めてAgentにタスクを委譲します。 ここからAgentは分離コンテキストで自律的に動作します
4. Agentがプリロードされたweather-fetcherの手順でAPIコール — Agentの起動時にweather-fetcherの内容がコンテキストに注入されており、 その手順に従ってAPIを呼び出します
5. Agentが温度データを返却 — 取得したデータを構造化してCommandに返します。 Agentのコンテキストはここで終了し、メインの会話に結果だけが渡されます
6. CommandがSkill toolでweather-svg-creatorを呼び出し — Agentから受け取った温度データを渡して、SVG生成を依頼します
7. SkillがSVG + サマリーファイルを生成 — 最終的な成果物としてSVGファイルとテキストサマリーが出力されます

5つの設計原則

オーケストレーションパターンを設計する際に意識すべき原則をまとめます。

原則1: 2つのSkillパターンを使い分ける

Skillにはプリロード（Agent内知識）と直接呼び出し（独立処理）の2パターンがあります。 天気システムでは、weather-fetcherがプリロード型（Agentのドメイン知識として注入）、 weather-svg-creatorが直接呼び出し型（Commandから独立して呼び出される）です。

原則2: Commandがオーケストレーター

ユーザーとの対話とワークフロー全体の調整はCommandが担当します。 Commandは「何を・どの順番で」実行するかを決め、実際の処理はAgent/Skillに委譲します。

原則3: Agentはデータ取得

分離コンテキストで自律的にデータを取得するのがAgentの役割です。 API呼び出し、データベースクエリ、ファイル調査など、情報収集タスクに向いています。

原則4: Skillは出力生成

コンテキストから受け取ったデータを元に、最終的な出力を生成するのがSkillの役割です。 独立して実行され、入力と出力が明確です。

原則5: 単一責任（Fetch→Render分離）

「データを取る」と「データを表示する」を1つのコンポーネントに混ぜないでください。 Fetch（Agent）→ Render（Skill）の明確な分離が、保守性とテスタビリティを高めます。

実務への応用例

天気システムのパターンを実務に応用した例を紹介します。

業務報告ワークフロー

# /weekly-report（Command）
# → data-collector（Agent + db-fetcher Skill）
# → report-generator（Skill）

# .claude/commands/weekly-report.md
---
description: 週次業務報告を自動生成する
model: haiku
---

1. Agent toolでdata-collectorを呼び出し、今週のデータを収集
2. Skill toolでreport-generatorを呼び出し、レポートを生成

# .claude/agents/data-collector.md
---
name: data-collector
description: "PROACTIVELY collect project data for reports"
model: sonnet
maxTurns: 5
permissionMode: acceptEdits
skills:
  - db-fetcher
---

# .claude/skills/report-generator/SKILL.md
---
name: report-generator
description: Generate formatted weekly reports from collected data
---

SEO記事ワークフロー

# /seo-article（Command）
# → research-agent（Agent）
# → article-writer（Skill）

# .claude/commands/seo-article.md
---
description: SEO最適化された記事を生成する
model: haiku
---

1. AskUserでキーワードとターゲットを確認
2. Agent toolでresearch-agentを呼び出し、競合・キーワード調査
3. Skill toolでarticle-writerを呼び出し、記事を生成

# .claude/agents/research-agent.md
---
name: research-agent
description: "PROACTIVELY research keywords and competitors for SEO"
model: sonnet
maxTurns: 8
tools:
  - WebFetch
  - Read
  - Write
---

# .claude/skills/article-writer/SKILL.md
---
name: article-writer
description: Write SEO-optimized articles from research data
---

まとめ

オーケストレーション設計は、Command・Agent・Skillの3つの拡張機構を組み合わせる最も高度なパターンです。 単一責任の原則に従い、各コンポーネントに明確な役割を持たせることで、 複雑なワークフローでも見通しよく管理できます。 まずは小さなワークフローから始めて、徐々にコンポーネントを増やしていくのがおすすめです。