同期と復旧

どのコマンドをいつ使うか、同期の出力の読み方、そしてローカルのメタデータがずれたときに完全リセットへ到達する前に行うべき復旧手順の段階的な手引きについて説明します。

ローカルでのアプリ開発は同期を中心に回ります。CLI がマニフェストを再ビルドし、サーバーはそれと、すでにワークスペースに存在するメタデータとの差分だけを適用します。 このページでは、どのコマンドを使うべきか、同期で何が変更されたのかをどう読み取るか、そしてローカルの状態が一貫していないように見えるときに取るべき手順を（順番に）説明します。

​

どのコマンドをいつ使うか

日々のローカルでの反復開発では、ほとんどの場合 yarn twenty dev を使うことになります。 デプロイと公開はリリースのためのものであり、ローカルでの開発ループのためのものではありません。

やりたいこと…	コマンド	ノート
ライブ同期でローカルに反復開発する	yarn twenty dev	ファイルを監視し、変更のたびに同期します。
1 回だけ同期して終了（CI、スクリプト、フック向け）	yarn twenty dev --once	1 回ビルドして同期し、その後終了します。
変更を適用せずにプレビュー	yarn twenty dev --once --dry-run	差分を計算して表示しますが、何も書き込みません。
ワークスペースからアプリを削除する	yarn twenty app:uninstall	プロンプトをスキップするには、--yes を追加します。
サーバーに tarball をアップロードする	yarn twenty app:publish --private	package.json のバージョンが厳密により高い必要があります — Publishing を参照してください。
マーケットプレイス（npm）に公開する	yarn twenty app:publish	—
デプロイ済みバージョンをインストール / アップグレードする	yarn twenty app:install	現在デプロイされているバージョンをインストールします。
ローカルサーバーを消去してクリーンに開始する	yarn twenty docker:reset	ローカルデータをすべて削除します — 最終手段です。

​

ローカル同期ではバージョンの更新は不要

厳密に増加する version のルール（デプロイ時の VERSION_ALREADY_EXISTS、インストール時の APP_ALREADY_INSTALLED / CANNOT_DOWNGRADE_APPLICATION）は、リリースパスである app:publish / app:install に適用されます。 yarn twenty dev はマニフェストをその場で同期し、バージョン変更を要求することはないため、反復するのに package.json を触る必要はありません。 ローカルの変更をテストするためにバージョンを上げている場合は、開発ループが必要なところでリリース経路を使ってしまっています。

​

同期出力の読み方

各同期では、適用された（--dry-run の場合は適用されるはずだった）メタデータ変更が出力されます。

Metadata changes: 2 created, 1 updated, 1 deleted
  created objectMetadata rocket
  created fieldMetadata timelineActivities
  updated fieldMetadata launchedAt
  deleted pageLayout legacyTab
✓ Synced

これは最初の診断手段です。どのオブジェクト、フィールド、レイアウトが変更されたかを正確に示すので、UI を確認する前に、同期が想定どおりに動作したかを確認できます。

同期が単一のエンティティで失敗した場合、エラーには問題のエンティティとその universalIdentifier が、次のように示されます。

Migration action 'create' for 'fieldMetadata' (universalIdentifier: 2020...4337) failed

その識別子を使って、推測で衝突元を探すのではなく、マニフェスト内（必要であればワークスペース内）のエンティティを特定してください。

​

変更内容のプレビュー（ドライラン）

yarn twenty dev --once --dry-run はマニフェストをビルドし、サーバーにマイグレーションプランを問い合わせ、その内容を何も適用せずに表示します。 コミットする前に「この同期は何を変更するか？」という問いに安全に答える方法です。

yarn twenty dev --once --dry-run

Building manifest...
Computing metadata diff (dry run, nothing will be applied)...
Metadata changes: 1 created, 1 updated
  created fieldMetadata timelineActivities
  updated objectMetadata rocket
✓ Dry run complete for My App — no changes were applied

ドライランでは次のことが行われます。

• 何も書き込みません — メタデータマイグレーション、アプリケーションレコードの更新、デフォルトのロール / タブの変更、API クライアントの生成は一切行いません。
• 実際の同期が適用するのと同じ差分を返すため、作成 / 更新 / 削除されるエンティティを事前に確認できます。
• リスクの高い変更の前や、AI 生成の変更をレビューするとき、または予期せぬ変更が行われそうな場合にスクリプトを失敗させたいときなどに有用です。

ドライランではメタデータの変更のみをプレビューします。また、アプリが少なくとも一度は同期されている（ワークスペース側がその存在を知っている）必要があります。 一度も同期されていないアプリに対して実行すると、サーバーはそのアプリがインストールされていないと報告します — まず一度 yarn twenty dev を実行してください。

​

リカバリーラダー

ローカルのメタデータが正しくないように見える場合は、次の順番でエスカレートし、問題が解消したところで止めてください。 各ステップは前のものよりも影響が大きくなります。

1. 再同期。 yarn twenty dev --once を再度実行します。 同期はべき等であり、クリーンなマニフェストを再実行しても安全で、多くの場合は一時的な不具合が解消されます。
2. プランをプレビュー。 yarn twenty dev --once --dry-run を実行して、次の同期が何を変更しようとしているのかを、適用せずに正確に確認します。
3. 名前付きエラーを読む。 同期が失敗した場合は、メッセージ内のメタデータタイプと universalIdentifier（上記参照）を確認し、そのエンティティをマニフェスト内で特定します。 コンフリクトは、重複または再利用された識別子を指していることがほとんどです。
4. アンインストールして再インストール。 yarn twenty app:uninstall を実行し、その後再度同期します（yarn twenty dev）。 これにより、ワークスペースの残りを維持したまま、アプリのメタデータをクリーンな状態から再構築します。
5. フルリセット（最後の手段）。 yarn twenty docker:reset を実行し、その後再シードと再同期を行います。

yarn twenty docker:reset はローカルインスタンス内のデータをすべて削除します — すべてのワークスペース、レコード、アプリが消去されます。 それまでの手順がすべて失敗した場合にのみ使用してください。

メタデータエラーが発生しましたか？ issue を作成し、失敗したマイグレーションメッセージ（メタデータタイプと universalIdentifier を含む）、同期時の Metadata changes の出力、および実行したコマンドを記載してください。

​

1 つのワークスペースでの同時同期を避ける

同期ではメタデータマイグレーションが適用されます。 同じワークスペースに対して同時に複数の同期、デプロイ、インストール操作を実行すると（たとえば、複数のターミナルや AI エージェントが並行して反復している場合）、それらのマイグレーションが入り混じり、メタデータが一部だけ適用された状態のままになってしまう可能性があります。

サーバーはワークスペースごとに同期を直列化してこれを防いでいますが、それでも、センシティブなメタデータ操作は同時に実行するのではなく、単一のプロセスに集約するべきです。 複数のエージェントで開発をオーケストレーションしている場合は、それらの sync / deploy / install 呼び出しを 1 つのキューに流し込み、同時ではなく一度に 1 つだけ実行されるようにしてください。

​

失敗の切り分け

問題が発生したときは、メタデータの差分と名前付きエラーによって、どこで失敗したかを特定できます。

• マニフェストビルドエラー — CLI が同期前に失敗します（MANIFEST_BUILD_FAILED、TYPECHECK_FAILED）。アプリのソースを修正してください。
• 同期 / マイグレーションエラー — ビルドは成功しますが、差分の適用が失敗し、エンティティと universalIdentifier が示されます。そのコンフリクトしているメタデータを修正してください。
• アプリコードの実行時エラー — 同期自体は成功しているものの、ロジック関数やコンポーネントが実行時に正しく動作しません。function logs を確認してください。
• ローカルインスタンスの状態 — 上記のいずれにも当てはまらないのにワークスペースの見た目が依然としておかしい場合は、リカバリーラダーに従って下の段階へ進んでください。