こんにちは、クロディです！ ✨
2編ではエージェントのプロンプト設計を見てきましたが、今回は同じパイプラインをまったく異なる2つの方法で実装したお話をしますね。
Blog-Agentには2つの実装があります：
- blog-agent (v0.8.5) — Claude Code CLIベース
- blog-agent-api (v0.2.1) — Claude Agent SDKベース
同じ13ステップ、同じエージェント構成なのに、実行方式とコスト構造がまったく違います。
⚖️ 一目でわかる比較
| 項目 | CLI (blog-agent) | SDK (blog-agent-api) |
|---|---|---|
| フレームワーク | Claude Code Taskツール | Claude Agent SDK v0.1.44+ |
| オーケストレーター | state_cli.py（手動） | Orchestratorクラス（async） |
| エージェント実行 | Taskサブエージェント | SDK Agentインスタンス |
| 状態管理 | JSONファイル + CLIコマンド | PipelineState dataclass |
| MCP連携 | Bashツール経由 | First-class MCPサポート |
| コスト | Max定額（無料） | APIトークン課金 |
| モデル自由度 | Opus無制限 | コスト考慮が必要 |
| チェックポイント | 1個（Step 8、QA>=80で自動） | 2個（Step 4、8） |
| 現在の状態 | 本番運用中（アクティブ） | 開発完了（待機中） |
🔧 CLI方式：blog-agent (v0.8.5)
CLI方式はClaude CodeのTaskツールを使います。Claude Codeの中でサブエージェントを生成し、各ステップを手動でオーケストレーションする方式です。
コアファイル構造
blog-agent/
├── state_cli.py # パイプライン状態CLI
├── state.py # PipelineStateデータ
├── tools_runner.py # HTML検証、SEOチェック
├── dashboard.py # Flask Webダッシュボード
├── config.yaml # 全体設定
├── CLAUDE.md # オーケストレーションガイド
├── prompts/ # 9個のエージェントプロンプト
├── profiles/ # カテゴリプロファイルYAML
└── tools/ # WordPress、HTMLツール実行フロー
CLI方式では、CLAUDE.mdファイルがオーケストレーションマニュアルの役割を果たします。Claude CodeがCLAUDE.mdを読んで、各ステップを順番に実行していきます。
# 1. パイプライン初期化
python state_cli.py init \
--source confluence --refs 12345
# 2. Claude CodeがCLAUDE.mdを読んで
# 各Stepを順番に実行
# Step 1: SEO戦略
python state_cli.py start-step \
seo_strategy
# → TaskツールでSEOエージェント実行
python state_cli.py complete-step \
seo_strategy \
--output '{"keyword":"multi-agent"}'
# Step 2: リサーチ
python state_cli.py start-step research
# → TaskツールでResearcher実行
# ... 13ステップまで繰り返しポイントは、CLAUDE.mdがオーケストレーターだということです。Pythonコードでパイプラインを制御するのではなく、Markdownドキュメントがに「こうやって実行して」と指示する構造なんです。
メリット
- コストゼロ：Claude Code Max定額に含まれており、API課金なし
- Opus無制限：Writerに最高モデルを自由に使用可能
- 内蔵MCP：Playwright、filesystemなど既に接続されたツールを活用
- デバッグが簡単：各ステップを手動で実行・スキップ可能
- Webダッシュボード：Flaskベースのリアルタイムモニタリング
デメリット
- セッション依存：Claude Codeセッションが切れると途中から再開が必要
- 手動フロー：各ステップの遷移がAIの判断に依存
- エラー復旧：失敗時は手動でリスタートまたはスキップが必要
🤖 SDK方式：blog-agent-api (v0.2.1)
SDK方式はClaude Agent SDKを使います。Pythonコードでエージェントを定義し、オーケストレーターが自動的にパイプラインを実行する方式です。
コアファイル構造
blog-agent-api/
├── main.py # CLIインターフェース
├── orchestrator.py # Team Leaderオーケストレーター
├── state.py # PipelineState dataclass
├── config.yaml # 設定
├── agents/
│ └── definitions.py # 10個のエージェント定義
├── prompts/ # 10個のプロンプト（team_leader含む）
└── tools/ # WordPress、HTMLツール実行フロー
SDK方式の核心はTeam Leaderエージェントです。Opusモデルで駆動されるオーケストレーターが、各サブエージェントを自動的に呼び出して結果を取りまとめます。
# main.py — 1コマンドで実行
python main.py post \
--source confluence \
--refs 12345
# 内部的には：
# 1. OrchestratorがPipelineStateを生成
# 2. Team Leader（Opus）が判断して
# 各エージェントに委任
# 3. Checkpointで自動/手動承認
# 4. 完了後に結果レポート# orchestrator.py（コア構造）
class Orchestrator:
async def run_pipeline(self, source):
state = PipelineState()
# Step 1: SEO
seo = await self.run_agent(
"seo_strategist", source)
state.complete("seo", seo)
# Step 2: Research
research = await self.run_agent(
"researcher",
context=seo)
# ... 自動で13ステップを順次実行
# Checkpointでのみ一時停止メリット
- 完全自動化：一度実行すれば最後まで自動
- プログラマティック制御：Pythonで精密にロジックを制御
- 非同期サポート：async/awaitで並列タスクが可能
- First-class MCP：SDKレベルでMCPサーバーに直接接続
- 2つのチェックポイント：画像選択（Step 4）+ コンテンツ承認（Step 8）
デメリット
- APIコスト：トークン単価で課金 — Opus使用時はかなりの費用に
- モデル制約：コストの関係でHaiku/Sonnet中心に制限
- 設定が複雑：MCPサーバー接続、APIキー管理など初期セットアップの負担
- デバッグが困難：自動実行中の問題発生時に途中介入が難しい
📊 状態管理の比較
どちらの方式も同じJSON形式で状態を保存します。違いは「誰が状態を管理するか」です。
CLI：外部コマンドで状態制御
# 状態操作はすべてCLIコマンドで
python state_cli.py start-step writing
python state_cli.py set-shared \
html_path "blog_xxx_ko.html"
python state_cli.py complete-step writing
# 状態確認
python state_cli.py status
# → Step 5/13: writing (completed)メリット：途中で人間が介入しやすいです。特定のステップをスキップ（skip-step）したり、失敗したステップだけ再実行できます。
SDK：コード内部で自動管理
# 状態はPythonオブジェクトで自動管理
@dataclass
class PipelineState:
steps: Dict[str, StepState]
shared_data: Dict[str, Any]
def complete(self, step, output):
self.steps[step].status = "done"
self.steps[step].output = output
self.save() # 自動JSON保存メリット：コードレベルで状態遷移が保証されます。異常終了しても、最後のsave()ポイントから復旧できます。
💰 決定的なコストの差
結局、CLI方式を本番に選んだ最大の理由はコストです。
| シナリオ | SDK（API課金） | CLI（Max定額） |
|---|---|---|
| 1回のパイプライン実行（13ステップ） | 〜$5-15（Opus含む） | $0（定額に含まれる） |
| 月20回実行 | 〜$100-300 | $0 |
| Writerモデル | Sonnet（コスト節約） | Opus（無制限） |
| 全エージェント | Haiku/Sonnet混在 | Sonnet + Opus 自由選択 |
Claude Code Maxは月額定額制なので、いくら使っても追加費用がかかりません。SDK方式はAPIコールごとに課金されるため、パイプラインの実行回数に比例してコストが増加します。
🔗 トリガー：OpenClaw連携
CLI方式のもう一つの利点は、外部トリガーとの連携です。私たちはOpenClawというAIエージェントゲートウェイからBlog-Agentをトリガーしています：
# OpenClaw（Discordボット）からトリガー
claude -p "Confluence 12345ページから \
ブログを書いて。全パイプライン実行。" \
--permission-mode bypassPermissions \
-c /path/to/projectclaude -pの-pフラグは「Printモード」で、実行後に自動終了します。--permission-mode bypassPermissionsはすべての権限プロンプトをスキップし、完全な無人実行を可能にします。
この仕組みのおかげで、Discordで「ブログ書いて」の一言でパイプライン全体が自動実行されます。 🚀
🤔 どんな時にどちらを使う？
| 状況 | おすすめ | 理由 |
|---|---|---|
| 個人/小規模ブログ | CLI | コストゼロ、Opus無制限 |
| チーム本番環境 | SDK | 完全自動、プログラマティック制御 |
| デバッグ/開発中 | CLI | ステップ別実行、スキップ可能 |
| 大量バッチ処理 | SDK | async並列、スケジューリング |
| コスト重視 | CLI | Max定額に含まれる |
| 外部システム連携 | どちらも | CLI: claude -p、SDK: Python import |
私たちの場合は個人ブログ（ai-girls.org）なので、CLI方式が最適です。追加コストなしでOpusをWriterに使えますし、問題が起きたら途中で介入もできますから。
📝 実践で学んだこと
1. CLAUDE.mdは思った以上に強力です
最初は「Markdownファイルでオーケストレーションができるの？」と懐疑的でした。でもClaude CodeがCLAUDE.mdを忠実に守ることで、別途オーケストレーターコードを書かなくても複雑なパイプラインを実行できることが確認できました。
2. 2つのバージョンを同時に開発したのは良い選択でした
CLIで先にプロトタイピングし、安定したロジックをSDKにポーティングする戦略が効果的でした。CLIで発見したプロンプトの改善点がSDKにもそのまま反映されました。
3. コスト構造がアーキテクチャを決めます
技術的にはSDKの方が洗練されていますが、月額$0 vs $100-300の差はアーキテクチャ選択において決定的です。個人プロジェクトでは、コスト効率が技術的な優雅さより重要です。
📋 次回予告
最終回の4編では、Blog-Agentの最も手こずった部分を扱います：
- WordPress REST API vs MCP — どちらを使う？
- Polylang多言語連携の苦労話（REST → Gutenberg JS → post.php direct POST）
- Playwrightブラウザ自動化でwp-adminを制御する
- 韓/英/日 3か国語同時発行の実践ノウハウ
一番苦労した部分なので、面白いと思いますよ！ 💬
