Claude Codeサブエージェント実例｜LLMに注文APIを渡さない3層設計を週次戦略OSSで解説

Claude Codeのサブエージェントを「複数用意して分業させる」ところまでは、もう珍しくありません。難しいのはその先です。エージェントが出した結論を、どうやって信用するのか。そして、副作用のあるAPI（メール送信、デプロイ、決済、発注）を、エージェントにどこまで触らせるのか。

tradermonty氏の claude-weekly-trade-strategy は、この2つに正面から答えている珍しいリポジトリです。米国株の週次戦略レポートを生成するという題材そのものより、LLMの出力を機械で突き返すゲートと、LLMに注文APIを一度も渡さない3層構成の方が読む価値があります。本記事はリポジトリの実コードを読んで、その設計を追いかけます（本記事は技術構成の解説であり、投資助言・売買推奨ではありません）。

Claude Code自体のインストールから CLAUDE.md・Hooks・本番運用までの全体像は Claude Code｜2026年版・インストールからCLAUDE.md・Hooks・本番運用までの実装手引き にまとめています。本記事はその応用編として、実際に動いているエージェント構成を1本読み解く位置づけです。

claude-weekly-trade-strategyとは｜7体のサブエージェントで週次レポートを組み立てる

まず、このリポジトリが何をするものかを整理します。ユーザーがやることは、TradingViewやFinVizで取得した週次チャート画像を charts/YYYY-MM-DD/ に置き、Claude Codeでワークフローを起動することだけです。READMEは16枚のチャート（VIX・米10年債利回り・主要4指数・コモディティ5種・セクター3種・ブレッドス2種）を推奨構成として挙げています。

そこから先は5ステップの分業です。READMEが「Workflow Overview (v2.5)」として示す流れを、実際の .claude/agents/ の中身と突き合わせると次のようになります。

各ステップは、それぞれ専任のサブエージェントが担当します。リポジトリの .claude/agents/ には7つの定義ファイルが置かれています。

・technical-market-analyst：チャート画像を読み、テクニカル分析レポートを出す
・us-market-analyst：市場環境（過熱感・センチメント・セクターローテーション・市場の広がり）を評価する
・market-news-analyzer：過去10日のニュースの影響と、今後7日の経済指標・決算予定を整理する
・weekly-trade-blog-writer：上の3本のレポートと前週分を統合し、1本のレポートに書き起こす
・strategy-reviewer：出来上がった原稿のチャート読解が正しいかを検査する（定義ファイルは39KBと7体中で最大）
・druckenmiller-strategy-planner：中期シナリオを組む任意ステップ
・blog-publisher：公開処理を担当する

サブエージェントはさらに、.claude/skills/ にある11個のスキルを呼び出します。ここが単なる「プロンプトを分けただけ」の構成と違う点です。たとえば breadth-chart-analyst スキルには detect_breadth_values.py（21KB）・detect_uptrend_ratio.py（29KB）といった画像から数値を読み取るPythonスクリプトと、そのユニットテストまで同梱されています。チャート画像の数値読み取りをLLMの目視だけに任せず、スクリプトで抽出する構えになっているわけです。

週次のレポート生成とは別に、日次で回る仕組みも用意されています。daily-action-plan スキルには当日の行動計画を組み立てる build_plan_state.py と、その計画を検証する verify_plan.py が対になって入っており、scripts/launchd/ には寄り付き前と引け後に起動するmacOS用の常駐設定が2つ置かれています。生成した内容はメールで通知する作りです。週次で方針を作り、日次で回し、機械で検証するという運用の骨格が、リポジトリの構成そのものに現れています。

サブエージェントとスキルの粒度をどう切るかは、それ自体が独立した設計論です。本リポジトリは「LLMの目視で足りる判断はサブエージェントに、数値の抽出はスキル側のスクリプトに」という寄せ方をしており、検証可能な処理をコードへ落とすパターンを実際に踏んでいる例と読めます。

LLMに注文APIを渡さない3層アーキテクチャ｜サブエージェントとルールエンジンの分業

ここからが本題です。READMEを読むだけだと、このリポジトリは「レポート生成ツール」に見えます。しかし pyproject.toml を開くと、様子が違います。

[project]
name = "weekly-trade-strategy-bot"
description = "Automated trading system based on weekly strategy blog posts"
dependencies = [
    "alpaca-py>=0.30",
    "anthropic>=0.40",
    "apscheduler>=3.10,<4.0",
]

パッケージ名は -bot、説明は「週次戦略レポートに基づく自動売買システム」、そして依存に alpaca-py（ブローカーのAPIクライアント）が入っています。実際 trading/ ディレクトリには102本のPythonファイルがあり、GitHub Actionsの3ジョブのうち1つは pytest trading/tests を回しています。つまりこのリポジトリは、レポートを書くエージェント層と、そのレポートを解釈して実行する層の両方を含んでいます。

そして、その実行層の作りがこの記事の核心です。docs/auto-trade-system-design-v2.md（55KB）と実装を照合すると、明確に3層に分かれています。

Layer 1 はLLMを使いません。 15分間隔で市場データを取得し、閾値突破・ストップロス・配分ドリフトを決定論的にチェックするだけです。設計書はここを「Claudeは使わない（コストゼロ、遅延なし）」と明記しています。大半の巡回は何も起こさずに終わります。

Layer 2 で初めてClaudeが呼ばれます。 ここで与えられているツールを trading/layer2/system_prompt.py で確認すると、get_market_data・get_portfolio_state・get_signal_status・get_trade_history という読み取り専用の4つと、emit_strategy_intent という意図を出力する1つしかありません。注文を出すツールは定義そのものが存在しません。システムプロンプトにも次の行があります。

・Never directly execute orders. You only emit intent; the system validates and executes.（訳：注文を直接実行してはならない。意図を出すだけであり、検証と実行はシステムが行う）
・You MUST use the emit_strategy_intent tool to output your decision. Never describe trades in text.（訳：判断は必ず専用ツールで出力し、文章で取引を記述してはならない）

後者は地味ですが重要です。「文章で書くな、ツールで構造化して出せ」と縛ることで、下流のコードが自然言語を解釈し直す必要をなくしています。加えて、確信度を low / medium / high で自己申告させ、データが古い・矛盾している場合は low を選べと指示しています。

Layer 3 が実際の発注を担当します。 ただし受け取った意図をそのまま流すわけではなく、OrderValidator が検査します。実装で確認できるのは、許可銘柄リストとの照合、指定シナリオがレポート内に実在するかの確認、シナリオ配分からの逸脱幅（既定±3%）の検査です。許可銘柄は trading/core/constants.py にハードコードされた12銘柄（SPY・QQQ・DIA・XLV・XLP・GLD・XLE・BIL・TLT・URA・SH・SDS）だけで、LLMがこれ以外を出力しても弾かれます。検証に落ちた場合は発注せず、通知と監査ログだけを残す ALERT_ONLY に落ちます。

さらに、LLMの判断より優先して効く停止条件があります。trading/layer1/kill_switch.py は、日次損失・週次損失・高値からの下落率・VIXの4条件を優先順に評価し、1つでも触れれば停止理由を返します。trading/config.py の既定値は次の通りです。

エージェントの処理を状態機械やグラフとして設計する考え方は エージェントをグラフとして設計する｜Claude Code動的ワークフローで多段処理を並列化する考え方 で扱っています。本リポジトリの3層構成は、そこで言うノードの責務分離を「権限の境界」として引いた例として読むと理解しやすくなります。なお設計書は、この実行層をClaude Agent SDKを活用して構築する方針として記述しています。

最も脆いのは「自然言語に書き戻す」工程

この構成には、正直に見ておくべき弱点があります。エージェントが書いたレポートは日本語の文章で、実行層はそれをもう一度パースして構造化データに戻しているという点です。

その役割を担うのが trading/layer2/tools/strategy_parser.py で、35KBとツール群の中で突出して大きく、冒頭のコメントにも「このシステムで最も重要なモジュール」と明記されています。日本語のレポートから配分・シナリオ・売買水準・トリガー条件・ストップロスを正規表現で抽出し、StrategySpec という構造体に変換します。

つまり流れとしては、構造化された分析 → 自然言語のレポート → 再び構造化データという往復が起きています。人間が読むレポートと機械が読む仕様を1つのファイルで兼ねているため、レポートの書式が少し揺れるだけで解釈が変わり得ます。実際、コミット履歴には「レポート書式の揺れに対するパーサーの頑健性を改善」というコミット（2026-05-10）が残っており、この往復が実運用で問題になったことがうかがえます。

生成物を機械が突き返す｜pre-flight / post-flight という二重ゲート

もう1つの見どころが、レポートの品質保証です。LLMに書かせた文章の事実確認を、人間のレビューでも別のLLMでもなく、Pythonスクリプトの決定論的チェックでやっています。

流れはこうです。執筆の前に scripts/preflight_blog_facts.py を走らせ、facts_snapshot.json を作ります。ここに入るのは、ETFの現値（20銘柄をAPIから取得）、オプションの満期日（米国の休日を考慮して算出）、対象期間の祝日、日付と曜日の対応表です。執筆前に「動かせない事実」を固定するわけです。

執筆後は scripts/postflight_blog_check.py が、出来上がった原稿をそのスナップショットと突き合わせます。終了コードは0（合格）・1（違反あり）・2（前提ファイルが無い）に分かれ、CIから機械的に判定できます。

とりわけ面白いのが禁止語の正規表現リストです。これは一般的なNGワード集ではなく、過去のレビューで実際に出た誤りが、そのままパターンとして固定されています。コードには理由がコメントで併記されています。

・Powell 退任 → 任期終了と退任は別物なので表現を改めよ、という指摘由来
・wikipedia → 一次ソースではないので参照先に使うな
・GLD ≈ GC / 10 → 換算値ではなくETFの現値を使え
・推定 HH:MM ET → 決算発表時刻を推定で書くな
・満期日の特定パターン → 祝日による前倒しを計算し直せ

つまり、レビューで一度指摘した誤りを、二度と通さないように機械化しているわけです。コード内のコメントによれば、これらは当初は警告扱い（--strict を付けたときだけ失格）でしたが、後のレビューで「エージェント側のドキュメントが『ビルドを落とす』と約束しているのに実装が緩い」という矛盾が指摘され、仕様に合わせて全て高重要度へ格上げされています。この格上げはチェックを既定でブロックする本物のゲートに変えたコミット（2026-05-16、リポジトリ最終更新）として履歴に残っています。

検証の対象は原稿だけではありません。決算発表の時刻などを扱う ir_events.yaml は、生成した時点では時刻が埋まっておらず、担当エージェントが確認済みの値を入れる前提になっています。この manifest が存在しない場合、post-flightは警告ではなく終了コード2（前提不足）で停止します。コメントによれば、以前は「manifestが無ければ中程度の指摘」に留めていたため、既定モードのまま合格してしまい、IRのクロスチェックが黙って無効化されていたことがあったといいます。チェックが素通りする経路を塞ぐという、地味だが重要な修正です。

CI側でもこの二重ゲートは担保されています。GitHub Actionsは3ジョブ構成で、post-flightのスモークテスト、IR manifestのスキーマ検証（生成→検証を実際に走らせる）、そして実行系のテストをそれぞれ回しています。

この「書く → 評価する → 直す」を機械化して回す発想自体は、エージェント設計の一般論としても整理されています。ハーネス側の原則は agents-best-practices完全解説｜プロバイダ中立のエージェントハーネス設計8原則とMVP構築ガイド にまとめており、本リポジトリはその原則を1つの題材で具体化した実装例と見ることができます。

自分の環境で構成を確認する手順

実際に中身を確認したい場合の手順です。前提として Claude Code CLI が必要です。.claude/agents/ はClaude Code固有の機能のため、READMEも「Claude Desktopでは動作しない」と明記しています。FMP APIキーは任意で、無くてもチャート分析と市場環境評価は動きますが、決算・経済カレンダーの自動取得は手動確認に変わります（無料プランは1日250リクエスト）。

まずリポジトリを取得し、エージェントとスキルの構成を確認します。

git clone https://github.com/tradermonty/claude-weekly-trade-strategy.git
cd claude-weekly-trade-strategy

# サブエージェントの一覧と、それぞれの定義サイズを見る
ls -la .claude/agents/

# スキルの一覧（検証スクリプト付きのものが混じっている）
ls -d .claude/skills/*/

次に、実行系がどのモードで動く設定になっているかを確認します。ここが安全側に倒れているかどうかは、読む前に必ず見ておく箇所です。

# 既定が dry-run かどうか、接続先がペーパー用かを確認する
grep -nE "dry_run|paper-api|base_url" trading/config.py

# LLMに渡されているツールの一覧（注文系が無いことを確認する）
grep -n '"name"' trading/layer2/system_prompt.py

# 許可されている銘柄リスト
sed -n '/ALLOWED_SYMBOLS/,/})/p' trading/core/constants.py

trading/config.py は dry_run: bool = True が既定で、Alpacaの接続先も既定が https://paper-api.alpaca.markets（ペーパートレード用）です。python -m trading.main を引数なしで起動した場合も dry-run になります。

安全側への倒し方が二重になっている点は、読んでおく価値があります。main.py は起動時に dry_run = not args.live としており、CLIの指定が環境変数より優先されます。TRADING_DRY_RUN を書き換えても、引数なし起動なら dry-run のままです。そして --live を付けても、接続先は切り替わりません。エンドポイントと認証情報は環境変数側にあり、既定はペーパー口座のままです。つまり実資金の口座に注文を出すには、--live に加えて認証情報とURLを差し替えるという別の操作が必要になります。作者のTODO.mdでも、この2つは別々の項目として管理されています。

導入前に押さえる3つの制約｜ライセンス・単独開発・検証未完了

中身が厚い一方で、そのまま持ち込むには無視できない制約があります。ここを飛ばすと判断を誤ります。

第一に、ライセンスが設定されていません。 リポジトリに LICENSE ファイルは存在せず（LICENSE / LICENSE.md ともに404）、GitHub APIのライセンス欄も null、pyproject.toml にも license の指定がありません。明示的な許諾が無い以上、既定では著作権が留保された状態です。エージェント定義やスキルを自分のリポジトリへコピーして使う、という読み方はできません。設計を読んで学ぶ対象として扱うのが妥当です。

第二に、単独開発かつ更新が止まっています。 コントリビュータは1名、リリースは0件、最終pushは2026-05-16で、本記事執筆時点から2か月以上動きがありません。スター22・フォーク11という規模は、広く検証されたプロジェクトではないことを意味します。

第三に、実行系の運用検証が完了していません。 trading/TODO.md（最終更新2026-02-14）には「Phase 1完了、Phase 2のコード完了、E2Eテスト全実装、388テスト通過」と書かれています。一方でその下の運用フェーズは、チェックボックスが1つも埋まっていません。ペーパー口座への配置、3〜4週間の稼働、想定外注文が3週間発生しないことの確認——いずれも未消化です。Phase 3（実資金での段階的拡大）も当然未着手です。

補足すると、テストの中身は「正常系が通る」だけのものではありません。TODO.mdが完了として挙げる14本のE2Eテストは、いずれも壊れ方を対象にしています。重複注文の防止、キルスイッチがClaudeの判断を上書きすること、APIエラーの段階的エスカレーション、古いレポートを掴んだ場合の扱い、祝日判定、部分約定からの復帰、データベースのロック競合、プロセスがクラッシュした後の復旧——といった具合です。注文の二重送信は client_order_id を生成して防ぐ設計になっており、その挙動もテストで固定されています。

こうした失敗系の作り込みがある一方で、運用フェーズのチェックが1つも埋まっていないのは、むしろ両者が別物であることを作者が理解している証拠とも読めます。

類似OSSとの違い｜再利用したいのか、設計を読みたいのか

同じ領域の代表的なリポジトリと並べると、それぞれの役割がはっきりします。数値はいずれも2026-07-25時点の実測値です。

使い分けは明快です。手元で動かして再利用したいなら、同じ作者のMITライセンス版である claude-trading-skills の方が現実的です。スター約2,488、直近も更新されており、スキル単位で取り込めます。複数エージェントの議論の組み立て方を知りたいなら ai-hedge-fund が参考になります。こちらは当サイトでも AI Hedge Fund徹底解説｜13人の投資家AIがLangGraphで議論する教育目的シミュレータ で詳しく扱いました。

そして claude-weekly-trade-strategy の価値は、再利用ではなく設計にあります。 LLMに何を渡し、何を渡さないか。生成物をどこで機械に検証させるか。この2点を、動くコードで最後まで書き切っているリポジトリは多くありません。スター数の多寡だけを見て素通りすると、この構成はまるごと見落とすことになります。

まとめ｜題材は金融、応用先はエージェント全般

このリポジトリから持ち帰れるものは、金融とは関係ありません。エージェントに副作用のある操作をさせたい場面すべてに効く型です。メールを送る、本番にデプロイする、課金する、データを削除する——どれも「LLMに提案させ、コードで検証し、コードで実行する」に置き換えられます。許可リストを定数で持ち、逸脱幅を数値で縛り、停止条件をLLMより上位に置く。この3つは、そのまま自分のエージェントに移植できます。

同じくスキルの自動起動という切り口で実機検証した例は Claude Codeのスキル自動起動とは｜インフラ構成ショーケースを実機検証で解説 にまとめています。あわせて読むと、.claude/ 配下をどう構成すると何が起きるのかが立体的に見えてきます。

参照ソース

・tradermonty/claude-weekly-trade-strategy（公式リポジトリ・README） — ワークフロー構成・前提条件・推奨チャート構成の一次情報
・trading/layer2/system_prompt.py — Claudeに与えられたツール定義と「注文を直接実行しない」制約の原文
・trading/layer3/order_validator.py — 許可銘柄・シナリオ整合・逸脱幅の検証実装
・scripts/postflight_blog_check.py — 禁止語の正規表現と検査関数、終了コードの定義
・tradermonty/claude-trading-skills — 同作者のMITライセンス版スキル集（比較表のスター数・更新日の出典）