existing-project-migration

既存プロジェクトの移行

基本方針

作業を続ける前に、コンテキストが圧縮されるたびにこの SKILL.md を読み直してください。会話の記憶だけで十分だと思い込まないでください。

このスキルの対象は技術スタックの移行であり、製品の再設計ではありません。

• お客様はすでにアプリをお持ちです。
• そのアプリを Customware スタックに再構成することが作業の目的です。
• 移行元製品のルート、ワークフロー、ラベル、レイアウトシェル、ページセクション、セクションの順序、ビジュアル表現、スタイルは、移行元に忠実な形で維持してください。デフォルトでは、ユーザー向けの UI や UX を意図的に変更しないことが期待されます。
• 実行時のスタックは、template-be-setup と必須の client-only-spa マージルールから構成される、準備済みの Customware スタックに変更する必要があります。

この作業を、新しいアプリの構築、ドメインの再解釈、または製品を小規模で汎用的なダッシュボードに簡素化する機会として扱わないでください。 過去の移行での想定を持ち込まないでください。このスキルは、お客様がアップロードしたどのアプリにも対応できる必要があります。移行元から何を維持するかは、その都度、現在インポートされているソースから判断してください。 移行元アプリに慣れたお客様が、作り直された別のアプリではなく、新しいスタック上で同じアプリを使っていると感じられるようにしてください。 実際のスタック制約、移行元成果物の欠落、または移行元のバグによって文字どおりの完全一致ができない場合は、差異を最小限にとどめ、名前を付けて明示的に記録してください。

ソースの優先順位

アップロードされた成果物を移行の基準とします。

優先順位：

1. projects.zip 内の .import/project/ を、製品の動作、ルート、UI、ワークフロー、インテグレーション、ビジネスロジックに関する第一の基準とします。
2. database.zip 内の .import/database/ を、永続化されるエンティティ、スキーマの推定、CSV 行が存在する場合のシードデータに関する第一の基準とします。
3. domain.zip 内の .import/domain/ と .import/domain-source.txt は、補助的なコンテキストとしてのみ扱います。
4. .tasks/domain.md、組織名、組織の説明、ロゴ、色、ブランドに関するコンテキストは、優先度の低い表示上のコンテキストに限ります。

組織や会社に関する情報、または .tasks/domain.md によって、インポートされた製品のドメイン、ルート、ワークフロー、スキーマ、製品の位置付けを再定義しないでください。この移行では、製品に関する基準としてドメインスキルに依存しません。 .tasks/domain.md が存在する場合でも、移行中の製品定義の判断では、実質的に無視できるものとして扱ってください。真の情報源は、.import/project/ 内のインポートされたコードベースと、.import/database/ 内のインポートされたデータベースファイルです。ドメイン関連の情報は、表示に関する細かなコンテキストの把握に役立つ場合にのみ使用し、ソースコードやソースデータより優先させないでください。

固定の移行先スタック

準備済みの Customware フルスタック移行先に移行してください。

• Vite
• React Router
• TypeScript
• Zod
• Node
• Hono
• tRPC
• better-sqlite3 経由の SQLite
• Drizzle ORM とマイグレーション

アップロードされた移行元アプリの実行時スタックを維持しないでください。

必須のフェーズ別参照資料

作業を始める前に、現在のタスクに該当するファイルを正確に読んでください。

• Migration build
  • .agents/skills/existing-project-migration/references/phase-1/overview.md
  • .agents/skills/existing-project-migration/references/phase-1/artifacts.md
  • .agents/skills/existing-project-migration/references/phase-1/grading.md
• Migration verify
  • .agents/skills/existing-project-migration/references/phase-2/overview.md
  • .agents/skills/existing-project-migration/references/phase-2/artifacts.md
  • .agents/skills/existing-project-migration/references/phase-2/grading.md

タスクの説明が不明確な場合は、まず両方のフェーズ概要ファイルを読み、現在のフェーズを特定してから、該当する成果物と評価の参照資料を読み込んでください。

移行における重要な不変条件

以下は厳守するルールです。

• これはスタックの移行です。ソースのプロダクトは維持し、ランタイムの基盤を置き換えてください。
• インポートしたアプリの画面に表示されるルートマップ、ルートパス、ナビゲーションラベル、ページ階層、見出し、ページセクション、セクションの順序、セクションのスタイル、操作面、ワークフロー、タイポグラフィ、テーマトークン、ロゴの使用方法を維持してください。デフォルトでは、ユーザー向けの変更は意図的に一切加えないものとします。
• インポートしたアプリの実際の画面の種類と、ソースにある具体的なページ仕様を維持してください。ソースのページがカレンダーなら、カレンダーを中心とした画面にしてください。情報量の多いテーブルワークスペースなら、その構造を維持してください。実際の設定フォームなら、同じフォーム主体の画面を維持してください。扱う業務領域が似ているという理由だけで、画面の種類を別のものに置き換えないでください。
• インポートしたフロントエンドを視覚表現と情報アーキテクチャの基準とし、ソースのルート／ページファイルを移植対象として扱ってください。UI の方向性を決める前に、実際に使用されているルーター／ブートストラップ、レイアウト／ナビゲーションファイル、テーマ／ルート CSS ファイル、主要なアセット、代表的なページファイルを確認してください。
• ソースのページ構造とスタイルトークンを直接移植してください。ソースの UI を、新しい要約、補足テキスト、説明パネル、汎用的なプロダクト文言に言い換えないでください。
• インタラクティブな検証を始める前に、ソースのフロントエンドコード、移行後のコード、利用可能なソースのスクリーンショットを直接照合して、移行前の忠実性レビューを実施してください。インタラクティブな検証を始める前に、共通シェルとソースに表示されるすべての画面について、期待されるレイアウトブロック、名前付きセクション、セクション順序、見出し、ラベル、コントロール、アクション、テーブル、チャート、フォーム、タブ、スタイルの方向性が維持されていることを確認してください。
• ソースに表示される画面ごとに、実装または評価の前に、正確な画面仕様を抽出してください。この仕様には、ソースアプリから取得した正確なボタンラベル、タブラベル、フィルターラベル、セクションタイトル、テーブル列、主要なアクション、名前付きセクション、セクション順序を含めてください。
• コード上で確認できる欠落は、インタラクティブ QA の前に不合格として扱ってください。ソースコードからサイドバー、ナビゲーションセクション、ヘッダー、タブバー、テーブルヘッダー、フィルター行、フォームブロック、チャートブロック、アクショングループ、その他の表示セクションの存在が明らかな場合、移行後のコードにそれらがなければ、ページを技術的にレンダリングできても、作業フェーズは未完了です。
• 抽出した正確な仕様項目が欠落、改名、並べ替え、認識できないほどのスタイル変更、または明示的な阻害要因なしで別の画面に置き換えられている場合、その評価は不合格です。不合格となった項目を必須の次回修正キューに加え、画面が合格するまで反復してください。
• ユーザーが気づく UI の違いを本当に避けられない場合は、最小限にとどめ、migration-plan.json、migration-review.md、migration-open-gaps.md に明記してください。記録されていない差異は不合格です。
• Imported App Migration、Migration slice、またはそれに類する移行をテーマにした文言を作らないでください。
• ソースアプリ自体がその表現を使用していない限り、ユーザー向けの文言で「インポート済み」「移行済み」「ソース」「維持済み」「フェーズ」「CSV」「シード」「ステージング」「準備状況」「レビュー」、または同等の来歴を示す表現に言及しないでください。
• CSV エクスポートがデータモデルの一部しかカバーしていないという理由で、インポートしたアプリを狭い垂直スライスに縮小しないでください。
• ソースに表示されるページを、汎用的なヒーローカード、プレースホルダーのダッシュボード、埋め草の文章、サマリーカード、準備状況パネル、汎用的なレビュー／ステータスの枠組みに置き換えないでください。
• インタラクティブ検証は常にエンドユーザーの視点で実施してください。レビュー用またはプレビュー用ホストがある場合は、通常、未認証状態で / にアクセスするなど、実際にそのホストで最初にユーザーに表示されるページから開始してください。
• インタラクティブ検証では、DOM の存在だけでなく、画面上での見た目の一致を確認してください。期待されるシェル、レイアウトブロック、主要なコントロールが画面上に表示され、少なくとも1つの基本的なページ固有の操作が機能して初めて、そのルートを検証済みとみなします。非表示のテキスト、切り離された UI、または DOM ノードが存在するだけの状態は成功とみなしません。
• フェーズ1の検証は、広範な自動テストスイートの作成ではなく、網羅的なインタラクティブ QA です。ユーザーの視点から、移行後に利用可能なすべてのページルートにアクセスし、各ルートで少なくとも1つの基本的なページ固有の操作を実行してください。対象の画面がある場合は、ログイン、サインアウト、ナビゲーション、検索、フィルター、タブ、フォーム、詳細表示、連携や設定の操作など、一般的なフローも確認してください。
• 自動ユニットテストとエンドツーエンドテストスイートは、主にフェーズ2で扱います。フェーズ1でテストを追加または修正してよいのは、移行やインタラクティブ QA を妨げる問題を解消するために必要な場合に限ります。フェーズ1の承認は、自動テストの範囲の広さではなく、網羅的なインタラクティブ検証の証跡に基づきます。
• レビュー用またはプレビュー用の URL がある場合、localhost のみ、またはデバッグポートのみでの検証では承認に不十分です。
• 最初のページが空白、ログインページが空白、シード済みログインが失敗、アプリ内で最初に行うナビゲーションが失敗、致命的なコンソールエラー、またはハイドレーション／ランタイムの起動エラーがある場合は、自動的に不合格です。
• 移行を成功したように見せるためだけに、レガシーランタイム、後方互換性のためのハンドラー、余分なバリデーターサービスを残さないでください。
• インポートしたプロダクトに合わなくなったテンプレートのデモページ、プレースホルダーの文言、テンプレート専用のテストを削除してください。
• .import/database/ に CSV の行データがある場合は、それをシードデータの基準としてください。
• 以下のエージェント管理のレビュー成果物を、準拠状況を徹底するための手段として使用してください。スコアが不合格、または通常の差異が未解消のままであれば、作業フェーズは未完了です。
• 忠実性は、現在のインポート済みアプリのみを基準に評価してください。以前の移行で得た教訓を、後続の移行における暗黙のプロダクト要件として持ち込まないでください。

必須の適用アーティファクト

これらのファイルは、移行中の必須品質ゲートです。

• .import/migration-plan.json
• .import/migration-checklist.md
• .import/migration-review.md
• .import/migration-open-gaps.md

以下のテンプレートをそのまま使用してください。

• .agents/skills/existing-project-migration/assets/templates/migration-plan.json
• .agents/skills/existing-project-migration/assets/templates/migration-checklist.md
• .agents/skills/existing-project-migration/assets/templates/migration-review.md
• .agents/skills/existing-project-migration/assets/templates/migration-open-gaps.md

ルール：

• Migration build は、ソースを十分に取り込んだ後に限り、不足しているアーティファクトを作成します。
• Migration verify は、検証開始時に必須アーティファクトが不足している場合、失敗します。
• 意味のある実装または検証の各パスの後に、migration-review.md と migration-open-gaps.md を更新してください。
• レビューと未解決課題の台帳では、ソース上で確認できる画面をそれぞれ個別に追跡し、コンテキストに必要な共有シェルまたはランタイムの項目も追跡してください。
• テンプレートの台帳テーブルを曖昧な文章に置き換えないでください。
• 最初の実際の評価パスでは、敵対的パスがすでに記録され、実際にブロッキングとなるドリフトが見つからなかった場合を除き、ギャップがゼロだと宣言してはなりません。
• 重要な評価項目に不合格となった場合、スコアのしきい値に届かなかった場合、または migration-open-gaps.md に通常の移行ドリフトが残っている場合、タスクは完了していません。

フェーズモデル

• Migration build はフェーズ 1 です。
  • ソースを徹底的に読み込みます
  • 移行計画とチェックリストを作成します
  • テンプレートをマージします
  • ソースからスキーマ、ルート、ページ、ワークフローを導き出します
  • ソースに基づいて UI を翻訳し、ルートごとにソース画面との忠実性を確保します
  • ブラウザーでの QA の前に、ソースコードとスクリーンショットを基準に敵対的な自己採点を行います
  • 移行されたすべてのページルートを対象に、ユーザー視点でインタラクティブな検証を徹底的に行います
  • ユーザーに見える未解決の差異がない状態で、初回の移行評価に合格します
• Migration verify はフェーズ 2 です。
  • フェーズ 1 の成果物を再読み込みします
  • フェーズ 1 のインタラクティブ QA の証跡を再読み込みします
  • verify の修正後、ユーザー視点で簡潔な健全性チェックを再度行います
  • 新しいデータベースでランタイム検証を行います
  • 単体テストを作成または修復します
  • Playwright のエンドツーエンドテストのカバレッジを修復または拡張します
  • 最終的な移行評価に合格します
  • 最後の手順として .import/、Playwright の出力、および移行専用の一時的な成果物をクリーンアップします

スコアのしきい値を超え、重要項目がすべて合格し、通常の未解決項目が残らなくなるまで、両フェーズとも反復してください。 ルーブリックを何度か実行し、まだ不合格だと気づいたところで止めてはいけません。採点の目的は、さらなる反復を促すことです。合格ラインを余裕のあるスコアで超えるまで、修正と再採点を続けてください。ぎりぎりの合格ではなく、おおむね高得点での合格を目指します。

フェーズ 1 はインタラクティブテストを重視します。フェーズ 2 は自動テストを重視します。 フェーズ 1 では、ソースに忠実なアプリと、ユーザー視点でルートを網羅的に確認した証跡を作成してください。 フェーズ 2 では、その証跡を永続的な単体テストとエンドツーエンドテストのカバレッジに変換し、インタラクティブな健全性チェックは軽く行うだけにして、最後にリポジトリをクリーンな状態にしてください。

UI の正確な再現はフェーズ 1 の担当です。画面の重要な一致をフェーズ 2 に先送りしないでください。フェーズ 1 の終了時点で、移行後のアプリはランタイムを置き換えただけの同一アプリのように見え、動作する必要があります。 エージェントはソースのフロントエンドコードを直接読めるため、元の UI 実装は着想の参考ではなく、翻訳対象の入力として扱ってください。新しいスタックで可能な限り、ルートごとの構成、名前の付いたページセクション、セクションの順序、ラベル、アクション、フィルター、フォーム、テーブル、グラフ、空の状態、スタイルトークンを直接移植してください。 見た目が近いだけの画面、同じ業務領域に属しているだけの画面、または移行や出所に関する説明文で補った画面は不合格です。 コードから明らかな基本構造のずれを、ブラウザーでの確認まで放置しないでください。ソースアプリに常設のサイドバー、ナビゲーションセクション、ヘッダーブロック、タブストリップ、フィルターバー、テーブル全体のセクション、テーブルヘッダーバンド、フォームセクション、またはその他の主要な表示要素がある場合は、インタラクティブテストの前に、移行後のコードにもおおむね同じ配置で含まれていることを確認してください。 画面ごとの採点は印象ではなく、具体的に行ってください。移行後の画面を抽出した正確な要件と項目ごとに比較し、不一致があればその評価ラウンドを不合格とし、修正して画面が合格するまで再評価してください。

絶対に守ること

• 移行は ZIP 主導のままにします。
• 組織のコンテキストはプレゼンテーション上の文脈に限定し、製品の決定権に関する文脈には使用しません。
• ランタイムは固定された Customware スタック上で維持します。
• client-only-spa の app/ をマージする際は、app/lib/trpc-provider.tsx と app/utils/error-logger.ts を保持します。
• リリースするルートやページに、移行に関する説明や来歴の解説を含めてはいけません。
• 実際のレビュー用アプリまたはプレビュー用アプリが、空白画面で起動する、あるいはユーザーがログインまたはログイン後の最初のページに到達する前にクラッシュする場合、どのフェーズも合格にしてはいけません。
• 添付のみ、または非表示要素のチェックを根拠に、どのフェーズも合格にしてはいけません。検証の証拠には、期待される UI がユーザーの視点から見て画面上に表示され、操作可能であることを示す必要があります。
• ワークスペース内に許可されたクローンがすでにある場合を除き、代替テンプレートの手順を求めて準備済みワークスペースの外を検索してはいけません。
• .import/ やその他の一時的な移行証拠は、フェーズ 1 の間およびフェーズ 2 の検証中は保持し、その後、タスクで永続的な保持が明示的に求められていない限り、フェーズ 2 の最終クリーンアップ手順で削除します。
• 根拠の弱い移行を自己承認するのではなく、具体的な阻害要因を示して失敗とします。