v0でUI案を作ってCursorで実装するワークフロー

v0とCursorを併用するなら、どちらが「本物のコード」を持つかを先に決めます。現在のv0はGitHubの既存repositoryをimportし、branch上で編集、commit、pull request作成まで進められるため、「v0は見た目、Cursorは実装」と役割を固定するのは正確ではありません。UI探索だけなら小さなprototypeから始め、既存repositoryへ変更を入れるならGitHubを共通の正本にします。Cursorでは既存構成へ統合し、testと差分reviewを行います。

この記事は機能の勝敗ではなく、作業境界を決めるworkflowです。v0側のbranchがそのまま製品repositoryの変更になる運用もありますし、Cursorを使わなくてよい場合もあります。両方を使うなら「画面案」「既存codeへの統合」「作業owner」「完了条件」を開始前に決めてください。

GitHubを共通の正本にするかを選ぶ

まず、作業が既存appへ入るか決まっていない画面案なのか、既存appのroute、design token、認証、APIを変更する作業なのかを分けます。prototypeなら新しいv0 projectで見た目を試し、production用のsecretや実データは接続しません。既存appを変えるなら、そのrepositoryをv0へimportするかCursorで開き、同じGit履歴を見られる状態にします。

v0公式のGit Importは、GitHub repositoryを取り込んで既存codebase上で作業する機能です。権限によって元repositoryへ変更をpushする場合と、自分のaccountへcloneする場合があります。v0のGitHub接続ではchatごとに作業branchが作られ、pull requestを通じてbase branchへ取り込むworkflowが案内されています。実際の書き込み先が元repoかcloneか、branch名、PRのbaseを画面で確認します。似た名前のrepositoryや部署違いのprojectを選ばないためです。

判断の目安：

・UIの方向だけ決めたい：隔離prototype。既存production設定や実dataはつながない。

・既存appの一画面を変更：正しいGitHub repoと作業branchを指定し、変更範囲を明示する。

・複数file、API、database、認証まで触る：architectureと契約を先に読み、変更を分割してreviewする。

・GitHub接続を使わない：v0からのhandoff内容と対象fileを指定し、既存コードを丸ごと置き換えない。

v0へ渡すのは画面目的と変更境界

指示には、画面の目的、利用者、input/output、再利用する既存component、変更禁止領域、responsive要件、完了条件を含めます。「モダンにする」だけでは、navigation、form validation、tracking、design tokenまで変わりかねません。たとえば「空状態の案を作る。既存URL query、候補ロジック、GA4 event、共通headerは変更しない。390pxで横overflowを出さず、empty/error stateを含める」と境界まで書きます。

ページ全体を一度に作り替えず、最も重要なsectionやstateから始めます。採用案ができたら見た目だけでなく、変更file、依存package、route、data model、environment variable、外部service接続を確認します。previewが動くことは、data protectionや実装の正しさを保証しません。

Handoffを差分単位で行う

v0からCursorへ渡すときは作業ownerを一つに決めます。同じbranchを同時編集すると、どちらのversionを基準に直すのか分からなくなります。v0で画面案を一区切りしたら、変更目的と差分を記録し、必要ならPRを作ります。Cursor側では最新branchを取り込み、既存component、routing、state management、CSS variableに合わせて統合します。逆にCursorからv0へ戻る場合は、基準commitを指定し、古いprototypeを最新と誤認しないようにします。

handoffメモ例：

目的：検索結果の空状態から読者が回復できるようにする。

v0で決める：spacing、card hierarchy、案内文、条件解除ボタンの位置。

Cursorで確認：実data、loading/error、keyboard操作、type、responsive。

維持する：query URL、候補ロジック、API schema、GA4 contract。

完了：typecheck、関連test、390px/1440px QA、diff review後にPR。

このメモは実装構造の答えを先に決めるものではなく、何を誰が検証するかを示します。

Cursorでは先にrepositoryを理解する

Cursor Agentはcodebaseを探索し、複数fileを編集したりterminal commandを実行したりできます。能力があるからといって、曖昧な指示でproject全体を再設計させる必要はありません。まず関連component、style、route、test、制約文書を読ませ、現状の実装経路を要約させます。その後、小さな変更から始め、diffを人が確認します。認証、billing、database migration、外部API secretのような影響範囲の大きい変更は、画面見た目の修正と混ぜず、別途レビューします。

v0由来のコードをそのまま追加する前に、既存のdesign tokenやUI primitivesを再利用できないか確認します。同じbutton、field、modalを複製すると、accessibility対応や状態変更が片方にしか反映されなくなります。不要なdependency、固定値として生成されたdata、重複CSS、未使用fileもチェックします。見た目を移植することと、architectureを移植することは別の判断です。

Previewとproduction-readyを分ける

v0 previewで成立しても、実repositoryで動くとは限りません。API/database connection、environment variable、routing、auth、browser storageには環境差があります。Cursorで統合した後はtest data、validation、loading/empty/error state、keyboard操作、狭いviewportを確認します。画面が表示されても、data権限や保存処理が正しいとは限りません。

v0がGitHubとVercel projectに接続している場合、環境変数やdeployment設定が共有されることがあります。production projectへ接続すると、previewのつもりでも本番側の設定やdeploy導線へアクセスできるため、project名、deployment target、branch、environment scopeを確認します。Production deployやmain mergeは、通常の画面案作成と切り分けます。

比較：

・v0単独prototype：UI探索。接続先dataやbusiness semanticsは別途確認。

・v0＋GitHub：既存repo同期、branch、PRを使う場合。書き込み権限とbase branchを確認。

・Cursorで統合：architecture、test、実data整合が必要な場合。repoとdiffを確認。

・両方を並行：owner、branch、handoff基準を分けられる場合のみ。

典型的な失敗を切り分ける

「v0では動いたがCursor側で崩れる」場合は、依存package、asset path、CSS framework、environment variable、routeを確認します。画面fileだけ移して、必要なproviderやserver routeを持ってこなかった可能性があります。

「Cursorがv0案を全面書き換えた」場合は、差分を分け、意図したvisual変更と不要なarchitecture変更を区別します。自動生成された大きなdiffを一括承認せず、fileごとに変更理由を確認します。

「両方で直したのに一方が戻る」場合は、同じbranchを並行編集していないか、古いcommitを基準にしていないか見ます。片方の編集を止め、Gitの最新状態を一つに決めてから再適用します。

「previewでは動くのに公開環境で失敗する」場合は、previewのenvironment variable、API permission、auth callback、backend接続をproductionと混同していないか切り分けます。secretをclient codeやcommitへコピーしないでください。

作業完了時に残すもの

最後に、画面の目的、base commit、branch、変更file、追加dependency、data/state変更、未対応の画面状態、実行test、visual確認、PR URLを記録します。未実施のbrowser QAは未実施と明記します。画面案のために作られたコードと、実際に動くproduction codeの境界が分かるよう、採用した部品と見送った案も残します。

v0とCursorは機能が重なるので、毎回両方を使う必要はありません。UI explorationを速めたいときだけv0を使い、既存appへの複数file統合やterminal validationが必要なときCursorを使うなど、作業と責任に合う方を選びます。共同作業する場合は、最新版の所在、作業owner、review担当、productionへ反映する担当を分けて記録します。

AIものさしの判断

どちらのAgentが優秀かを決めるより、source of truthを一つに保つことが重要です。既存製品へ入れる変更では、repository、branch、environment、最終diffを明示します。画面案の見た目が採用されても、既存URL、database semantics、GA4 event、accessibility、responsive behaviorが検証されるまでは完成扱いにしません。v0は探索、Cursorは統合と固定するのでなく、そのプロジェクトの責任境界に合わせて作業を割り当てます。