blitz-create-script

Blitz 作成スクリプト

GTM ブリーフから、公式 Blitz SDK （blitz-api-py／blitz-api-js）を使用し、最適なパッケージマネージャーでインストールして、 API キーの安全性、基本的なエラー処理、正しいページネーションを備えた実行可能な Blitz スクリプトを作成します。

SDK がページネーション、エンドポイントごとのクライアント側レート制限、429／5xx の再試行を処理します。 生の fetch／requests は絶対に出力しないでください。SDK が解消するために存在する問題がすべて再発します。

クイックスタート

./gtm-brief.yaml を読み込む（またはユーザーに貼り付けてもらうか、先に blitz-gtm-brainstorm を実行する）。その後、以下の手順に沿って作業し、実行可能なスクリプトと .env を出力します。

以下の scripts/ と references/ のパスは、このスキル自体のディレクトリからの相対パスです。ヘルパーはそこから実行してください（例：bash <skill-dir>/scripts/detect_pm.sh）。ユーザーのプロジェクトルートから実行しないでください。

ワークフロー

1. ブリーフを読み込みます。 ./gtm-brief.yaml があれば読み取ります。なければユーザーに貼り付けてもらい、それも難しければ短い聞き取りで最低限の情報（エンドポイント、フィルター、エンリッチメント、出力、言語）を確認します。 スキーマ：../blitz-gtm-brainstorm/references/gtm-brief-schema.md。

2. 列挙値の検証を確認します（ブリーフで使用されるすべての列挙値が対象）。 ブリーフでカテゴリ列挙値を使用していて、enums_verified が true でない場合は、処理を止めてユーザーに blitz-gtm-brainstorm を案内します（または、その scripts/pull_enums.sh で今すぐ検証します）。大文字と小文字を区別する列挙値に誤字があってもエラーにならず、結果が何も返りません。キーワードのみのブリーフには、この確認は不要です。（件数が 少ないもののゼロではない 場合は、情報が失われる列挙値によってタグ付きレコードだけに絞り込まれている可能性があります。キーワードを軸にしてください： ../blitz-gtm-brainstorm/references/strategy.md。）

3. パッケージマネージャーを検出します。 bash scripts/detect_pm.sh <python|typescript|javascript> → Python：uv → poetry → pip（＋venv）。JS／TS：bun → pnpm → yarn → npm。run コマンドはブリーフの language に従います。typescript は bun／tsx で実行（script.ts）、javascript は bun／node で実行（script.mjs）します。ブリーフの language をそのまま渡してください。JS のブリーフに TypeScript を強制しないでください。

4. SDK をインストールして検証します。 インストール（uv add blitz-api-py／bun add blitz-api-js／pip／npm）した後、bash scripts/verify_sdk.sh <python|typescript|javascript> を実行します。インストールまたはインポートに失敗した場合は、正確なエラーとインストールコマンドを表示して、処理を止めてください。生の HTTP 通信に切り替えてはいけません。インストール失敗は環境を修正すべき合図であり、クライアントを手作業で実装する理由ではありません。

5. ブリーフの language で、references/script-templates.md をもとにスクリプトを生成します。python（script.py）、typescript（script.ts）、または javascript（型注釈を除いた同じテンプレートの script.mjs）を使用します。ユーザーの選択に従い、javascript のブリーフに TypeScript を出力しないでください。

   • volume.exceeds_ceiling: false → 単一母集団テンプレート（SDK が自動的にページネーションを処理します）。
   • volume.exceeds_ceiling: true → 分割テンプレート：partition_plan のセグメントをループし、各セグメントの全ページを収集して統合し、output.dedupe_key で重複を除去します。 ブリーフのフィルターを SDK 呼び出しにそのまま反映します。メソッドの一覧とクライアント設定： references/sdk-reference.md。

6. 安全性とエラー処理。 キーを BLITZ_API_KEY（.env）から読み込み、.env を .gitignore に追加します。 /v2/account/key-info による事前確認を追加し、found == false、結果が空の場合、米国内のみの電話番号に関する注意事項に対応します。詳細は references/error-handling.md を参照してください。

7. 実行方法をユーザーに伝えます。Python：uv run script.py、TypeScript：bun run script.ts（bun がない場合は npx tsx script.ts）、JavaScript：bun run script.mjs（または node script.mjs）です。 設定が必要な環境変数（BLITZ_API_KEY）も伝えてください。

ルール

• SDK の使用を徹底してください。生の fetch／requests は決して生成しないでください。SDK をインストールできない場合は、明確で実行可能なエラーを表示して停止してください。
• API キーをハードコードしないでください。.env をコミットしないでください。
• 電話番号のエンリッチメントは米国のみが対象です。呼び出す前に、米国以外の連絡先を除外してください。
• ブリーフに従ってください。exceeds_ceiling が true の場合は、分割されたテンプレートが必須です。
• ブリーフの language に従ってください。javascript のブリーフでは、実行可能な JavaScript（script.mjs、node／bun で実行）を用意してください。TypeScript や TS ランタイムを無理に使わせないでください。