backtest

バックテスト

JSON 戦略ファイルを起点に、バックテストツールを実行し、結果を事実に基づく記述＋ベンチマークとの比較＋仮説の反証判定として解釈します。修正が必要な場合は、調査結果を create-strategy に引き継ぎます。

このスキルは、仮説から反証に至るワークフローにおけるCLI ラッパーおよび結果解釈ガイドです。ツールは決定論的な結果を返し、このスキルはその結果が何を意味するかを説明します。結果の値を再計算したり、推定したりしないでください。

詳細ガイドは references/ に分かれています。

• 結果の解釈原則とレポート形式：references/result-interpretation.md
• ベンチマークとの比較方法：references/benchmark.md
• 時間足ごとのデフォルト期間：references/period-defaults.md
• 手動確認用の公式市場ルール資料：references/market-rules.md

指標名、インジケーター名、または戦略用語を韓国語で説明する場合は、skills/references/glossary.md を読み込んでください。

---

データルートと実行モード

作業を開始する際に、モードを特定し、{data_root} を絶対パスとして解決してください。

モード	判定方法	{data_root}（config set data-dir が実行されていない場合に使用）
clone モード	upbit-strategy-toolkit リポジトリのワークスペース／cwd で実行中	実行時の現在の作業ディレクトリ
agent skills モード（グローバル）	npx skills add ... -g でスキルがインストールされており、リポジトリが現在のワークスペースにない	実行時の現在の作業ディレクトリ
agent skills モード（プロジェクトスコープ）	npx skills add ...（-g なし）でスキルがインストールされており、リポジトリが現在のワークスペースにない	実行時の現在の作業ディレクトリ

config get data-dir が未設定を返す場合、CLI はモードにかかわらず、実行時の現在の作業ディレクトリを使用します。ユーザーが config set data-dir を実行している場合は、保存された値が使用されます。判断に迷う場合は、上記の表から推測せず、bash scripts/upbit-strategy-toolkit.sh config get data-dir で確認してください。

スラッグを使ったリクエストは {data_root}/strategies/{slug}.json として解釈してください。ラッパーには、戦略 JSON の絶対パスを必ず渡してください。

upbit-strategy-toolkit を直接実行するのではなく、このスキルのラッパーを使ってツールを呼び出してください。

bash scripts/upbit-strategy-toolkit.sh ...

ルーティング契約

• 役割：保存済みの戦略を実行し、結果を解釈します
• 前提条件／復旧：uv がない場合、ラッパーが失敗した場合、または CLI が失敗した場合は setup にルーティングします
• 次のステップ：結果の解釈後に戦略の修正が必要な場合は create-strategy を使用します
• 対象外：このスキルでは戦略を作成しません

---

トリガー

• 「この戦略のバックテストを実行して」
• 「{slug} を検証して」
• 「バックテスト結果を確認して」
• 仮説／反証基準を含むペイロードがある create-strategy からの引き継ぎ直後

禁止事項

• 結果の値を再計算したり推定したりしないでください - ツールの標準出力をそのまま引用してください。トータルリターン、MDD、シャープレシオ、CAGRを再計算または概算してはいけません。結果再計算ガードレールを参照してください。
• 良し悪しを判断しないでください - 「リターンは+12％、ベンチマークの+8％を+4％ポイント上回っています」のように、事実のみを述べてください。「パフォーマンスは良好です」とは言わないでください。結果判断ガードレールを参照してください。
• 戦略、資産、取引のタイミング、取引価格、目標リターン、保有期間を推奨しないでください - 出力は事実に基づく比較、仮説の判定、修正候補のみにとどめてください。
• ツールの制限をユーザーに隠さないでください - スリッページ、板の流動性、部分約定は反映されません。この点はレポート内で一度だけ言及してください。
• ライブ取引に接続しないでください - ライブ取引ガードレールを参照してください。
• 毎回開始日と終了日を尋ねないでください - まずreferences/period-defaults.mdにある期間別のデフォルトを適用し、ユーザーが明示的に期間を指定した場合にのみ上書きしてください。
• 期間エラーが発生しても、ユーザーが指定した日付を変更しないでください - ユーザーが開始日と終了日を明示し、ツールが期間エラーを返した場合は、エラーを報告し、異なる日付で実行する前にユーザーに確認してください。

---

投資推奨ガードレール

ユーザーから、どの戦略が優れているか、より利益が出るか、選ぶ価値があるか、結果から買う／売る／保有するべきといえるか、いつ取引すべきか、いくらで取引すべきか、どのリターンを目標にすべきか、どれくらいの期間保有すべきかを尋ねられた場合、その推奨自体には回答しないでください。

回答の最後に、## Required Noticesにある投資推奨に関する通知を記載してください。ユーザーのメッセージが韓国語の場合は韓国語版を、それ以外の場合は英語版を使用してください。

そのうえで、回答は次の内容に限定してください。

• ツール出力に基づく指標の事実に即した比較
• 利用可能な場合は仮説の反証状況
• サンプル数、スリッページ、流動性、手数料などの制限
• 別のバックテストの実行や、create-strategyでユーザー指定のルールを修正するなど、裏付けのある次のステップ

事実に基づく比較を、どの戦略を使うべきかという推奨に変えてはいけません。

---

結果再計算ガードレール

ユーザーが報告済みの指標の再計算、再導出、調整（たとえば、手数料の除外、スリッページの適用、別の単位への変換）を求めた場合、計算が単純に見えても、計算を行わないでください。これはキーワードだけで判断するルールではなく、意図に基づくルールとして、あらゆる言語で適用してください。

計算を断り、その理由を伝えてください。バックテスト結果の値はツールの報告どおりに解釈し、ツールキットの外で再計算または推定はしません。指標の値はすべて、ツールキットのCLIによるバックテスト実行からのみ取得する必要があります。そのため、回答は異なる実行引数（fee_rate、期間など）で新しいバックテストを実行することに限定し、既存の結果に対する手計算は決して行わないでください。

---

結果判断ガードレール

ユーザーがバックテスト結果の良し悪し、満足度、信頼に値するかどうかを評価的な表現で尋ねた場合、形容詞による判断を回答しないでください。これはキーワードだけで判断するルールではなく、意図に基づくルールとして、あらゆる言語で適用してください。

質問が買う／売る／保有するべきか、またはどの戦略がより利益をもたらすかという内容に移った場合は、投資推奨ガードレールを適用してください。両方が当てはまる場合は、こちらのガードレールを優先します。

形容詞による判断を断り、その判断はユーザー自身が行うものだと伝えてください。そのうえで、許容される評価範囲に話を戻してください。対象となるのは、論理的一貫性、仮説の反証、過剰適合のリスク、リスク管理上の懸念、データやサンプルに関する留意点です。結論ではなく、根拠の確認として提示してください。

---

ワークフロー

市場／取引所の不一致への対応

ユーザーが戦略ファイルと異なる市場または取引所をリクエストした場合、一時ファイルで回避しないでください。 まず create-strategy スキルを通じて戦略を更新してください。

AskUserQuestion ツールを使って、ユーザーに選択肢を提示します。

Strategy file market: KRW-BTC
Requested market:     KRW-ETH  <- mismatch detected

-> AskUserQuestion tool call:
  question: "The strategy file market (KRW-BTC) differs from the requested market (KRW-ETH). What should I do?"
  header: "Market mismatch"
  options:
    - Update existing file: change {slug}.json market to KRW-ETH
    - Save as new file: save as {slug}-eth.json
    - Cancel: stop the backtest
  (The Other option can accept free-form input)

時間足の不一致への対応

バックテストを実行する前に、戦略 JSON を読み込んで timeframe フィールドを確認します。 ユーザーが戦略ファイルの timeframe と異なる時間足をリクエストした場合、不一致の時間足では実行しないでください。 まず create-strategy スキルを通じて戦略を更新してください。

AskUserQuestion ツールを使って、ユーザーに選択肢（create-strategy で新しい戦略ファイルを作成する、既存の時間足を使用する、またはキャンセル）を提示します。

「新しい戦略ファイルを作成」が選ばれた場合は、slug と新しい時間足を指定して create-strategy に引き継ぎます。 「既存の時間足を使用」が選ばれた場合は、戦略ファイルの時間足を使って STEP 2 に進みます。

STEP 1. 入力の解析 - 引き継ぎか直接呼び出しか

該当するモードを特定します。

モード A：create-strategy から引き継いだ直後

ペイロードには次の内容が含まれます。

slug: {slug}
hypothesis: {one-sentence hypothesis}
falsification_criterion: {falsification criterion - for example, "win rate < 40% or MDD > 25%"}
notes: {free-form notes such as period-adjustment reason, optional}

-> 仮説／反証基準は提示されたとおりに使用します。期間は指定しないでください - STEP 2 の時間足別デフォルトで決定します。

モード B：ユーザーからの直接呼び出し

hypothesis／falsification_criterion はありません。期間は STEP 2 で決定します。

提示形式：

backtest

Strategy: {slug}.json / {market} / {timeframe}
Period: {start} ~ {end} (timeframe={tf} default or user-specified)
Hypothesis: {show only in Mode A}
Falsification criterion: {show only in Mode A}

Proceeding.

STEP 2. 期間の決定

バックテスト期間は UTC 基準です。YYYY-MM-DD 形式の日付文字列をそのまま CLI に渡すと、ツールは UTC 00:00 として解釈します。ユーザーが「KST 2024-01-01」のようにタイムゾーンを指定した場合にのみ UTC に変換します（例：KST 2024-01-01 00:00 -> UTC 2023-12-31）。

優先度	参照元
1	ユーザーが明示した開始日／終了日
2	時間足別デフォルト - references/period-defaults.md

期間の選択を行うのはバックテストスキルのみです。 create-strategy は別途推奨期間を渡しません。渡した場合、ここで定義されている時間足別デフォルトと競合する可能性があります。

時間足別デフォルトの概要（全表は references を参照）：

• 1d -> 直近 1 年
• 1h -> 直近 3 か月
• 1m -> 直近 1 週間
• その他の時間足は、約 250 本のローソク足を基準に算出します

end_date のデフォルトは昨日（今日 - 1、UTC）です。仕様上、過去データサービスは当日のデータを提供しないためです。references/period-defaults.md を参照してください。リクエストが大量のローソク足を意味する場合（例：ユーザーが指定した 1m x 1 year）、呼び出し前に一度警告します。

STEP 3. run_backtest の呼び出し + CSV の保存

バックテストツールは CSV を自動的に保存します。スキル側で別途保存する必要はありません。CSV は {data_root}/reports/{slug}-{YYYYMMDD_HHMMSS}.csv に自動保存されます。

STRATEGY_PATH="{data_root}/strategies/{slug}.json"
bash scripts/upbit-strategy-toolkit.sh backtest run "$STRATEGY_PATH" --start {start_date} --end {end_date}

上書きが必要な場合はオプションを追加します。

• --capital FLOAT：初期資金（省略時は建値通貨に適した値がデフォルトで適用されます：KRW 1,000,000／USDT 1,000／BTC 0.01）
• --fee-rate FLOAT：手数料率（省略時は市場ルールに基づく取引所／市場のデフォルト値が自動適用されます）
• --no-verbose：標準出力のサマリー、CSV パス、取引のハイライトを非表示にします（デフォルト：詳細表示）
• --force-refresh：キャッシュを無視し、API からローソク足を再取得します

投資注意事項の処理

最初の試行は、標準入力をパイプで渡さずに必ず実行します。CLI は投資注意が設定された市場に対して対話形式で確認を求めますが、エージェント環境では標準入力にデータがないため、プロンプトは直ちに EOF に達し、実行は終了コード 1 で自動キャンセルされます。

次の両方の条件を確認して、投資注意を検出します。

• 終了コードが 1
• stdout に "investment caution" が含まれている

投資注意が検出された場合 — 再実行する前に一時停止してユーザーに確認します。

⚠️ {market} は現在、投資注意の対象です。 バックテストはキャンセルされました。このまま続行しますか？

• はい → 同じコマンドを、標準入力に y をパイプで渡して再実行し（例：echo y | bash scripts/upbit-strategy-toolkit.sh backtest run ...）、STEP 4 に進みます
• いいえ → 停止し、バックテストがキャンセルされたことをユーザーに伝えます

終了コードが 1 でも stdout に "investment caution" が含まれていない場合は、通常のエラーとして扱います（stderr をユーザーに伝え、再実行しません）。ローソク足データに関するエラーケースについては、以下の期間がサポートされていない場合の処理と取引所／時間足がサポートされていない場合の処理を参照してください。

投資注意を確認したうえでバックテストを続行した場合（標準入力に y をパイプで渡して再実行した場合）は、レポートに必ず次の注意書きを含めます。

⚠️ {market} は現在、投資注意の対象です。

期間がサポートされていない場合の処理

次の条件を確認して検出します。

• 終了コードが 1
• stderr に "Backtesting is not available for the selected period" が含まれている

指定された日付範囲にはローソク足データがありません。ユーザーが日付を明示的に指定した場合は、ツールのエラーをそのまま引用し、新しい期間を尋ねます。

Backtesting is not available for the selected period.
Please provide a different period. You can check available data at: https://www.upbit.com/historical_data/download?prefix=candle

明示的な確認なしに、別の日付で再実行してはいけません。また、サポート対象となる最も古い日付を探してはいけません。

取引所／時間足がサポートされていない場合の処理

次の条件を確認して検出します。

• 終了コードが 1
• stderr に "Historical candle data" が含まれている

この戦略の取引所または時間足は恒久的にサポートされていません（日付範囲を変えても機能しません）。create-strategy に切り替え、バックテスト可能な時間足（1M 以下）または kr 取引所を選択します。

実行結果

stdout に出力される項目（値はそのまま引用します）。

Period      YYYY-MM-DD ~ YYYY-MM-DD (trading bars: N, warmup bars: N)
Benchmark   +N.NN%
Total Return +N.NN%
CAGR        +N.NN%
MDD         N.NN%
Sharpe      N.NN  (Rf=0, portfolio / full equity curve)
Sharpe      N.NN  (Rf=0, trades / position holding periods only)
* Sharpe ratio is unreliable for 1m/1s: annualization amplifies microstructure noise.  ← 1m/1s TF일 때만 출력
Trades      N  Win Rate N% (before fees)
Profit Factor  N.NN (before fees)
SL N / TP N / sell N / final_bar N
Total Fees  N

実際のデータ範囲が指定された期間と異なる場合、この注意書きは常に出力されます（verbose モード以外では、免責事項の前に出力されます）。英語版／韓国語版のテキストについては、## データ利用可能性に関する通知を参照してください。

0 executed trades の場合、stdout ではツールが提供する未定義マーカーがそのまま使われます。

Trades      0  Win Rate N/A (0 executed trades) (before fees)
Profit Factor  N/A (0 executed trades) (before fees)

STEP 4. 結果の解釈と双方向の引き継ぎ

レポートの形式（詳細はreferences/result-interpretation.mdを参照）。

a) 概要 - stdout をそのまま引用し、CSV パスと（モード A の場合）仮説／反証基準を再掲します。

b) 取引の注目点 - 最初のエントリー／利益が最大の取引／損失が最大の取引／exit_reason の分布（SL／TP／sell／final_bar）から注目すべき点を記載します。CSV の # section: trades から抽出します。

c) コメント（1～2 行、事実に基づく記述） - 値同士の関係のみを記載します。例はreferences/result-interpretation.mdを参照してください。

「MDD は総リターンを上回っています。各ポジションのストップロスは上限が設定されていましたが、ポジションをまたいでドローダウンが蓄積しました。」 「N 件の取引のうち、SL は N 件、TP は N 件です。利確よりも損切りが多く発生しました。」

d) 仮説の反証判定 - モード A の場合のみ。各 falsification_criterion の項目を結果の値と直接比較し、反証／維持／判定不能を示します。

反証基準：「勝率 < 40% または MDD > 25%」 結果：勝率 N%／MDD N.NN% -> [反証／維持]：{どの項目が、どの基準を満たしたか、または満たさなかったか}

e) 次回の改訂候補と引き継ぎ用ペイロード - create-strategy に引き継ぐ場合は、次の形式を使用します。

slug: {original slug}
result_summary:
  total_return_pct: {stdout exactly}
  benchmark_pct: {stdout exactly}
  win_rate_pct: {stdout exactly}
  mdd_pct: {stdout exactly}
  trades: {N}
  exit_reasons: SL N / TP N / sell N / final_bar N
benchmark_comparison: {+/-N.NN%p vs benchmark - see references/benchmark.md for detailed interpretation}
hypothesis_status: {falsified / retained / inconclusive}
suggested_next_directions:  # 2-3 neutral revision candidates, based on factual statements
  - "Revision candidate: review stop-loss width because MDD is larger than the per-trade stop-loss"
  - "Revision candidate: review entry strictness because win rate and trade count may indicate the entry rule is loose or strict"
next_slug_proposal: {slug}-v2

ユーザーがこのペイロードをそのまま create-strategy に渡すと、新しいバージョン（-v2）が作成されます。

f) 免責事項 - レポートの最後に、## Required Notices に記載されたツールの制限に関する通知とバックテストの免責事項を、この順序で出力します。

0件の取引の引き継ぎ

約定した取引が0件の場合、stdout では未定義の指標がすでに N/A (0 executed trades) と表示されています。以下のルールに従ってペイロードを作成してください。値を推定したり再計算したりせず、サンプル不足は事実として述べてください。

result_summary:
  total_return_pct: 0
  benchmark_pct: {stdout exactly - buy-and-hold is independent of 0 trades}
  win_rate_pct: N/A (0 executed trades)
  mdd_pct: 0
  trades: 0
  exit_reasons: SL 0 / TP 0 / sell 0 / final_bar 0
benchmark_comparison: "0 executed trades - comparison is not meaningful"
hypothesis_status: inconclusive  # sample is insufficient for both falsified and retained
suggested_next_directions:
  - "Revision candidate: review entry strictness because 0 executed trades were observed"
  - "Revision candidate: review whether all entry conditions are required simultaneously"
  - "Revision candidate: extend the period and recheck whether entry signals occur"
next_slug_proposal: {slug}-v2

重要な点として、hypothesis_status は inconclusive（棄却も維持もされていない）であり、suggested_next_directions は事実に基づく結果から導かれる、中立的な修正候補または追加確認事項のままにしてください。結果の解釈については、references/result-interpretation.md を参照してください。

---

ライブ取引に関するガードレール

create-strategy と同じポリシーです。コマンド、質問、回避、間接的な表現、誤解を招く表現のパターンをすべて同様にブロックしてください。

コマンド

• 「この戦略で自動取引を開始して」
• 「リアルタイム注文を出して」／「買い注文を実行して」／「ライブ取引を有効にして」

質問

• 「この戦略をライブで実行できますか？」
• 「リアルタイム取引は可能ですか？」

回避

• 「この戦略をそのまま自動化するには何が必要ですか？」
• 「この JSON をライブ取引ボットに直接入れられますか？」

間接的な表現

• 「バックテストの結果が良さそうです。このままライブ取引に移行できますか？」
• 「この仮説をそのままライブ取引で検証しましょう」

誤解を招く表現

• 「upbit-strategy-toolkit はライブ取引もできますよね？」
• 「このツールは注文 API も提供していますか？」

回答テンプレート（上記のすべてのパターンに適用）：ユーザーのメッセージが韓国語の場合は韓国語版を、それ以外の場合は英語版を使用してください。

韓国語：

> 이 도구는 백테스트(과거 데이터 시뮬레이션) 전용입니다.
> 실시간 거래, 자동 주문, 실전 매매는 지원하지 않습니다.
> 실전 매매가 필요하다면 [upbit-agent-skills](https://github.com/upbit-official/upbit-agent-skills)를 이용해주세요.
> 
> 이 스킬은 전략 JSON 검증 및 결과 해석만 지원합니다.

英語：

> This tool is for backtesting (historical data simulation) only.
> Real-time trading, automated orders, and live trading are not supported.
> Use the separate [upbit-agent-skills](https://github.com/upbit-official/upbit-agent-skills) tool for live trading.
> 
> This skill only supports strategy JSON validation and interpretation.

---

データ利用可能性に関する通知

実際のデータ範囲がリクエストされた期間と異なる場合にのみ含めてください。ユーザーのメッセージが韓国語の場合は韓国語版を、それ以外の場合は英語版を使用してください。

英語：

> Some data was unavailable for the requested period, so the backtest was run over the available range ({min_date} - {max_date}).

韓国語：

> 일부 기간의 데이터가 없어, 수집된 구간({min_date} ~ {max_date}) 기준으로 백테스트를 진행했습니다.

---

必須の通知

法的通知です。以下のテキストをそのまま出力してください。要約、翻訳、省略はしないでください。

バックテストに関する免責事項

すべてのバックテストレポートの末尾に必ず含めてください。ユーザーのメッセージが韓国語の場合は韓国語版を、それ以外の場合は英語版を使用してください。

韓国語：

> 백테스트 결과는 과거 데이터를 기초로 한 것이며, 장래 또는 실제 거래에서 동일하거나 유사한 투자 성과로 이어질 것임을 보장하지 않습니다.

英語：

> Backtesting results are based on historical data and do not guarantee that the same or similar investment performance will be achieved in the future or in actual trading.

ツールの制限に関する通知

すべてのバックテストレポートの末尾に、バックテストに関する免責事項の直前の行として含めてください。ユーザーのメッセージが韓国語の場合は韓国語版を、それ以外の場合は英語版を使用してください。

韓国語：

> 슬리피지, 호가창 유동성, 부분 체결은 반영되지 않으며 다음 캔들 시가에 전량 체결로 가정합니다.

英語：

> Slippage, order book liquidity, and partial fills are not reflected. The tool assumes full execution at the next candle open.

投資推奨に関する通知

ユーザーが投資推奨を求めた場合、回答の末尾に含めてください。ユーザーのメッセージが韓国語の場合は韓国語版を、それ以外の場合は英語版を使用してください。

韓国語：

> Upbit Strategy Toolkit은 어떠한 경우에도 특정 종목, 거래 시점, 투자 방식, 투자 전략 등을 추천·권유하지 않습니다. 생성되는 응답은 사용자가 이용 중인 AI 모델이 입력 내용과 도구 실행 결과를 바탕으로 생성한 것으로, 거래·투자 행위와 관련된 모든 책임은 이용자에게 귀속됩니다.

英語：

> Upbit Strategy Toolkit does not, under any circumstances, recommend, advise on, or solicit the purchase, sale, timing, method, or strategy of any specific asset or investment. Any responses are generated by the AI model based on the user's inputs and tool executions. All responsibility for trading and investment activities conducted through User AI lies with the user.

実行ルールの概要

• stdout の値を再計算したり推定したりしないでください。正確に引用してください。結果再計算のガードレールを参照してください
• 良し悪しを判断せず、事実のみを述べてください。結果判断のガードレールを参照してください
• ベンチマーク比較では、ツールの stdout にある Benchmark の値を使用してください。別途計算は行いません。詳しい解釈についてはreferences/benchmark.mdを参照してください
• バックテストツールは CSV を {data_root}/reports/{slug}-{ts}.csv に自動保存します。スキル側で別途保存する必要はありません
• 時間足ごとのデフォルト期間を適用してください。references/period-defaults.md。毎回ユーザーに尋ねないでください
• 仮説の反証に関する判断を述べるのは、Mode A（引き継ぎ）の場合のみです。Mode B では事実の記述にとどめてください
• 戦略の修正や新バージョンのリクエストは create-strategy に引き継いでください。引き継ぎペイロード形式を使用してください
• ライブ取引は拒否し、upbit-agent-skillsを案内してください
• すべてのバックテストレポートで、必ずバックテストに関する免責事項をユーザーに提示してください
• 投資に関する注意事項を確認したうえでバックテストを実行する場合は、レポートに必ず ⚠️ 注意書きを含めてください
• 期間エラーが発生しても、ユーザー指定の日付を変更しないでください。stderr に出力されたエラーをそのまま報告し、新しい期間を提示するようユーザーに依頼してください。または、時間足／取引所がバックテストに対応していない場合は、その恒久的な制限について説明してください
• 実行前に、戦略ファイルの timeframe を確認してください。ユーザーのリクエストと異なる場合は、create-strategy で新しい戦略ファイルを作成する、既存の時間足を使用する、またはキャンセルする、という選択肢を提示し、時間足が一致しない状態では実行しないでください