turborepo

Turborepo

Turborepo のタスクオーケストレーション、キャッシュ、モノレポ構造、フィルター／影響範囲に基づく CI、prune／Docker、watch／dev グラフ、または turbo への移行に関わる作業では、このスキルを使用してください。

スナップショット：[email protected]、[email protected]（2026-10-01）。バージョンが異なる場合は、source-map.md から最新情報を取得してください。

ワークフロー

1. コードを変更する前に、ローカルの Turborepo の状況を確認します。
   • turbo／create-turbo のパッケージバージョン（2.x 系、スナップショットは 2.11.6）。以下の多くの機能には 2.10 以降（遅延ハッシュ計算、キャッシュの削除）、または 2.11 リリースが必要です（devEngines.packageManager、nub/aube、prune --production は 2.10.1～2.10.3 のパッチで初めて提供されました。ネイティブの Rust／Python／Go には 2.11 が必要で、タスクタグには 2.11.6 が必要です）。
   • ルートの turbo.json／turbo.jsonc、パッケージレベルの turbo.json、ワークスペースの glob、ロックファイル、devEngines.packageManager／packageManager。
   • turbo が実行するルートおよびパッケージの package.json スクリプト。
   • CI のリモートキャッシュ環境変数（TURBO_TOKEN、TURBO_TEAM）、prune／Docker の使用状況、--affected／フィルター、ルート turbo.json の futureFlags。
2. セットアップ、日常的な実行、段階的な導入、ベースライン、トラブルシューティングについては、まず完全なガイドを参照してください：usage-guide.md。
3. バージョンがスナップショットと異なる場合や、キャッシュ、環境変数のハッシュ化、prune、将来のフラグに関わる作業では、最新の公式ドキュメントを確認してください。source-map.md から始めてください。
4. 詳細情報は、以下を参照してください。
   • タスクグラフ、dependsOn／with、入力／出力、パッケージ設定：turbo-json-tasks.md。
   • turbo run、フィルター、--affected、watch、ジェネレーター：cli-filtering-watch.md。
   • ローカル／リモートキャッシュ、削除、環境変数モード、フレームワークの推論：caching-env-remote.md。
   • CI ベンダー、prune、Docker：ci-docker-prune.md。
   • 内部パッケージ、フレームワーク／ツールのグラフ、境界、パッケージマネージャー、Rust／Python／Go のツールチェーン、移行：packages-integrations.md。
5. ユーザーから移行を依頼されない限り、リポジトリのパッケージマネージャーと既存のスクリプト名を維持してください。
6. 最も範囲を絞った有用な bunx turbo run …（--dry、--filter、または --affected）で検証してください。

基本的な判断

• Turborepo は、既存の package.json スクリプトをオーケストレーションします。パッケージマネージャーではなく、ワークスペースの代替でもありません。
• CI では、タスク名と今後の CLI サブコマンドが衝突しないよう、turbo build のみではなく turbo run <tasks> を優先してください。
• キャッシュ可能なビルドタスクにはすべて outputs を宣言してください。outputs がないと、キャッシュヒットしても有用なものが復元されません。
• 依存関係のビルドには "dependsOn": ["^build"] を、同一パッケージ内の順序指定には "dependsOn": ["build"] を使用してください。混同しないでください。
• envMode のデフォルトは strict です。ハッシュに影響する変数は env / globalEnv に指定してください。値によってキャッシュが無効になってはならない場合に限り、passThroughEnv を使用します。
• 再帰は絶対に避けてください。パッケージスクリプトから、turbo がすでに実行中の同じタスクに対して turbo run を呼び出してはいけません。
• dev / watch / サーバーには "cache": false と "persistent": true を指定してください。関連する永続タスクを同時に実行するには "with" を使用します。
• 非推奨の --no-cache / --remote-only よりも、--cache=local:…,remote:… を優先してください。
• キャッシュや prune の精度を高めるため、依存関係はルートに hoist せず、使用する場所にインストールしてください。
• Turbo で TypeScript Project References を使用するよりも、並列型チェックには中継ノード（topo / transit）を優先してください。
• Lint / format ツール（Oxlint や Oxfmt など）は、ルートタスク //#lint / //#format として適していることがよくあります。
• 上流タスク（codegen）が書き出すファイルや、依存関係の出力（.d.ts）には、cache: false の代わりに遅延 inputs オブジェクト（{ "mode": "jit" } / { "mode": "dependencyOutputs" }）を使用してください。
• パッケージマネージャーは devEngines.packageManager で宣言してください（2.10.1 以降、2.11 で発表）。トップレベルの packageManager も引き続き動作しますが、将来のメジャーバージョンで削除される予定です。
• futureFlags の項目を変更するとグローバルハッシュが無効になり、すべてのタスクが一度キャッシュミスになります。設定する場合は、ルートの turbo.json のみに指定してください。
• 2.11.5 以降、turbo はコーディングエージェントを検出すると、ルートの AGENTS.md に管理対象の Turborepo ブロックを保持します（agentGuidance: true がデフォルトです）。その差分は想定されるものです。無効にするには、ルートに "agentGuidance": false を設定してください。
• Rust（Cargo）、Python（uv）、Go（go.work）のワークスペースは、将来的な実験用フラグです。ユーザーから求められない限り、本番 CI では有効にしないでください。

検証

リポジトリで定義されたコマンドを優先してください。Turborepo に関わる重要な作業では、関連する項目を検証してください。

• 高コストな実行の前に bunx turbo run <task> --dry=json または --graph で DAG を検証します。
• bunx turbo run <task> --filter=<pkg> で対象を絞って実行し、CI に近い形で検証する場合は --affected に範囲を広げます。
• キャッシュの正確性：入力または環境変数を変更した場合はミス、変更していない場合はヒットすることを確認します（ハッシュが不明瞭な場合は --summarize を使用）。
• TURBO_* または remoteCache の設定を変更した場合は、リモートキャッシュのスモークテストを行います。
• prune / Docker：デプロイグラフを変更した場合は、turbo prune <app> --docker を実行し、out/ からインストールしてビルドします。
• Watch / dev：長時間実行タスクについて、interruptible / with / persistent の動作を確認します。

実行したチェック、実行しなかったチェック、および残る turbo バージョンやリモートキャッシュに関する前提を報告してください。