encore-migrate

Encore への移行

このスキルは、既存のバックエンドアプリケーションを Encore へ、一度に 1 つの移行単位で移行する手順を案内します。あらゆるソース言語やフレームワークをサポートし、Encore.ts と Encore Go の両方を対象とします。セッションをまたいで進捗を追跡するため、Encore プロジェクトのルートに migration-plan.md というサマリーファイルと、移行単位ごとの詳細ファイルを格納する migration-plan/ ディレクトリが作成されます。このスキルには Encore のコード例は含まれていません。Encore 固有の実装はすべて、適切な言語別スキルに委ねます。

フェーズの判定

何かを行う前に、どのフェーズから始めるべきかを判断します:

• Encore プロジェクトディレクトリに migration-plan.md が存在しない → フェーズ 1: DISCOVER から開始
• migration-plan.md は存在するが migration-plan/ ディレクトリが存在しない → フェーズ 2: PLAN から再開（Discovery は完了しているが、詳細ファイルがまだ作成されていない）
• migration-plan/ ディレクトリが存在し、未処理の移行単位がある（サマリー内のいずれかの移行単位のステータスが pending または in progress） → フェーズ 3: MIGRATE から再開
• サマリー内のすべての移行単位が migrated、skipped、または manual validation needed → フェーズ 4: COMPLETE へ進む

自律モード

このワークフローにおける確認のための停止（フェーズ 1 での移行単位の確認、フェーズ 2 での最初の移行単位の承認、フェーズ 3 での各次の移行単位の選択）はデフォルトの動作です。ユーザーが停止せずに移行を最後まで実行するよう求めた場合（「そのまま移行して」「全部やって」「聞かないで」）、これらの停止をスキップします:

• 未確定の決定事項については妥当なデフォルトを選択し（フェーズ 1 の「主要な決定事項」を参照）、コードを書く前にそれぞれを短いリストでユーザーに伝えます
• すべてのデフォルトを migration-plan.md の ## Decisions セクションに記録し、後から見直せるようにします
• ソースシステムに対する副作用のある HTTP 呼び出しの前には、引き続き確認を求め、ソースを決して変更しません
• 各エンティティを migrated とマークする前に、引き続き検証します

移行の再開（フェーズ 3）

migration-plan.md と migration-plan/ が存在し、未処理の移行単位がある場合:

1. migration-plan.md を読みます（サマリーのみ — すべての詳細ファイルを読んではいけません）
2. 現在のステータスをユーザーに報告します — 例えば: 「7 ユニット中 3 ユニットが移行済みです。次に推奨: billing（依存関係はすべて移行済みです）」
3. 次に取り組みたいものをユーザーに尋ね、プラン内の依存関係の順序に基づいて提案を行います

フェーズ 1 — Discover

1. 情報の収集

ユーザーに以下を尋ねます:

• ソースシステムのパス（移行対象の既存コードベース）
• ソースシステムが実行されるローカル URL（該当する場合 — 後の HTTP 比較検証に必要です）
• ターゲット言語: Encore.ts または Encore Go

2. ソースコードベースの分析

ソースコードベースを読み、すべてのエンティティを洗い出します:

カテゴリ	探すべきもの
サービス / モジュール / ドメイン	明確な境界づけられたコンテキスト、個別にデプロイ可能な単位、ルートのグループ化
API エンドポイント	メソッド、パス、ハンドラー関数、リクエスト/レスポンスの形状
データベース	種類（Postgres、MySQL など）、テーブル、スキーマ、マイグレーションファイル
Pub/Sub トピックとサブスクリプション	トピック名、パブリッシャー、サブスクライバー、メッセージの形状
Cron ジョブ / スケジュールされたタスク	スケジュール式、ハンドラー関数
認証ミドルウェア / ハンドラー	認証戦略、トークン検証、セッション管理
シークレット / 環境変数	参照されているすべての環境変数とシークレット（どれが機密かを記録）
グローバルな HTTP の挙動	CORS 設定、グローバルなパスのプレフィックス、グローバルミドルウェア、カスタムのエラーフィルター / エラーレスポンスのボディ
既存のテスト	テストファイル、それらが対象とするエンティティ、使用されているテストフレームワーク
フロントエンドコード	React/Vue/Angular コンポーネント、静的 HTML、CSS、クライアントサイド JS — これらは対象外です

3. フロントエンドコードの特定

フルスタックのリポジトリやモノレポでは、バックエンドとフロントエンドのコードが混在していることがよくあります。移行の対象はバックエンドのみであり、フロントエンドのコードは対象外です。

フロントエンドのディレクトリを検出し、対象外としてマークします。 よくある指標は次のとおりです。

パターン	例
専用のフロントエンドディレクトリ	frontend/、client/、web/、app/（React/Vue/Angular を含む場合）、src/components/、public/
フロントエンドの設定ファイル	next.config.js、vite.config.ts、nuxt.config.ts、angular.json、.svelte-kit/、remix.config.js
パッケージの依存関係	package.json 内の react、vue、@angular/core、svelte

移行すべきフレームワークのサーバーサイドコードにフラグを立てます。 一部のフロントエンドフレームワークには、API エンドポイント、データベースクエリ、サーバーサイドのビジネスロジックを含むバックエンドロジックが埋め込まれています。

フレームワーク	サーバーサイドの場所	探すべきもの
Next.js	pages/api/、app/*/route.ts	API ルートハンドラー — これらはバックエンドのエンドポイントです
Remix	app/routes/*.tsx（loader/action のエクスポート）	loader 関数と action 関数にサーバーロジックが含まれます
Nuxt	server/api/、server/routes/	サーバー API ルート
SvelteKit	src/routes/+server.ts、+page.server.ts	サーバーエンドポイントと load 関数
Astro	src/pages/*.ts（.astro 以外）	API エンドポイント

フレームワークのサーバーサイドコードが見つかった場合は、それをどう扱うかをユーザーに確認します。 すべてのサーバーサイドコードを Encore に移すべきとは限りません — 場合によっては、薄いバックエンドレイヤー（BFF、認証プロキシ、SSR のデータフェッチ）は Encore バックエンドと並行してフロントエンドフレームワーク内に残すべきです。

見つかった内容をユーザーに提示し、次のように尋ねます。

「 アプリで 個のサーバーサイドルート（例: pages/api/users.ts、app/billing/route.ts）が見つかりました。これらには Encore に移行できるバックエンドロジックが含まれていますが、SSR のデータフェッチや BFF プロキシなどのために、フロントエンドフレームワーク内に薄いサーバーレイヤーを残すことを好むチームもあります。どのようにしますか:

1. サーバーサイドルートをすべて移行して Encore に移す
2. 一部を移行 — 一覧を提示するので、移行するものを選んでください
3. すべて に残す — スタンドアロンのバックエンドコードのみを移行する」

ユーザーの選択に基づいて:

• すべて移行: バックエンドロジックを移行単位に抽出します。フロントエンドのレンダリングコードは対象外のままにします。移行計画に、フロントエンドとバックエンドのコードが混在しているソースファイルを記載します。
• 一部を移行: サーバーサイドルートの一覧を提示し、ユーザーに選択してもらいます。選択されたルートを移行単位に含め、残りは対象外としてマークします。
• すべて残す: フレームワークのサーバーサイドコードをすべて、フロントエンドと同様に対象外としてマークします。スタンドアロンのバックエンドコード（Express のルート、スタンドアロンの API サーバーなど）のみが移行単位に入ります。

ユーザーに報告: 検出されたすべてのフロントエンドディレクトリと、フレームワークのサーバーサイドコードについて下した決定を一覧にします。例: 「app/ に Next.js のフロントエンドが見つかりました — React コンポーネントは対象外です。pages/api/ の 12 個の API ルートのうち 8 個を Encore に移行し、4 個の薄いプロキシルートを Next.js に残すことを選択しました。」

4. 主要な決定事項を特定する

一部の選択はすべてのユニットに影響します。計画を立てる前にそれらを明らかにし、回答を migration-plan.md の ## Decisions セクションに記録してください。

• 動作のターゲット: 古いコードベースにはしばしばバグがあります（所有権チェックの欠落、保存されないフィールド、誤ったフィルター）。ソースの動作を正確に再現するのか、明らかなバグを修正するのかを確認してください。ソースが公開された API 契約（OpenAPI 仕様、RealWorld、パートナー連携）を実装している場合は、その契約に合わせて修正するのが通常は正しい選択です。どちらを選ぶにせよ、意図的な相違点をそれぞれユニットの Notes 列に列挙してください。
• エラー応答フォーマット: Encore の型付き api() エンドポイントは常にエラーを {code, message, details} として返し、リクエスト検証の失敗は常に HTTP 400 です。クライアントが異なるエラーボディ（例: {"errors": {...}}）やステータス（例: 422）に依存している場合、選択肢は次のとおりです。Encore のフォーマットを受け入れる（フィールドエラーは details に入れられます）、または影響を受けるルートに api.raw を使用する（型付きリクエストと生成されたクライアントを諦めることになります）。どちらを好むかをユーザーに確認してください。
• CORS: ソースが CORS を有効にしている場合は、Encore のデフォルトに任せるのではなく、encore.app の global_cors に変換してください。

5. エンティティを移行ユニットにグループ化する

発見したエンティティを、次の優先順位のヒューリスティクスを用いて移行ユニットにグループ化します。

1. 既存のサービス境界 — ソースアプリにすでにサービス、モジュール、パッケージがある場合は、それらをチャンクの出発点として使用します
2. URL パスのプレフィックス — パスプレフィックスを共有するエンドポイントをグループ化します（例: /users/*、/billing/*）
3. 共有データベーステーブル — 同じテーブルを読み書きするエンドポイントは一緒にまとめます
4. 共有の型/モデル — リクエスト/レスポンスの型やドメインモデルを共有するエンドポイント

チャンクのサイズ: 移行ユニットあたり 5〜15 エンドポイントを目安にしてください。グループが約 15 エンドポイントを超える場合は、さらに分割することを提案してください（例: users-crud と users-admin）。グループのエンドポイントが 3 つ未満の場合は、関連するチャンクと統合することを検討してください。

横断的関心事は独自の移行ユニットを持ちます。認証、シークレット、およびスタンドアロンのインフラストラクチャ（pub/sub トピック、1 つのサービスに密結合していない cron ジョブ）は、異なる依存関係の階層に従うため、別々のユニットになります。

明確な境界がないモノリスの場合: URL パスプレフィックスによるグループ化にフォールバックし、次のように尋ねてください。「これらのグループ化は URL パスに基づいています — ドメインごとに再編成しますか？」

6. 移行ユニットを提示する

移行ユニットを要約表としてユーザーに提示します。

Unit	Endpoints	DB Tables	Other	Complexity

合計数を含めてください（例: 「42 エンドポイント、3 データベースをカバーする 7 つの移行ユニット」）。各ユニットについて、移行全体の複雑さを評価します。

• Low — 直接対応する Encore の等価物が存在し、マッピングが straightforward
• Medium — 再構築が必要、または部分的に Encore の等価物が存在する
• High — 直接対応する等価物がなく、再設計またはカスタムソリューションが必要

ユーザーが確認する前に中身を検査したい場合に備えて、任意のユニットの詳細を表示することを提案してください。

7. コードプレビューを表示する

2〜3 の代表的なエンティティ（異なるユニットから単純なものと複雑なものを混ぜて選んでください）について、ソースコードが現在どのようになっているか、および Encore 版がどのようになるかの短い「ビフォーアフター」プレビューを表示します。プレビューには適切な言語固有のスキルを用いてください。プレビューは簡潔に保ってください — プレビューごとに 1 つのエンドポイント、1 つのクエリ、または 1 つのトピック宣言で十分です。

8. ユーザーに確認する

移行ユニットが正しいことをユーザーに確認してください。特に次のように尋ねてください。

• 「見落としているサービス、エンドポイント、その他のエンティティはありますか？」
• 「これらの移行ユニットを分割、統合、または名前変更したいですか？」
• 「移行から除外したいものはありますか？」

9. 必要に応じて反復する

ユーザーが不足しているエンティティを指摘したり、チャンクの境界を調整したい場合、ユニットを更新して要約表を再提示してください。ユーザーが移行ユニットが正確であると確認するまで繰り返してください。

フェーズ 2 — 計画

1. 既存の Encore プロジェクトの確認

対象パスに Encore プロジェクトがすでに存在するかどうかを確認します（encore.app ファイルを探します）。存在する場合は、これが正しいプロジェクトであることをユーザーに確認します。存在しない場合は、encore-getting-started スキル（Go の場合は encore-go-getting-started）を呼び出して作成を支援します。

2. 対象情報の収集

ユーザーに以下を尋ねます:

• Encore プロジェクトのパス（移行後のコードが配置される場所）
• Encore アプリが実行されるローカル URL（デフォルト: http://localhost:4000）

3. 依存関係の順序の決定

依存関係に基づいて移行単位を並べます。次の階層順に従います:

1. シークレット / 設定 — 依存関係がなく、すべてのものから必要とされる
2. データベース — サービスが使用する前に、スキーマとマイグレーションが存在している必要がある
3. 認証 — 保護されたエンドポイントの前に、認証ハンドラーが必要
4. リーフ単位 — サービス間の依存関係がない単位
5. 依存単位 — すでに移行済みの単位に依存する単位
6. Pub/Sub トピックとサブスクリプション — 多くの場合、サービスが整っていることに依存する
7. Cron ジョブ — 通常、サービスエンドポイントに依存する

各階層内では、最もシンプルな単位を最初に提案します（エンドポイントが最も少なく、スキーマが最小で、複雑さが最も低いもの）。

4. migration-plan.md（サマリー）の作成

以下の「migration-plan.md の形式」セクションのテンプレートを使用して、Encore プロジェクトのルートに migration-plan.md サマリーファイルを作成します。すべての移行単位をステータス pending で記入します。

5. 詳細ファイルの作成

Encore プロジェクトのルートに migration-plan/ ディレクトリを作成します。以下の「詳細ファイルの形式」セクションのテンプレートを使用して、移行単位ごとに 1 つの詳細ファイルを作成します。各ファイルの名前は migration-plan/<unit-name>.md です。

6. 最初の単位の提案

最初の移行単位を提案し、依存関係の順序に基づいて、なぜそれが最初であるべきかを説明します。フェーズ 3 に進む前にユーザーの承認を待ちます。

フェーズ 3 — 移行（ループ）

1. 次の単位の特定

migration-plan.md（サマリーのみ）を読み、依存関係の順序に基づいて次に保留中の移行単位を特定します。

2. 提案と確認

次に移行する単位を提案し、なぜこれが次なのかを説明します（例: 「この単位は未移行の単位に依存していません」または「これを使用するサービスを移行する前に、データベースが存在している必要があります」）。この単位で進めるか、別のものを選ぶかをユーザーに尋ねます。

3. 単位の詳細の読み込み

選択した単位の詳細ファイル（migration-plan/<unit-name>.md）を読みます。他の単位の詳細ファイルは読まないでください。

4. 各エンティティの移行

単位内の各エンティティについて:

a. 実装

エンティティの種類と対象言語に基づいて、適切な言語固有のスキルを呼び出します:

移行対象...	Encore.ts スキル	Encore Go スキル
サービス構造	encore-service	encore-go-service
API エンドポイント	encore-api	encore-go-api
認証	encore-auth	encore-go-auth
データベース + マイグレーション	encore-database	encore-go-database
Pub/Sub トピックとサブスクリプション	encore-pubsub	encore-go-pubsub
Cron ジョブ / スケジュールされたタスク	encore-cron	encore-go-cron
オブジェクトストレージ / ファイルアップロード	encore-bucket	encore-go-bucket
キャッシュ（Redis）	encore-cache	encore-go-cache
シークレット / API キー / 認証情報	encore-secret	encore-go-secret
Webhook（Stripe、GitHub など）	encore-webhook	encore-go-webhook
テスト	encore-testing	encore-go-testing

b. テストの移行

移行元のエンティティに関連するテストがある場合は、適切なテストスキル（encore-testing または encore-go-testing）を使用して移行します。テストのアサーションを Encore API のパターンに合わせて調整します。移行元のエンティティにテストがない場合は、その旨を詳細ファイルに記録します。

c. 検証

migrated としてマークできるようになる前に、各エンティティに 3 つの検証レイヤーが適用されます。すべてのエンティティは、該当するすべてのレイヤーを通過する必要があります。

レイヤー 1: テストの移行（主要）

• エンティティを移行する際は、関連するテストも一緒に移行します
• テストの実装には encore-testing スキル（Go の場合は encore-go-testing）を使用します
• テストを実行します — エンティティを migrated としてマークする前に、テストが成功している必要があります
• 移行元のエンティティにテストがなかった場合は、計画に「移行元にテストなし」と記載し、他のレイヤーに頼ります

レイヤー 2: HTTP 比較（エンドポイントのみ、ベストエフォート）

両方のシステムがローカルで実行されている場合、移行元システムと Encore アプリの両方で同じエンドポイントを呼び出し、次を比較します:

• HTTP ステータスコード — 一致している必要があります
• レスポンスボディの構造 — キーと形状が一致している必要があります（タイムスタンプや ID などの動的データでは値が異なってもかまいません）

このレイヤーをスキップする場合:

• エンドポイントが、エージェントが取得できない認証情報を必要とする場合（ユーザーに確認する — スキップを許可）

どちらかのシステムへのリクエストが接続に失敗した場合は、再試行する前にユーザーにアプリの起動を依頼します。黙ってスキップしないでください — ユーザーが単に起動し忘れただけかもしれません。

副作用が生じる可能性のある HTTP 呼び出しを行う前には、必ずユーザーに確認してください。

レイヤー 2 の代替: コントラクトテストスイート

移行元システムを現実的に実行できない場合（データベースエンジンが利用できない、ツールチェーンが古すぎてインストールできない、外部依存関係がある）、または動作の対象が意図的に移行元から乖離している場合、移行元に対する HTTP 比較は意味を持ちません。API に外部のコントラクトテストスイート（Hurl、Postman/Newman、Bruno、OpenAPI 仕様に対する Schemathesis、利用側の統合テスト）がある場合は、代わりにそれを Encore アプリに対して実行します:

• 失敗しても続行する形でスイート全体を実行します（例: hurl --test --continue-on-error --report-json）。これにより、ファイルごとに最初の失敗だけでなく、失敗したすべてのアサーションが確認できます
• 失敗を分類します。予期される逸脱（エラーレスポンス形式など、記録された決定によるもの）と、実際の動作のギャップを分離し、ギャップを修正します
• 成功/失敗の件数とカテゴリを検証ログに記録します

移行元に対する HTTP 比較をスキップした理由を計画に記載します。

レイヤー 3: 完了前検証ゲート

いかなるエンティティも migrated としてマークする前に、エージェントは現在のセッションで得た新しい証拠を持っている必要があります:

• 成功件数と終了コードを示すテストコマンドの出力、または
• 一致を示す HTTP 比較の結果、または
• 検証をスキップすることに対するユーザーの明示的な承認

ルール:

• 「動くはず」「正しく見える」「問題なさそう」は禁止 — 証拠に裏付けられた主張のみ
• エージェントは、何を検証し、その出力がどうだったかを正確に述べる必要があります
• 証拠が不十分な場合は、エンティティを migrated ではなく manual validation needed としてマークします
• 前のセッションで得た古い証拠は無効です — 再開する場合は検証を再実行してください

d. 詳細ファイルの更新

ユニットの詳細ファイル（migration-plan/<unit-name>.md）でエンティティのステータスを更新し、そのファイルの検証ログテーブルに検証の証拠を記録します。

e. サマリーの更新

ユニット内のすべてのエンティティが完了したら、migration-plan.md 内のユニットのステータスを migrated に更新します。一部のエンティティが保留中の場合は、ユニットのステータスを in progress に設定します。

5. 続行または一時停止

ユニットを完了した後、「次に何を移行しますか？」と尋ね、依存関係の順序に基づいて次のユニットを提案します。

6. バッチ処理

既定では一度に 1 ユニットです。ユーザーが「続けて」「全部やって」などと言った場合は、複数のユニットをバッチ処理しますが、それでも各エンティティを移行済みとしてマークする前に個別に検証します。

フェーズ 4 — 完了

migration-plan.md 内のすべてのユニットが migrated、skipped、または manual validation needed になったら、次のようにします。

1. migration-plan.md から最終サマリーを提示します:
   • 移行済みユニットの合計数
   • manual validation needed とマークされたユニット — それらの特定の詳細ファイルを読み、注意が必要なエンティティを理由とともに列挙します
   • スキップされたユニット (理由とともに列挙します)
2. 統合の問題を検出するため、最後にもう一度フルテストスイートを実行することを提案します
3. 依然として人手による確認が必要な手動検証項目があれば指摘します
4. ソースシステムにフロントエンドコードがあった場合は、encore-frontend スキルを使ってフロントエンドを新しい Encore バックエンドに再接続することを提案します (型付き API クライアントの生成、CORS の設定、ベース URL の更新)
5. ユーザーが移行に満足したら、プロジェクトから migration-plan.md と migration-plan/ を削除することを提案します

質問をする

次の場合は、行動する前にユーザーに質問します。

• サービスの境界が不明確な場合 — 例: 「これらのルートファイルは 1 つのサービスにも 3 つにもできます — どのように分割しますか?」
• 対応する明確な Encore の等価物が存在しない場合 — 例: Redis キャッシュレイヤー、カスタムミドルウェアチェーン、WebSocket ハンドラー
• 複数の有効な移行戦略が存在する場合 — トレードオフとともに選択肢を提示します
• 副作用を伴う可能性のある HTTP 呼び出しを行う前 — 常に最初に確認します
• ソースコードが曖昧な場合 — エージェントがコードの動作について確信が持てないときは、推測せずに質問します
• ソースシステムが変更されたと思われる場合 — 詳細ファイルで参照されているファイルが存在しなくなった、または大幅に変更された場合

ソースシステムの保護

移行中はソースシステムを決して変更してはいけません。次のルールに従います。

• ソースファイルを決して変更しない — 読み取るだけで、編集しません
• ソースファイルを決して削除しない — 移行が完了した後でも同様です
• ソースディレクトリに決して書き込まない — すべての出力は Encore プロジェクトに送られます
• ソースシステムに対して破壊的なコマンドを決して実行しない (テーブルの削除、キューの削除など)
• ソースシステムの状態を変更する HTTP 呼び出しの前には確認する (POST、PUT、DELETE)

ユーザーが古いシステムの「クリーンアップ」または「削除」を依頼した場合は、いかなる操作を行う前にも明示的に確認してください。ソースシステムは依然として本番トラフィックを処理している可能性があります。

エッジケース

ユニット間でのエンドポイントの移動

ユーザーが、あるエンドポイントが別の移行ユニットに属するべきだと気づいた場合:

1. ソースユニットの詳細ファイルからエンドポイントの行を削除します
2. ターゲットユニットの詳細ファイルにそれを追加します
3. migration-plan.md 内のエンドポイント数を更新します

移行途中でのユニットの分割

作業中にユニットが大きすぎることが判明した場合:

1. 分割された部分のための新しい詳細ファイルを作成します (migration-plan/<new-unit>.md)
2. 保留中のエンティティを新しいファイルに移動します (すでに移行済みのエンティティは元のファイルに残します)
3. migration-plan.md のサマリーテーブルに新しいユニットを追加します
4. 依存関係の順序にそれを挿入します (同じ階層で、元のユニットの後)

モノリスから複数の Encore サービスへ

単一の移行ユニットが複数の Encore サービスにマッピングされることがあります。詳細ファイルはソースのグループ化を追跡しますが、「Notes」列でターゲットの Encore サービスを示すことができます。移行中に、そのユニットが 1 つのサービスにマッピングされるのか、複数の Encore サービスに分割すべきなのかを確認してください。

ディスカバリー以降にソースコードが変更された場合

詳細ファイルで参照されているファイルが存在しなくなった、またはディスカバリー以降に大幅に変更された場合:

1. その不一致をユーザーに報告します
2. 詳細ファイルを新しい状態で更新するか、影響を受けるエンティティをスキップするかを確認します
3. 更新する場合は、複雑さを再評価し、それに応じて計画を調整します

トラブルシューティング

移行中によくある問題と、その解決方法:

問題	原因	解決方法
サービス間のインポートエラー	サービス間の直接インポート	代わりに ~encore/clients (TS) またはサービスごとのクライアントパッケージ (Go) を使用してください
データベースマイグレーションの失敗	互換性のない SQL 構文	Encore は PostgreSQL を使用していることを確認してください — MySQL/SQLite 構文を適応させてください
Pub/Sub メッセージが受信されない	サブスクリプションが登録されていない	サブスクリプションが関数内ではなくパッケージレベルで宣言されていることを確認してください
Cron ジョブが実行されない	無効なスケジュール式	Encore は標準の cron 式を使用します — 構文を確認してください
encore run がインフラストラクチャでエラーになる	インフラストラクチャが関数内で宣言されている	すべてのインフラストラクチャ宣言をパッケージレベルに移動してください
元のコードと Encore の応答が異なる	ビジネスロジックの欠落またはエラーハンドリングの違い	応答の形状を注意深く比較し、エッジケースを確認してください
エンドポイントを検証できない	認証が必要、または副作用がある	ユーザーにテスト用の認証情報を求めるか、manual validation needed としてマークしてください
クライアントが 422 またはカスタムエラー本文を期待している	Encore の型付きエンドポイントは固定のエラーエンベロープを使用し、検証エラーに対して 400 を返します	決定事項として記録してください: Encore の形式を受け入れるか、それらのルートに api.raw を使用してください
移行後にブラウザクライアントが失敗する	元のコードが CORS をグローバルに有効化していた	encore.app に global_cors を追加してください
HTTP 比較のために元のコードを実行できない	古いツールチェーンまたは利用できないインフラストラクチャ	代わりにコントラクトテストスイートを使用してください (Layer 2 Alternative を参照)

migration-plan.md の形式

サマリープランファイルにはこの正確なテンプレートを使用してください。値はディスカバリーフェーズの結果から記入してください。

# Migration Plan

## Source System
- **Path:** <source system path>
- **URL:** <source system local URL>
- **Framework:** <detected framework>
- **Language:** <detected language>

## Frontend (Out of Scope)
- **Detected:** <Yes/No>
- **Directories:** <list of frontend directories, or "None">
- **Framework:** <frontend framework if detected, or "N/A">
- **Note:** <any framework server-side code that WAS included in migration units>

## Target System
- **Path:** <encore project path>
- **URL:** <encore local URL>
- **Type:** Encore.ts | Encore Go

## Decisions
- **Behavior target:** <reproduce source exactly | fix bugs toward <contract>>
- **Error format:** <Encore native | api.raw for <routes>>
- **CORS:** <source setting → encore.app global_cors>
- <any other default chosen in autonomous mode>

## Migration Units

| Unit | Endpoints | DB Tables | Other | Complexity | Status |
|------|-----------|-----------|-------|------------|--------|

## Dependency Order
1. <ordered list of migration units>

Status の値: pending、in progress、migrated、skipped、manual validation needed

Complexity の値: Low (直接的な等価)、Medium (再構築が必要)、High (再設計が必要)

詳細ファイルの形式

移行単位ごとに migration-plan/<unit-name>.md に 1 ファイルを作成してください。この正確なテンプレートを使用してください:

# Migration Unit: <unit-name>

## Source
- **Files:** <list of source files in this unit>
- **Depends on:** <other migration units, with their current status>

## Endpoints
| Endpoint | Method | Path | Status | Notes |
|----------|--------|------|--------|-------|

## Database
| Table | Complexity | Status | Notes |
|-------|------------|--------|-------|

## Tests
- **Source tests:** <test files and count>
- **Migrated:** <count of migrated tests>

## Validation Log
| Entity | Tests | HTTP Match | Evidence | Status |
|--------|-------|------------|----------|--------|

すべてのセクションが必須ではありません — 特定の移行単位に当てはまらないセクションは省略してください (例: シークレットの移行単位には Endpoints や Database セクションはありません)。