agent-decompose

name	agent-decompose
description	agent-discover の後に呼び出すスキル。spec.md を読んで業務プロセスをノードに分割し、各ノードを「決定論コード」と「LLM 判断」に振り分け、設計パターン（Reflection / Tool Use / Planning / Multi-Agent）を選定する。LangGraph のグラフ構造、ReAct ツール定義、ハイブリッド構成を design.md として出力する。「実装の設計をしたい」「ノードの切り方が分からない」「パターンの選び方を知りたい」と言われたとき呼ぶ。

agent-decompose — 業務分解 + 設計パターン選定

いつ使うか

• /agent-discover で spec.md が完成した直後
• 既存設計を見直したい / ノード構成を変えたい
• 「設計が複雑になりすぎている」と感じたとき

入力

workspace/<project>/vN/spec.md

出力

ファイル	内容
design.md	グラフ構造・ノード一覧・各ノードの責務・LLM/コード境界・設計パターン選定理由
tools.md	ReAct で使うツール一覧と各ツールの仕様（入出力・エラー時の挙動・最小権限）
detailed_design.md	詳細設計書 (シーケンス図・状態遷移図・データモデル等を Mermaid で網羅) ← reference/detailed_design_template.md を雛形に
spec.md	必要があれば更新（決定したパラメータを反映）
reports/decompose_report.md	作業報告（選んだ理由・捨てた選択肢）

進め方

Step 1: 業務プロセスをノードに分割

spec.md の「2. 業務ステップ」を読み、各ステップを LangGraph のノードに対応させる。

リサーチ系の典型例:

fetch → preprocess → enrich (コード) → summarize (LLM) → review → send

レビュー系の典型例:

intake → classify (LLM) → extract_rules (コード) → judge (LLM) → format → send

抽出系の典型例:

fetch → ocr → extract (LLM/Tool Use) → validate (コード) → store

アシスタント系の典型例:

receive_query → retrieve (Tool Use) → compose (LLM/Reflection) → respond

Step 2: 各ノードを「決定論コード」と「LLM 判断」に振り分け

reference/workflow_vs_agent.md のフレームワークで判定:

決定論コードでやる	LLM でやる
データ取得（API/RSS/DB）	自然言語の生成・要約
フィルタ・並び替え・集計	分類・関連性判断
重複排除・正規化	文脈解釈・判断
ファイル出力・配信	エラーリカバリー思考

鉄則: コードで書ける処理はコードで書く。LLM は最後に集中投下。

Step 3: 設計パターン選定

reference/design_patterns.md を読み、4パターンから必要なものを選ぶ:

パターン	向く場面	落とし穴
Reflection	高精度が必要、出力品質が最重要	回数制限なしでコスト爆発
Tool Use	外部 API/DB/ファイル操作が必要	権限管理不備、最小権限の原則
Planning	多段階タスク、順序判断が価値になる	計画の過剰詳細化、修正困難
Multi-Agent	役割分担が価値（Planner+Reviewer 等）	エージェント間調整コスト

実務はハイブリッド: 基本はワークフロー型、一部だけエージェント化が王道。

Step 4: ツール設計（Tool Use を使う場合）

reference/tools_pattern.md を参照。各ツールに以下を定義:

## tool_name
- 機能: 1行で説明
- 入力: 引数の型・意味
- 出力: 返り値の型・形式
- エラー時: 失敗パターンとフォールバック
- 権限: 何にアクセスできて、何にできないか
- キャッシュ: するか・キーは何か
- 呼び出し制限: 1回の実行で最大N回

Step 5: コスト見積もり

reference/cost_management.md を参照し、設計ごとに概算:

- LLM 呼び出し回数 × 平均トークン数 × 単価
- ツール呼び出しコスト（ReAct がループするほど増える）
- 軽量モード（一部スキップ）の選択肢を用意

Step 6: design.md を生成

# 設計図: <エージェント名> v1

## 1. グラフ構造
（LangGraph の Mermaid 図）

## 2. ノード一覧
| ノード | 責務 | LLM/コード | 入力 | 出力 |
|---|---|---|---|---|

## 3. 設計パターン選定
- 採用: ○○、△△
- 不採用: □□（理由）

## 4. データフロー
（State の構造、ノード間で受け渡す情報）

## 5. ツール一覧
（Tool Use がある場合、各ツールの詳細）

## 6. コスト見積もり
| モード | 1回あたり | 月間 |
|---|---|---|

## 7. 失敗モードと対処
（各ノードが失敗したらどうなるか）

## 8. 次のアクション
（agent-prototype で何を実装するか）

Step 7: detailed_design.md の生成 (必須)

reference/detailed_design_template.md をベースに、以下の図解を Mermaid で網羅:

• システムコンテキスト図 / デプロイ図
• コンポーネント図 (パッケージ依存)
• データモデル (TypedDict クラス図 + ER図)
• シーケンス図 (主要ユースケース 5〜7本: 正常系 / 各バリエーション / 失敗系)
• 状態遷移図 (チケットライフサイクル / 状態の有効フィールド遷移)
• アクティビティ図 / フローチャート (主要ノードの判定分岐)
• インターフェース仕様 (公開関数シグネチャ表)
• エラー処理・例外フロー
• ロギング・監視メトリクス
• 性能・コスト試算 (Gantt 形式のレイテンシ予算など)
• セキュリティ要件 (PII 流れ、脅威モデル)
• テスト戦略

design.md は概要、detailed_design.md は実装・運用・レビュー時に参照する。 シーケンス図 1 本でも、後の prototype / deploy フェーズで業務担当・SE 間の認識合わせが格段に楽になる。

Step 8: spec.md の更新

design.md と detailed_design.md の決定が spec.md と矛盾しないか確認。必要なら spec.md を更新。

このスキルの注意点

ノードを分けすぎない

10ノードを超えると見通しが悪くなる。5〜7ノードが目安。 複雑さが増えるなら、サブグラフ化（ノードの中にさらにグラフ）か、別エージェントに切り出し。

「全部エージェント化」を避ける

最初から Multi-Agent や Planning を採用すると、コストとデバッグ困難で頓挫しがち。 ワークフロー型で動くものを作ってから、必要箇所だけエージェント化する。

TypedDict のフィールド宣言を忘れない

LangGraph の StateGraph を使うなら、WorkflowState (TypedDict) に流すフィールドを 必ず全て宣言する。 未宣言のキーは silent drop され、ノード側で state.get("foo", default) のデフォルト値が常に使われる罠がある。

詳細: AGENT_MINDSET.md §「TypedDict / LangGraph での落とし穴」

次のステップ

/agent-prototype

design.md を読んで、reference/workflow_skeleton.py などの雛形から最小実装を組み立てる。