sync-provider

同期プロバイダー

ローカルのカスタマイズを保持しながら、クローンしたプロバイダーリポジトリの変更を同期します。

概要

ほとんどのプロバイダー（opencodeを除く）は外部リポジトリからクローンされるため、上流の変更と同期する必要があります。このスキルでは、更新の確認から変更の安全な適用まで、ワークフロー全体を説明します。

前提条件

1. GitHub CLI（gh）：インストールされ、認証されている必要があります

   gh --version
   gh auth login
   gh auth status
   

2. GitHub トークン：ルートの.envファイルにGITHUB_TOKENを追加します

   GITHUB_TOKEN=your_token_here
   

3. リポジトリ情報：各プロバイダーのpackage.jsonには、repository.urlフィールドが含まれています（形式：https://github.com/owner/repo-name）

ワークフロー

ステップ 1：プロバイダーとリポジトリを特定する

プロバイダーのpackage.jsonでリポジトリの URL を確認します。

cat providers/<provider>/package.json | grep -A 2 repository

owner/repo形式を抽出します：https://github.com/owner/repo-name → owner/repo-name

ステップ 2：新しいコミットを確認する

check-provider-commit.shを使って、新しいコミットがあるか自動的に確認します。

COMMIT_HASH=$(scripts/check-provider-commit.sh <provider> 2>/dev/null)
EXIT_CODE=$?

if [ $EXIT_CODE -eq 0 ] && [ -n "$COMMIT_HASH" ]; then
  echo "Proceeding with sync from commit: $COMMIT_HASH"
elif [ $EXIT_CODE -eq 0 ]; then
  echo "Already up to date - no sync needed"
  exit 0
else
  echo "No state file found - need to determine initial commit hash manually"
  exit 1
fi

スクリプトの動作：

• 最新の状態：コード0で終了し、「Already up to date」と表示します
• 新しいコミットあり：コミットハッシュ（最後に同期したもの）を出力し、コード0で終了します
• 状態ファイルなし：コード1で終了し、最新のコミットを表示します（初回同期では手動での判断が必要です）

**重要：**コミットハッシュを取得する際は、情報メッセージが混在しないように、標準エラー出力をリダイレクトします（2>/dev/null）。

ステップ 3：Git 差分スクリプトを実行する

適切なパラメーターを指定して同期スクリプトを実行します。

REPO=$(cat providers/<provider>/package.json | grep -A 2 repository | grep url | cut -d'"' -f4 | sed 's|https://github.com/||')

pnpm exec tsx scripts/git-diff.ts \
  -r $REPO \
  -c "$COMMIT_HASH" \
  -i "src/**/*" \
  -i "docs/**/*" \
  -i "examples/**/*" \
  --state-file-path ./providers/<provider>/diff_last_commit.txt

パラメーター：

• -r, --repo：owner/repo形式の GitHub リポジトリ（必須）
• -c, --commit：比較元のコミットハッシュ（必須）— 状態ファイルに記録された最後の同期コミットを使用します
• -i, --include：ファイルを絞り込むグロブパターン（複数回指定できます）
  • 次の3つのデフォルトパターンを必ず使用してください：
    • src/**/* — すべてのソースファイル
    • docs/**/* — ドキュメントファイル
    • examples/**/* — サンプルファイル
• --state-file-path：最後に同期したコミットハッシュを保存するパス

ステップ 4：詳細な調査と分析

**必須：**変更を適用する前に、詳細な調査を実施してください。

# List all generated diff files
ls -R .diffs/<commit_hash>/

# Review all diffs to understand scope
find .diffs/<commit_hash>/ -name "*.txt" -exec echo "=== {} ===" \; -exec cat {} \;

# Get list of affected files
find .diffs/<commit_hash>/ -name "*.txt" | sed "s|\.diffs/<commit_hash>/||" | sed 's|\.txt$||'

調査手順：

1. すべての差分を分析する：各差分ファイルを確認し、次の内容を把握します。

   • 変更、追加、削除されるファイル
   • 変更の内容（バグ修正、機能、リファクタリング、破壊的変更）
   • 既存のローカルカスタマイズへの影響
   • 変更間の依存関係

2. ローカルのカスタマイズを確認する：現在のローカルファイルを確認し、次の内容を特定します。

   • 競合する可能性のあるカスタム変更
   • 保持すべきローカルの追加内容
   • 設定の違い

3. プロジェクトルールを確認する：必須の手順 — .cursor/rulesを確認し、次の内容を把握します。

   • このプロバイダーに適用されるルール（TypeScript、React など）
   • プロジェクトの標準とパターン
   • 関連する技術のベストプラクティス

ステップ 5：Pal MCP を使用したリファクタリング計画の作成

必須：Pal MCP のリファクターツールを Gemini 3.0 Pro とともに使用して、包括的な計画を作成します。

- **タスクの無効化**：Pal のリファクターツールのすべてのステップを完了する前にファイルを編集すると、**タスクは無効になります** - **例外なし**：ファイルに触れる前に、Pal のリファクターワークフロー全体（`next_step_required: false` になるまでのすべてのステップ）を必ず完了してください - **検証**：Pal のリファクターステップがすべて完了したという確認を受け取ってから、ステップ 7 に進んでください

リファクターツールの使用方法：

1. 関連ファイルの特定：影響を受けるファイルをすべて収集します。

   • 変更がある .diffs/<commit_hash>/ 内のファイル
   • 変更されたファイルに対応する、providers/<provider>/ 内の現在のローカルファイル
   • すべてのファイルに完全な絶対パスを使用します

2. Pal のリファクター分析の実行：

   // Use mcp_zen_refactor with:
   // - model: "gemini-3.0-pro" or "anthropic/claude-opus-4.6"
   // - relevant_files: Array of absolute paths to affected files
   // - refactor_type: "modernize" or "organization" (as appropriate)
   // - focus_areas: ["sync-upstream-changes", "preserve-local-customizations"]
   

3. すべてのステップの完了：必須 — next_step_required: false になるまで、すべてのステップを完了します

   • すべてのステップが完了したという確認を受け取るまで、リファクターツールの呼び出しを続けます
   • 確認を受け取るまで、ファイルの編集に進まないでください
   • このステップを省略すると、タスクは無効になります

4. リファクタリングの推奨事項の確認：ツールから次の内容が提示されます。

   • 変更を適用する最適な方法
   • ローカルのカスタマイズを維持する方法
   • 起こり得る競合とその解決方法
   • コード品質の改善
   • アーキテクチャに関する考慮事項

リファクターツールの要件：

• モデル：gemini-3.0-pro または anthropic/claude-opus-4.6 を必ず使用します
• 複数ステップ：next_step_required: false になるまで、すべてのステップを完了します。例外はありません
• ファイルパス：完全な絶対パスを使用します（例：/Users/pedronauck/Dev/compozy/compozy-code/providers/claude-code/src/index.ts）
• 重点領域：ローカルのカスタマイズを維持しながら上流の変更を同期するためのコンテキストを含めます
• 完了の確認：ツールですべてのステップの完了が確認されてから進みます

ステップ 6：実装計画の作成

Pal のリファクター分析に基づいて、詳細な実装計画を作成します。

1. 変更の優先順位付け：依存関係（依存関係を先に適用）、リスクレベル（低リスクを先に）、影響度（重要なファイルを先に）に基づいて順序を決めます

2. 競合の特定：上流の変更と競合するローカルのカスタマイズがあるファイル、各競合の解決方針、維持する内容と更新する内容についての判断を記録します

3. テスト戦略の計画：各変更後に実行するテスト、ローカルのカスタマイズが維持されていることの検証方法、テストすべき統合箇所を定義します

4. 判断の記録：特定の変更を適用またはスキップする理由、ローカルのカスタマイズを維持する方法、行ったアーキテクチャ上の判断を記録します

ステップ 7：計画に従って変更を適用

- **検証が必要**：先に進む前に、次の点を確認してください。 1. Pal のリファクターステップがすべて完了している（`next_step_required: false`） 2. リファクタリング分析と推奨事項をすべて受け取っている 3. 詳細な実装計画を作成している（ステップ 6） - **タスクの無効化**：Pal のリファクターステップをすべて完了する前にファイルの編集を始めると、**タスクは無効になります** - **例外なし**：変更内容を理解していると思っていても、Pal のリファクターワークフロー全体を必ず完了してください

ステップ 4～6 を完了し、Pal のリファクター完了を確認してから、変更を適用します。

1. 変更されたファイル：ローカルのカスタマイズを維持しながら、リファクター計画に従って変更を適用します
2. 追加されたファイル：プロジェクトの標準に従って新しいファイルを追加します
3. 削除されたファイル：削除をローカルに適用すべきか評価します（維持が必要な場合もあります）
4. 名前が変更されたファイル：計画に従って、名前の変更と内容の変更に対応します

ベストプラクティス：

• 優先順位を付けた計画に従い、段階的に変更を適用します
• 重要な変更ごとにテストを実行します
• 計画で特定したローカルのカスタマイズを維持します
• 計画から逸脱した場合は、その内容を記録します

ステップ 8：状態ファイルを更新する

変更を正常に適用した後、状態ファイルが更新されたことを確認します。

cat providers/<provider>/diff_last_commit.txt
# Should contain the latest commit hash that was synced

ワークフローの例

claude-code プロバイダーの同期

# 1. Check repository info
cat providers/claude-code/package.json | grep repository

# 2. Check for new commits
COMMIT_HASH=$(scripts/check-provider-commit.sh claude-code 2>/dev/null)
EXIT_CODE=$?

if [ $EXIT_CODE -ne 0 ]; then
  echo "⚠️  No state file found - need to determine initial commit hash manually"
  exit 1
elif [ -z "$COMMIT_HASH" ]; then
  echo "✅ Already up to date - no sync needed"
  exit 0
fi

# 3. Extract repository name
REPO=$(cat providers/claude-code/package.json | grep -A 2 repository | grep url | cut -d'"' -f4 | sed 's|https://github.com/||')

# 4. Run sync script
pnpm exec tsx scripts/git-diff.ts \
  -r $REPO \
  -c "$COMMIT_HASH" \
  -i "src/**/*" \
  -i "docs/**/*" \
  -i "examples/**/*" \
  --state-file-path ./providers/claude-code/diff_last_commit.txt

# 5. Deep research and analysis
find .diffs/$COMMIT_HASH/ -name "*.txt" -exec echo "=== {} ===" \; -exec cat {} \;

# 6. Use Pal MCP refactor tool (complete all steps)
# 7. Create implementation plan
# 8. Apply changes according to plan
# 9. Verify state file updated
cat providers/claude-code/diff_last_commit.txt

利用可能なプロバイダー

プロバイダー	リポジトリ	備考
claude-code	ben-vargas/ai-sdk-provider-claude-code	クローン済み
gemini	ben-vargas/ai-sdk-provider-gemini-cli	クローン済み
codex	ben-vargas/ai-sdk-provider-codex-cli	クローン済み
opencode	N/A	ローカルで作成済み - 同期不要

重要な要件

- 新しいコミットを同期前に自動で確認するため、**必ず** `gh` CLI を使用してください - スクリプトを実行する前に、`package.json` からリポジトリの URL を**必ず**確認してください - デフォルトのインクルードパターンを 3 つすべて使用してください：`src/**/*`、`docs/**/*`、`examples/**/*` - `-c` パラメーターには、状態ファイルに記載されたコミットハッシュ（最後に同期したコミット）を**必ず**使用してください - 計画を作成する前に、すべての差分を詳細に調査・分析してください - 適用されるルールを把握するため、`.cursor/rules` ファイルを**必ず**確認してください（必須ステップ） - 最適な変更の適用方法を確認するため、Gemini 3.0 Pro と Pal MCP リファクターツールを**必ず**使用してください - Pal リファクターツールのすべてのステップを完了してください。処理を途中で止めないでください - ファイルを編集する前に、Pal リファクターが完了していること（`next_step_required: false`）を**必ず**確認してください - 変更を適用する前に、リファクター分析に基づく詳細な実装計画を**必ず**作成してください - Pal MCP ツールを使用する際は、**必ず**完全な絶対パスを使用してください（相対パスは使用しないでください） - 上流の変更を適用する際は、ローカルのカスタマイズを保持してください - 変更を適用した後、プロバイダーをテストしてください（プロバイダーディレクトリで `pnpm test` を実行） - 変更を適用した後、Lint と型チェックを実行してください（`pnpm run lint && pnpm run typecheck`） - プロバイダーディレクトリ構造に合わせて、状態ファイルのパスを更新してください - `opencode` プロバイダーはローカルで作成され、クローンされていないため、**絶対に**同期しないでください - 詳細な調査と計画を行わずに、**絶対に**変更を直接適用しないでください - Pal リファクターのすべてのステップが完了する前に、**絶対に**ファイルの編集を始めないでください - 回避策は**絶対に**使わず、常に優れた設計のソリューションを優先してください - リポジトリは**必ず**正確な形式 `owner/repo-name` を使用してください（`https://github.com/` のプレフィックスは付けないでください） - 計画前に `.diffs//` フォルダーが存在し、想定されるファイルが含まれていることを**必ず**確認してください - `gh` CLI が認証済みであることを**必ず**確認してください（`gh auth status`） - グリーンフィールドの方針に**必ず**従ってください。後方互換性は考慮せず、品質を優先してください - タスクに適用される `.cursor/rules` のルールを、作業開始前に**必ず**再確認してください（必須ステップ）

トラブルシューティング

glob パターンに一致するファイルがない

• コミットハッシュが正しいか確認してください
• リポジトリ名の形式を確認してください
• **/* のようなより広いパターンを使って、すべての変更を確認してください

状態ファイルが見つからない

• 初回の同期：クローン時の初期コミットハッシュを使用してください
• 2 回目以降の同期：スクリプトが状態ファイルを自動で作成します

バイナリファイルが検出された

バイナリファイルは .diffs/<commit_hash>/<file-path>.txt に記録されますが、差分は作成されません。手動で対処してください：

• 画像：GitHub で確認するか、直接ダウンロードしてください
• その他のバイナリ：更新が必要か判断してください

GitHub API のレート制限

• 再試行する前に待ってください
• レート制限の上限が高い GitHub トークンを使用してください
• 小さな単位に分けて同期することを検討してください

同期後

• 必ずテストしてください：プロバイダーディレクトリでテストを実行します。

  cd providers/<provider>
  pnpm test
  pnpm run lint
  pnpm run typecheck
  

• 必ず確認してください：すべての変更が正しく適用され、ローカルのカスタマイズが失われていないことを確認します。

• 必ず記録してください：同期プロセス中に行った判断を記録します。特に、以下を記録してください。

  • 解決した競合
  • 維持したローカルのカスタマイズ
  • アップストリームの変更からの逸脱
  • アーキテクチャ上の判断