futures-position-sizer

先物ポジションサイザー

概要

Shapiro パイプラインのステップ 4 です。方向、エントリー価格、損切り価格を、口座のリスク予算と確認済みの契約仕様（乗数、ティックサイズ、ティック値）に基づいて契約数に変換します。これは position-sizer とは別の新しいスキルです。先物契約はレバレッジがかかった乗数ベースの商品で、ポイントあたりの金額が大きく異なります（ES では $0.25 の値動きが $12.50、NQ では $5.00、ZB では $31.25 です）。先物に株式の株数サイザーを流用すると、誤ったポジションサイズが気付かれないまま算出されます。

取引のサイズを決める方法は 2 つあります。

• モード A（明示指定）：--symbol --direction --entry --stop を直接指定します。
• モード B（ゲートから引き継ぎ）：--gate-json <contrarian-setup-gate report> --entry を指定します。方向と損切り価格（ゲートの invalidation_level）は、ゲートの READY_FOR_PLAN レポートから取得します。サイザーはゲートが READY と確認していないセットアップのサイズを決めることはなく、--gate-json と同時に明示的な --direction／--stop を指定することもできません（ゲートが指定されている場合は、ゲートが正となります）。

どちらのモードでも --entry は必ず必要です。このスキルもゲートもエントリー価格を算出することはありません。価格はオペレーターが指定します。

使用するタイミング

• contrarian-setup-gate が READY_FOR_PLAN に到達し、確認済みの方向と損切り価格に基づいて契約数を算出する必要がある場合
• ユーザーが「ES／NQ／GC／CL／…を何契約取引すべきですか？」と尋ねた場合
• ユーザーにエントリー価格と損切り価格が決まっている先物取引のアイデアがあり、リスクベースでサイズを決めたい場合
• サイズ算出前にシンボルの確認済み契約仕様（乗数／ティックサイズ／ティック値）を確認したい場合（--list-specs）

前提条件

• Python 3.9 以降。標準ライブラリのみを使用し、API キーは不要で、完全にオフラインで動作します
• 方向、エントリー価格、損切り価格（モード A）、または setup_status: READY_FOR_PLAN を含む contrarian-setup-gate の JSON レポート（モード B）
• 確認済み 23 市場のコアテーブルにないシンボルの場合：乗数、ティックサイズ、建値通貨の 3 つすべてをまとめて指定します

ワークフロー

ステップ 1：ポジションサイズを算出する

モード A -- 明示指定：

python3 skills/futures-position-sizer/scripts/futures_position_sizer.py \
  --symbol ES --direction LONG --entry 5000.25 --stop 4980.00 \
  --account-size 100000 --risk-pct 1.0 \
  --output-dir reports/ --format both

モード B -- ゲートから引き継ぎ：

python3 skills/futures-position-sizer/scripts/futures_position_sizer.py \
  --gate-json reports/contrarian_setup_gate_B6_2026-07-15.json \
  --entry 1.3400 \
  --account-size 100000 --risk-pct 1.0 \
  --output-dir reports/ --format both

モード B では --symbol を省略できます。ゲートレポートから取得されます。両方を指定する場合は一致している必要があります。一致しない場合は gate_symbol_mismatch になります。--gate-json と同時に --direction／--stop を指定すると拒否されます（使用方法エラー、終了コード 2）。どちらか一方のモードだけを指定し、両方を指定しないでください。

ステップ 2：結果を確認する

sizing_status	意味
SIZED	contracts が 1 以上です。total_risk_usd／risk_pct_of_account は実際に取るリスクを示します
NO_TRADE	クラッシュを意味することはありません。常に no_trade_reason が含まれます。理由については、以下の理由一覧を参照してください

risk_below_one_contract による NO_TRADE 結果でも、リスク計算の全項目（契約あたりのリスク、リスク予算、損切り幅）が表示されます。このリスク率と損切り幅では、口座の資金で 1 契約も購入できないということです。より小さな契約（たとえばマイクロ）を検討するか、既存のリスクポリシーの範囲内でリスク率を慎重に見直すか、取引を見送ってください。損切り価格はセットアップで定義された無効化レベルに維持してください。損切り幅を広げると契約あたりのリスクが増え、購入可能性がさらに低くなります。予算に合わせるためだけに損切り幅を狭めないでください。

より小さな契約を使う場合は、その契約固有のシンボルと確認済み仕様を使用してください。コアテーブルにない場合は、--multiplier、--tick-size、--contract-currency をまとめて指定します（建値が USD 以外の場合は --fx-rate も指定します）。既存シンボルの乗数を小さくして、マイクロ契約の代わりにしないでください。モード B では、同じ小型契約シンボルに対する READY_FOR_PLAN ゲートを使用します。シンボルチェックを回避するために、元のゲートのシンボル名を変更しないでください。

ステップ 3：警告を確認する

warnings（トップレベルのリスト）はサイズ算出を妨げません。監査で確認すべき条件を示します。risk_pct_above_2 はリスクが 2% のガイドラインを超えていることを、off_tick_grid_entry／off_tick_grid_stop は債券以外のシンボルの価格がティックグリッドに正確に沿っていないことを示します。ミッドクオートでは正当な場合もありますが、再確認する価値があります。

Step 4: 検証済み契約仕様テーブルを確認する

python3 skills/futures-position-sizer/scripts/futures_position_sizer.py --list-specs

公式取引所の契約仕様ページを情報源とする、23市場のコアテーブル全体（倍率、ティックサイズ、ティック価値、通貨、取引所）を出力します。各行の出典URLと検証日は、references/futures-contract-specs.md を参照してください。

実例：債券のグリッド外価格ガード（32分の1から小数へ）

債券／ノート先物（ZT、ZF、ZN、ZB）はポイントの分数（32分の1、または32分の1の32分の1）で価格を提示し、一般にアポストロフィを使って表記します。110'16 は 110 + 16/32 = 110.50 を意味します。代わりに 110.16 と入力し、アポストロフィの後の数字を小数点以下のセントとして読むのは、よくある、気づきにくい誤った金額計算です。110.16 はそもそも ZB のティックグリッド（0.03125 = 1/32）上にありません。

# WRONG -- 110.16 is not on the 1/32 grid; this is almost certainly a
# mistyped "110'16" (which means 110.50). Exits 2, no report written:
python3 skills/futures-position-sizer/scripts/futures_position_sizer.py \
  --symbol ZB --direction LONG --entry 110.16 --stop 108.00 \
  --account-size 100000 --risk-pct 1.0

# CORRECT -- decimal points, not the raw 32nds digits:
python3 skills/futures-position-sizer/scripts/futures_position_sizer.py \
  --symbol ZB --direction LONG --entry 110.50 --stop 108.00 \
  --account-size 100000 --risk-pct 1.0

テーブル内のそれ以外のすべての銘柄は、通常の小数ポイントで価格を提示します。そこでグリッド外の価格（たとえば中間気配値）は、ソフトな off_tick_grid_* 警告にとどまり、拒否されることはありません。

出力仕様

--format json|both の場合、--output-dir に futures_position_size_<SYMBOL>_<as-of>.json を書き込みます。--format text|both の場合、整形済みの概要を標準出力に表示します。--as-of のデフォルトは今日です（これはオペレーターの時点でのポジションサイズ計算ツールであり、バックテスト用ツールではありません）。

schema_version: "1.0"
symbol: ES
direction: LONG
sizing_status: SIZED | NO_TRADE
no_trade_reason: null | risk_below_one_contract | gate_not_ready | gate_symbol_mismatch | ...
entry: 5000.25
stop: 4980.00
stop_distance_points: 20.25
stop_distance_ticks: 81
contract_spec: {multiplier: 50, tick_size: 0.25, tick_value: 12.5, currency: USD, source: cme, verified: "2026-07-17"}
risk_per_contract_usd: 1012.50
risk_budget_usd: 2000.00
contracts: 1
total_risk_usd: 1012.50
risk_pct_of_account: 1.01
max_contracts_cap_applied: false
fx_rate_used: 1.0
margin_note: "Exchange margin requirements are broker/time-dependent and NOT computed here; verify initial/maintenance margin with your broker."
gate: {report_path, setup_status, gate_confidence, warnings}   # mode B only
warnings: []
run_context: {symbol, as_of, schema_version, skill}

ガードレール

1. 明示的なストップなしにポジションサイズを計算することはありません。 モード A では --stop が必須です。モード B では、ゲート自体が有効な invalidation_level とともに READY_FOR_PLAN を報告するまで、サイズ計算を拒否します（gate_not_ready）。
2. 切り捨て、切り上げなし――イプシロン不要の正確な計算です。 contracts = floor(risk_budget / risk_per_contract) は、厳密な有理数演算（浮動小数点除算ではなく、Python の Fraction）で計算されるため、contracts * risk_per_contract <= risk_budget が計算の仕組み上必ず成り立ちます。イプシロンによる調整も、浮動小数点表現に起因する境界ケースもなく、予算を超えるリスクもありません。また、算出された数量が経済的にあり得ない場合（正規化数スケールの倍率を上書きするなど、異常な入力の場合）も、明確に拒否されます。契約数がゼロになるのは、正当なフェイルクローズの NO_TRADE 結果であり、エラーではありません。
3. 不正な値を入力した人に応じて、2種類のフェイルクローズを使い分けます。 オペレーターに起因する問題（--entry に対して反対側にある明示的な --stop、1ティックより近いストップ、ティックグリッドから外れた債券価格の入力）は使用方法のエラーです。終了コード 2 で終了し、レポートは書き込みません。信頼されていないゲートレポートファイルに由来する値（モード B のストップ）で同じ種類の問題が発生した場合は、代わりにフェイルクローズの NO_TRADE 結果になります。終了コード 0 で終了し、理由を記載したレポートを書き込みます。このパイプラインのほかのすべてのスキルと同様、不正または未準備のゲートファイルでクラッシュすることはありません。
4. 債券ファミリーのグリッド外価格は警告ではなく、ハードエラーとして拒否されます。 ZT／ZF／ZN／ZB は32分の1／64分の1の表記で価格を提示します。ティックグリッドに合わない価格は、ほぼ確実に表記の入力ミスであり、そのままサイズ計算すると誤った金額計算が気づかれないまま発生します。それ以外のすべての銘柄では警告にとどまります。
5. 証拠金は計算しません。 margin_note は固定の注意喚起であり、古くなることはありません。証拠金要件はブローカーと時期によって異なるため、このスキルでは推定しません。
6. 通貨を考慮します。 コアテーブルのすべての銘柄は USD 建てです（テーブル全体を対象とする単体テストで確認済み）。契約サイズが外貨建て（たとえば B6 は GBP 62,500）であっても、取引および決済は USD で行われる CME FX 先物も含みます。USD 以外の通貨建ての銘柄（--contract-currency による上書き）は、明示的な --fx-rate が必要です。暗黙のデフォルト値はありません。
7. 投資助言ではありません。 このスキルは、オペレーターが指定した入力、またはゲートで確認された入力に基づいてリスクベースの計算を行います。取引、方向性、エントリーを推奨するものではありません。

リソース

• scripts/futures_position_sizer.py -- CLI：引数の解析、強化された gate-json の読み込み（読み取り不可／parse_error。RecursionError／non_finite はファイル全体を反復スキャンして検出）、レポートの生成
• scripts/futures_sizing.py -- 純粋なサイジングコア：数値バリデーター、検証済みの23市場の契約仕様テーブル、リスク計算、切り捨てアルゴリズム、ティックグリッドのガード、ゲートレポートの形式の正規化
• references/futures-contract-specs.md -- 行ごとの公式ソース URL と検証日を記載した、検証済みの契約仕様テーブル
• references/sizing-methodology.md -- 数式、厳密な有理数による切り捨てアルゴリズムの根拠、フェイルクローズ方式の終了コード規約、計算例（ES のロング、ゲート経由の B6 のショート）