alpaca-trading-backtest

Trading API バックテスト

Alpaca CLI とローカルワークスペースのコードを使って、AI エージェントに特定の過去データのバックテストを実行させる場合に、このスキルを使用します。このバージョンは実行ごとの処理に最適化されています。エージェントは、確認済みの戦略に必要な、読みやすい最小限のコードを作成し、正確な成果物を保存して、結果をあなたに報告します。

このスキルは、AI エージェントを通じて実行を依頼するあなたに向けて書かれています。あなたとは、エージェントにバックテストの実行を依頼するトレーダー、開発者、研究者、またはオペレーターを指します。エージェントはあなたに直接話しかけ、前提条件を明確に言い直し、解釈上の選択をすべて明示する必要があります。

strategy idea -> formalized rules -> confirmed assumptions -> CLI data fetch -> local script -> artifacts -> report

これは、戦略が実際の市場で機能することを約束するものではありません。再現可能なリサーチワークフローです。

必須の開示事項

すべてのレポート、notes.md、report.md、ノートブック、ダッシュボード、またはエクスポートされた結果には、次の内容を含めてください。

重要な開示事項
このバックテストは、過去のデータを用いた仮想的なシミュレーションであり、実際の取引実績を示すものではありません。バックテストの結果は将来の結果を保証するものではありません。結果は、市場データの品質、データフィードの選択、コーポレートアクションの処理、手数料、スリッページ、流動性、税金、執行の前提条件、実装の詳細に左右されます。この資料はリサーチおよび教育目的のみであり、投資助言、有価証券、オプション、暗号資産、その他の金融商品の売買に関する推奨、申し出、勧誘ではありません。すべての投資にはリスクが伴い、価値が下落する可能性があります。alpaca.markets/disclosures で Alpaca の開示事項と契約をご確認ください。

ワークフローにペーパートレードが含まれる場合は、次の内容を追加してください。

ペーパートレードはシミュレーション環境です。実際の資金や証券取引は発生しません。約定の前提条件、市場インパクト、流動性、レイテンシ、データの差異、注文処理、手数料、その他の市場状況により、ペーパートレードの結果は実取引と異なる場合があります。

バックテストで Alpaca の証券取引活動手数料をモデル化する場合は、notes.md、summary.json、report.md に Alpaca の Brokerage Fee Schedule PDF へのリンクを記載してください。

https://files.alpaca.markets/disclosures/library/BrokFeeSched.pdf

PDF の改訂日、抽出日時、モデル化した手数料の分類、意図的に除外した手数料項目を記録してください。

CLI の前提条件

Alpaca CLI

エージェントは市場データへのアクセスに Alpaca CLI を使用してください。

インストールされているか確認します。

alpaca version

必要に応じて Go を使ってインストールします。

go install github.com/alpacahq/cli/cmd/alpaca@latest

macOS または Linux で Homebrew を使う場合：

brew install alpacahq/tap/cli

Go でインストールした場合は、一般的に ~/go/bin などのバイナリディレクトリが PATH に含まれていることを確認してください。

ローカル実行権限

Alpaca CLI のコマンドは、Alpaca プロファイル、環境変数、ネットワークアクセス、保存済みの成果物を利用できるローカルワークスペースで実行してください。一部のエージェント実行環境では、これを次のように表します。

required_permissions: ["all"]

エージェント環境で同等の権限モデルを使用し、CLI がローカルの認証情報や設定にアクセスして、実行成果物を書き込めるようにしてください。

接続と認証の確認

バックテストの実行前に、CLI と認証情報を確認してください。

alpaca doctor

認証に失敗した場合、エージェントは実行を中止し、利用可能なログイン／ヘルプコマンドを提示してください。

alpaca profile login --help

対話形式でペーパー環境を設定する場合：

alpaca profile login

API キーを設定する場合：

alpaca profile login --api-key

自動化では、シークレットを生成コードに書き込まずに済むため、環境変数の使用を推奨します。

export ALPACA_API_KEY=PK...
export ALPACA_SECRET_KEY=...
export ALPACA_QUIET=1

エージェントはシークレットキーを決して表示したり、ファイルにコミットしたり、レポートに含めたり、シェルの履歴に露出する方法で渡したりしてはいけません。

機械可読出力

出力をコードで解析するコマンドには --quiet を使用します。

alpaca account get --quiet
alpaca data bars --symbol SPY --start 2024-01-01 --end 2024-12-31 --timeframe 1Day --quiet

フラグとレスポンスフィールドの正確な情報源として、インストール済み CLI のヘルプとスキーマを使用してください。

alpaca --help-all
alpaca data bars --help
alpaca data bars --schema
alpaca data quotes --schema

CLI は API 仕様から生成され、変更される可能性があるため、古い例よりも、最新の --help、--schema、alpaca doctor の出力を優先してください。

必須のワークフロー

エージェントは、次のワークフローに従う必要があります。

1. 必要な入力を収集します。開始日、終了日、戦略のコンセプトまたは戦略ファイルを確認します。
2. その他の情報を収集または推定します。資産クラス、銘柄またはユニバース、時間枠、初期資金、ポジションサイジング、データフィード、調整モード、約定の前提、ベンチマークを確認します。
3. 実行時の考慮事項を確認します。注文シミュレーション、指標、配当、株式分割、手数料、スリッページ、スプレッド、市場営業時間、カレンダー処理、検証を検討します。
4. 自由形式のアイデアを、正確な数学的ルールに変換します。
5. 依頼がすでに数学的に明確である場合を除き、コードを作成する前に、形式化した解釈をあなたに提示します。
6. ワークスペースを確認し、再利用可能なデータ、過去の実行結果、既存のユーティリティを探します。
7. 自己完結型の実行フォルダーを作成します。
8. notes.md、strategy_spec.json、config.json、および読みやすい実行固有のスクリプトを作成します。
9. Alpaca CLI を通じて過去のデータを取得し、CLI の生出力を保存し、選択した市場営業時間に絞り込み、データフィンガープリントを計算します。
10. ローカルシミュレーションを実行します。
11. 成果物を作成します。
12. Teaching Five、最初と最後の取引、前提、注意事項、データフィンガープリント、成果物のパスを返します。

ワークスペースの確認

新しいコードを生成したりデータを取得したりする前に、エージェントはワークスペースを確認する必要があります。

データの再利用

次の条件に一致する過去の生データファイルまたはキャッシュ済みの正規化データを探します。

symbol
asset class
feed
adjustment mode
timeframe
start/end range
calendar filter
regular-hours or extended-hours setting

データフィンガープリントが一致する場合に限り、データを再利用します。フィンガープリントが異なる場合、エージェントはそれぞれの実行で異なる入力データが使用されているものとして扱う必要があります。

実行の系譜

今回の実行が過去の実行の派生版である場合、notes.md に変更点を記載する必要があります。

changed RSI threshold from 30/70 to 25/75
changed fill model from next_open bar proxy to quote-aware fill
changed slippage from 5 bps to 10 bps
extended date range from 2020-2024 to 2018-2025

既存のコード

ワークスペースに、戦略の要件に適合するバックテストエンジンまたは共有ユーティリティがすでにある場合、エージェントはそれを再利用してもかまいません。それ以外の場合は、実行フォルダーに読みやすい run.py を1つ作成するのがデフォルトです。

実行フォルダーと成果物の要件

このスキルでは、成果物のパスに raw/ と normalized/ を標準名として使用します。

各実行では、次のようなフォルダーを作成する必要があります。

runs/YYYY-MM-DD_symbol_strategy_timeframe/
  notes.md
  strategy_spec.json
  config.json
  run.py
  requirements.txt or pyproject.toml when needed
  raw/
    bars_SYMBOL.json
    quotes_SYMBOL.json
    trades_SYMBOL.json
    calendar.json
    corporate_actions.json
  normalized/
    bars_SYMBOL.csv
    quotes_SYMBOL.csv
  summary.json
  report.md
  trades.csv
  round_trips.csv
  equity.csv
  benchmark_equity.csv
  data_fingerprint.json
  warnings.json
  fee_source.json

notes.md

notes.md には、元の依頼、確認済みの戦略解釈、推定またはデフォルト設定したすべての前提、指標の定義、約定モデル、手数料モデル、データフィードと調整モード、配当および株式分割の扱い、ベンチマークの定義、カレンダーと市場営業時間の処理、警告と注意事項、Alpaca の開示情報と手数料体系へのリンクを含める必要があります。

その他の成果物

summary.json、strategy_spec.json、data_fingerprint.json、fee_source.json のスキーマについては、reference.md を参照してください。

コード生成のルール

実行固有の CLI バックテストでは、エージェントは再利用可能なフレームワークではなく、スクリプトを生成する必要があります。デフォルトは単一ファイルの run.py です。

監査しにくくなるような圧縮された式ではなく、読みやすいコードを使用します。

fill_price = bar_open * (1 + friction_pct)

生成するコードは、次の条件を満たす必要があります。

• 実行フォルダー内の生データファイルまたは正規化済みファイルを読み込む。
• 確認済みの戦略を正確に実装する。
• 選択した指標の定義を正確に実装する（指標の計算式を参照）。
• シグナルのタイミングと約定のタイミングを分ける。
• 確認済みの前提に従って、手数料、スリッページ、スプレッド、決済を計算する。
• 必要な成果物をすべて生成する。
• 決定的なソートとタイムゾーン処理を含める。
• 明示的に文書化されていない限り、データ取得後の隠れたネットワーク呼び出しを避ける。

デフォルトでは Python 3 を使用します。可能な場合は、標準ライブラリと pandas/numpy を優先します。依存関係を追加するのは、正確性または可読性が大幅に向上する場合に限ります。

戦略の形式化

エージェントはコードを生成する前に、アイデアを形式化する必要があります。

各ルールでは、データフィールド、トリガー、境界値を含むかどうか、指標の種類とパラメーター、ウォームアップ動作、ポジションサイジングと丸め、現金の扱い、注文種別、約定モデル、ベンチマークを指定する必要があります。

確認例：

I interpreted your strategy as:
- Symbol: SPY
- Timeframe: 1Day
- Data: Alpaca CLI bars, feed=sip, adjustment=split
- Indicator: SMA(50) and SMA(200), simple arithmetic mean of completed daily closes
- Entry: fast SMA crosses above slow SMA
- Exit: fast SMA crosses below slow SMA
- Signal timing: completed bar close
- Fill timing: next trading day's open
- Fill model: next_open bar proxy with 5 bps slippage unless quotes are available
- Sizing: invest 100% of available cash, fractional shares allowed when supported
- Benchmark: SPY buy-and-hold with same assumptions

確認後は、コードを確認済みの解釈に一致させる必要があります。

フィルモデル

確認メッセージと notes.md では、次のモデル名を使用してください。実装の詳細は フィルモデルのルール を参照してください。

• next_open（デフォルト）：バー T の終値でシグナルを判定し、バー T+1 の始値または T+1 の始値時刻の気配値で約定します。
• time_based：確定した時刻に約定します。利用可能な場合は、気配値の買値／売値を使用します。
• same_bar：明示的に要求された場合に限ります。notes.md とレポートに先読みのリスクを記載してください。
• 指値注文と逆指値注文：OHLC バーの適格性ルールが適用されます。逆指値と利確目標の両方が同じバーに触れた場合は、保守的なバー内競合ポリシーを使用してください。

レポート形式

report.md の先頭には、ベンチマークとのパフォーマンス比較を記載してください。

| | Total Return | Ann. Return | Max Drawdown | Sharpe | Final Equity |
|---|---:|---:|---:|---:|---:|
| **Strategy** | ...% | ...% | ...% | ... | $... |
| Benchmark | ...% | ...% | ...% | ... | $... |

表の後に、戦略の設定、銘柄／時間枠／フィード／調整方法、フィルモデルと摩擦、最初と最後の取引、詳細な指標、ベンチマークの説明、前提条件、データフィンガープリント、注意事項、開示ブロックを記載してください。

指標の定義については、reference.md を参照してください。

チャット内の回答基準

まず、重要な 5 項目を提示してください。

1. ベンチマークに対する総リターン
2. 最大ドローダウン
3. 取引数
4. 勝率
5. ベンチマークに対するシャープレシオ

続けて、年率リターン、プロフィットファクター、支払った手数料、最初の取引、最後の取引、適用した前提条件、データフィンガープリントの概要、成果物のパス、最も重要な注意事項を記載してください。

取引がなかった場合は、その旨を明確に伝え、ウォームアップ、シグナルなし、現金不足、データ欠損、カレンダーフィルタリングのどれが原因かを説明してください。

実行前の確認事項

実行前に、エージェントは次の各項目を解決する必要があります。

• 注文シミュレーションと約定のタイミング
• 気配値対応の約定か、バーを代理値とする約定か
• 配当の処理
• 株式分割と併合の処理
• 約定時の摩擦
• PDF から算出した取引手数料
• 市場取引時間と時間外取引の対象可否
• カレンダーに基づく判断
• ベンチマークの選択
• 先読みバイアス
• サバイバーシップバイアス
• パラメーター調整に対するアウト・オブ・サンプル検証またはウォークフォワード検証
• 複数のバリエーションを繰り返すことによる過剰適合のリスク

注文シミュレーション、配当、株式分割、手数料、カレンダー、ベンチマークについて、指定がない場合は、選択内容を notes.md に記載してください。

安全性と品質に関するガードレール

エージェントは、次のことを避ける必要があります。

• シグナルの生成に将来のデータを使用すること
• 文書化された same_bar モデルと警告なしに、同一バーで判断と約定を行うこと
• 約定に関する前提を隠すこと
• 調整済みバーと別個の株式分割調整を併用すること
• 曖昧なルールが完全に指定されているかのように扱うこと
• 実行後に生成したコードを破棄すること
• 要求されていない時間外取引のバーを含めること
• インジケーターのバリエーションを黙って置き換えること
• 始値、終値、高値、安値、VWAP、気配値由来の価格を、相互に置き換え可能な約定の代理値として扱うこと
• レポートに日次シャープレシオと記載しながら、バーごとのリターンからシャープレシオを計算すること
• 標本標準偏差（N-1）が必要な場合に、シャープレシオの計算で母標準偏差を使用すること
• 過去のバックテストの一環として、実際の注文を送信すること
• 対応していない商品への対応を主張すること。オプションには、明示的な契約選択と約定ロジックが必要です。
• 直接 HTTP 呼び出しに切り替えて Alpaca CLI を迂回すること
• ローカル認証情報とファイルシステムへのアクセスがないサンドボックスで Alpaca CLI コマンドを実行すること
• フィルモデルのルール から逸脱する約定ロジックを、逸脱の内容を notes.md に記載せずに実装すること
• シグナルトリガーに close、high、low を同じ意味で使用すること
• クロスオーバー方式と閾値方式のシグナルロジックを黙って選択すること
• 単一ファイルのスクリプトで十分な場合に、複数モジュールのエンジンを生成すること

任意のペーパー取引によるフォワード検証への引き継ぎ

過去のバックテスト後、依頼があれば、エージェントはペーパー取引によるフォワード検証パッケージを準備できます。

paper_config.json
strategy_runtime.py
risk_limits.json
alpaca_order_adapter.py
reconciliation_plan.md

これは過去のバックテストとは別のものです。明示的なリスク制限、自動化のためのクライアント注文 ID、想定されたペーパー取引の約定と実際の約定との照合を使用してください。

トラブルシューティング

command not found: alpaca
  Check PATH and Go install location, commonly ~/go/bin.

alpaca doctor reports auth failure
  Re-run alpaca profile login or set ALPACA_API_KEY and ALPACA_SECRET_KEY.

CLI output includes non-data text
  Use --quiet or set ALPACA_QUIET=1.

Parsed fields changed
  Run <command> --schema and update the parser for the current CLI response.

Rate limited
  Respect Retry-After, reduce request frequency, and use cached data where fingerprints match.

Pagination missing data
  Check next_page_token and fetch all pages.

関連資料

便利なコマンド：

alpaca version
alpaca update --check --quiet
alpaca doctor
alpaca --help-all
alpaca data bars --help
alpaca data bars --schema
alpaca data quotes --schema
alpaca calendar --help

開示情報へのリンク：

https://alpaca.markets/disclosures
https://files.alpaca.markets/disclosures/library/BrokFeeSched.pdf

CLI のデータ取得、インジケーターの計算式、手数料モデル、指標、ベンチマーク、JSON スキーマ：reference.md。

関連ファイル

• reference.md