migrating-to-workflow-sdk

Workflow SDK への移行

既存のオーケストレーションシステムを Workflow SDK に移行するときは、このスキルを使用します。

事前確認

1. 移行元のシステムを特定します。
   • Temporal
   • Inngest
   • Trigger.dev
   • AWS Step Functions
2. 対象のランタイムを特定します。
   • マネージドホスティング -> start()、getRun()、フック／Webhook、ルートハンドラーに焦点を当てた例にします。
   • セルフホスト -> references/runtime-targets.md も読み、ワークフロー／ステップのコードはそのまま使用できますが、デプロイには World の実装と起動時のブートストラップが引き続き必要であることを明示します。
3. 移行元の構成要素を抽出します。
   • エントリーポイント
   • 待機／タイマー
   • 外部コールバック／承認
   • リトライ／エラー処理
   • 子ワークフロー／ファンアウト
   • 進行状況のストリーミング
   • 外部での副作用

デフォルトの移行ルール

• オーケストレーションは "use workflow" 関数に記述します。
• 副作用、SDK 呼び出し、DB 呼び出し、HTTP 呼び出し、ストリーム I/O は "use step" 関数に記述します。
• sleep() はワークフローのコンテキストでのみ使用します。
• Signals、step.waitForEvent()、.waitForTaskToken では、再開方法を次のいずれか1つだけ選びます。
  • resume/internal -> 決定的な業務トークンを使ってサーバー側コードからアプリを再開する場合は、createHook() + resumeHook() を使用します。
  • resume/url/default -> 外部システムで生成済みのコールバック URL が必要で、デフォルトの 202 Accepted レスポンスで問題ない場合は、createWebhook() を使用します。
  • resume/url/manual -> カスタムのレスポンス本文、ステータス、またはヘッダーが明示的に必要な場合に限り、createWebhook({ respondWith: 'manual' }) を使用します。
  • コールバック URL を求めるプロンプトでレスポンスの仕様が指定されていない場合は、デフォルトで resume/url/default を選択し、その前提を ## Open Questions に明記します。
• createWebhook() と resumeHook() を組み合わせてはなりません。また、createWebhook() に token: を渡してはなりません。
• 子実行では、start() と getRun() を "use step" 関数の中で呼び出します。
• 外部書き込みの冪等性キーには getStepMetadata().stepId を使用します。
• ワークフローのコンテキストで getWritable() を使用してストリームを取得します。ただし、ストリームの操作（書き込み、クローズ）は "use step" 関数の中でのみ行います。
• 複数ステップの補償処理には、ロールバックスタックを優先します。
• アプリ境界の構文は、次の順序で選択します。
  1. プロンプトでフレームワークに依存しないアプリ境界コードが明示的に求められている場合は、Hono のようなフレームワークが指定されていても、標準の Request / Response を使用します。
  2. それ以外で、対象のフレームワークが指定されている場合は、そのフレームワークに合わせたアプリ境界の例にします。
  3. それ以外の場合は、標準の Request / Response を使った、フレームワークに依存しない例にします。Next.js が明示的に指定されていない限り、Next.js 専用のルートシグネチャをデフォルトで使用してはなりません。

すぐ確認できる要点：

• コールバック URL + デフォルトの応答 -> createWebhook()
• コールバック URL + カスタム応答 -> createWebhook({ respondWith: 'manual' })
• 決定的なサーバー側での再開 -> createHook() + resumeHook()

クイックルート選択

移行元で Signals、step.waitForEvent()、または .waitForTaskToken による一時停止がある場合は、references/resume-routing.md を読み込みます。

デフォルトの選択肢：

• コールバック URL のみ -> resume/url/default
• コールバック URL + 明示的なカスタム応答 -> resume/url/manual
• 決定的なサーバー側での再開 -> resume/internal
• セルフホスト -> runtime/self-hosted を追加
• フレームワークの指定あり -> boundary/named-framework を追加
• フレームワークに依存しないことが明示的に求められている -> boundary/framework-agnostic を追加

## Migrated Code の作成に取りかかる前に、選択したルートキーを ## Migration Plan に記載します。

移行元のリファレンス

• Temporal -> references/temporal.md
• Inngest -> references/inngest.md
• Trigger.dev -> references/trigger-dev.md
• AWS Step Functions -> references/aws-step-functions.md

共有リファレンス

• references/shared-patterns.md：フック、子ワークフロー、冪等性、ストリーミング、ロールバック用の再利用可能なコードテンプレートです。
• references/runtime-targets.md：マネージドとカスタムの World に関するガイダンスです。
• references/resume-routing.md：ルートキーの選択、要件、正確な ## Migration Plan の形式について説明します。
• references/retries.md：stepFn.maxRetries、RetryableError({ retryAfter })、FatalError を含む、標準的なリトライの仕組みについて説明します。

必須の出力形式

次の構造で移行内容を返してください。

## Migration Plan
## Source -> Target Mapping
## Migrated Code
## App Boundary / Resume Endpoints
## Verification Checklist
## Open Questions

検証チェックリスト

次のいずれかに当てはまる場合、ドラフトは不合格です。

• ## Migration Plan に Route keys がない
• ## Migration Plan に Why these route keys がない
• ## Migration Plan に、プロンプトと一致しないルートキーが記載されている
• ## Migration Plan に、選択したルートキーと一致しない必須のコード要件が記載されている
• 移行後のコードにソースフレームワークのプリミティブが残っている
• ワークフローのコンテキストに副作用が残っている
• ステップ内に sleep() がある
• ワークフロー関数内にストリーム操作（getWriter()、write()、close()）がある
• 子ワークフローがワークフローのコンテキストから直接 start()／getRun() を呼び出している
• 外部への書き込みに冪等性キーがない
• ソースでシグナル、waitForEvent、またはタスクトークンが使われているのに、フック／ウェブフックがない
• コールバック URL を使うフローで、createWebhook() ではなく createHook() + resumeHook() を使っている
• resume/url/default または resume/url/manual の移行で、webhook.url のみを再開手段とすべきところに、ユーザー作成のコールバックルートまたは resumeWebhook() ラッパーを独自に追加している
• createWebhook() にカスタムの token を指定している、または resumeHook() と組み合わせている

検証に関する注意：

• ワークフローのコンテキストでウェブフックのリクエストデータを読み取ることは許可されています。ステップ内でのみ使えるのは request.respondWith() です。

追加の不合格条件：

• resume/internal の出力で、アプリ境界のコードに resumeHook() がない
• resume/internal の出力に、決定的なビジネストークンがない
• resume/internal の出力に、createWebhook() または webhook.url がある
• resume/url/default の出力で、外部システムに webhook.url を渡していない
• プロンプトにカスタムレスポンスの要件がないのに、resume/url/default の出力に resumeHook()、respondWith: 'manual'、または RequestWithResponse がある
• webhook.url を再開手段とすべきところに、resume/url/default の出力でユーザー作成のコールバックルートまたは resumeWebhook() ラッパーを独自に追加している
• resume/url/manual の出力で、外部システムに webhook.url を渡していない
• resume/url/manual の出力に RequestWithResponse または await request.respondWith(...) がない
• resume/url/manual の出力で、"use step" 関数の外から request.respondWith(...) を呼び出している
• webhook.url を再開手段とすべきところに、resume/url/manual の出力でユーザー作成のコールバックルートまたは resumeWebhook() ラッパーを独自に追加している
• createWebhook() を resumeHook() と組み合わせている
• セルフホストの出力に、World extends Queue, Streamer, Storage、startWorkflowWorld()、または「カスタムの World はアプリに引き続き必要ですが、ワークフローとステップのコードはそのまま使えます」という明示的な注記がない
• 名前付きフレームワークの出力で、フレームワークの構文と、フレームワークに依存しない上書き指定なしのプレーンな Request／Response アプリ境界コードが混在している

合格する具体的なコードについては、次を参照してください。

• references/shared-patterns.md -> ## Generated callback URL (default response)
• references/shared-patterns.md -> ## Generated callback URL (manual response)
• references/runtime-targets.md -> ## Self-hosted output block
• references/aws-step-functions.md -> ## Combined recipe: callback URL on self-hosted Hono

サンプルプロンプト

Migrate this Inngest workflow to the Workflow SDK.
It uses step.waitForEvent() with a timeout and step.realtime.publish().

期待される応答形式：

## Migration Plan
## Source -> Target Mapping
## Migrated Code
## App Boundary / Resume Endpoints
## Verification Checklist
## Open Questions

参考例

プロンプトで具体的なコードが必要な場合にのみ、実装例を読み込みます。

• references/shared-patterns.md -> ## Named-framework internal resume example (Hono)
• references/shared-patterns.md -> ## Generated callback URL (default response)
• references/shared-patterns.md -> ## Generated callback URL (manual response)
• references/runtime-targets.md -> ## Self-hosted output block
• references/aws-step-functions.md -> ## Combined recipe: callback URL on self-hosted Hono

次の誤った例は採用しないでください。

• webhook.url が意図された再開用の受け口である場合に、resume/url/default または resume/url/manual と、ユーザーが作成したコールバックルートを組み合わせる
• createWebhook() と resumeHook() を組み合わせる
• フレームワークに依存しないオーバーライドがない状態で、名前付きフレームワークのアプリケーション境界の出力と、プレーンな Request / Response を混在させる