ClaudeCode × OpenAI API　役割分担の設計

〜湯かげアーキテクチャが生まれるまで〜

この資料について

本資料は筆者ソウが実際に運用している環境における、ClaudeCodeとOpenAI APIの使い分け記録です。コストや運用形態は環境やモデル選定により変わるため目安としてご覧ください。ClaudeCodeを「対話的に詰める担当」、OpenAI APIを「仕様確定後にバッチ処理として流す担当」として役割分担を設計し、実運用での失敗例も含めてまとめました。

湯かげアーキテクチャ：3段レイヤー設計

タスク振り分けのフロー

役割の違い

	ClaudeCode（対話モード担当）	OpenAI API（バッチ実行担当）
向いている仕事	判断・設計・振り分け・記録管理	定型処理・フォーマット変換・HTML生成・構造化テキストの分析・フィードバック生成
コスト傾向	対話モードはトークン消費が大きい（※モデル・使い方により変動）	単発実行のため必要分だけ消費（※モデルにより変動）
呼び出し方	ユーザーが直接対話	スクリプト経由でAPIを叩く
使い方の違い	対話的に詰める（仕様が曖昧でも動ける）	バッチで流す（仕様が確定してから渡す）
状態保持	session.md（自分で運用するファイル）で引き継ぐ	Chat Completions API想定は毎回完結。Responses APIは状態保持可能。
代表的な用途	戦略相談・コードレビュー・チーム指示	タイムライン生成・HTML整形・バッチ処理・会話ログ分析・仕様文書要約・品質チェック（構造化インプット前提）

待機ルールの設定方法（CLAUDE.mdへの記述例）

過去に話し合い中にClaudeCodeが承認語（「いいですね」など）を誤って実装指示と認識して動き出す事故がありました。これを防ぐため、CLAUDE.mdに以下を記載し運用しています。

エージェントが呼ばれたら実装・処理への移行を一時停止する。
「実装して」「やって」など明示的な指示があるまで動かない。
「いいですね」「みたいな感じ」は実装GOではない。
session.mdに「▶ エージェント待機中」欄を立て、宣言があるまでクロコは動かない。

使えるスクリプト例

check_timeline.py — タイムラインの抜け検出（APIなし）

import re
with open("timeline.html", "r") as f:
    html = f.read()
links = re.findall(r'href="activity6\.html#(disc-\d+)"', html)
nums = [int(x.split("-")[1]) for x in sorted(set(links))]
missing = set(range(min(nums), max(nums)+1)) - set(nums)
print(f"抜け：{sorted(missing)}" if missing else f"OK（disc-{min(nums)}〜{max(nums)} 全件）")

※ activity6.html と href のパターンは筆者環境固有です。ご自身の環境に合わせて調整してください。

gen_timeline.py — OpenAI APIでHTML生成

python3 gen_timeline.py --from 154 --to 160
activity6.htmlからdiscのタイトル・日付・タグを読み取り、timeline.html用のHTMLを自動生成します。

失敗から学んだこと

「いいですね」事件：承認語を実装指示と誤解し動き出したため、待機ルールを設けて解決。
仕様未確定での外注：仕様が固まる前にAPIに渡すと手戻りが発生。確定後に外注すべき。
セッション断の積み残し：session.mdに実行済み範囲を記録し、再起動時の引き継ぎを徹底。

まとめ

ClaudeCodeは対話で仕様を詰める役割を担い、OpenAI APIは仕様確定後にバッチで処理を行う役割です。この役割分担とCLAUDE.mdへの待機ルール記述により、コスト管理と運用効率が大幅に向上しました。今後もこの設計を基点に、より良い運用を目指していきます。

著者：ソウ（翻訳担当）｜2026-05-02

ClaudeCode × OpenAI API 役割分担の設計