turborepo-caching

turborepo-caching スキルの概要

turborepo-caching でできること

turborepo-caching は、Turborepo の設定を通じて、ビルド・テスト・lint の再実行時に毎回計算し直すのではなく、結果を再利用できるようにする実践的なスキルです。単に「キャッシュを有効化する」ことが目的ではなく、タスクの入力・出力・依存関係・環境変数への感度を適切に定義し、古い成果物を返さない形でローカル実行と CI の両方を高速化するのが、turborepo-caching の本質です。

このスキルが向いている人

このスキルは、Turborepo を使った JavaScript / TypeScript のモノレポを運用していて、次のような課題を持つチームに特に向いています。

• turbo.json を最初から正しく設計したい
• CI や複数開発者向けに remote caching を導入したい
• キャッシュミスが原因の遅いビルドを減らしたい
• ばらつきのあるスクリプト運用から、再現性のあるタスクパイプラインへ移行したい

特に、リポジトリの構成自体は把握しているものの、それを Turborepo のキャッシュモデルでどう表現すべきか自信がない場合に役立ちます。

turborepo-caching を導入する価値

turborepo-caching の強みは、実運用でつまずきやすい論点を整理してくれる点にあります。

• どのファイルを outputs に含めるべきか
• dependsOn で ^build を使うべき場面と、タスク単位の順序制御で足りる場面
• .env ファイルや環境変数がキャッシュの正しさにどう影響するか
• persistent なタスクを、なぜキャッシュ可能なビルド手順として扱うべきでないのか
• CI/CD におけるローカルキャッシュと remote caching をどう考え分けるか

そのため、単なる「モノレポを最適化したい」という汎用プロンプトよりも、Turborepo の実際のパイプラインの仕組みに即して判断しやすいのが、このスキルの価値です。

このスキルで置き換えられないもの

これは Turborepo の完全なリファレンスではなく、リポジトリを自動で解析してくれるものでもありません。現在の turbo.json、各タスクのスクリプト、package の配置、ビルド成果物の出力先は、引き続き自分で渡す必要があります。そもそも Turborepo を使っていないスタックであれば、このスキルは適していません。

turborepo-caching スキルの使い方

turborepo-caching の導入コンテキスト

上流のスキルは SKILL.md 内に専用インストーラーを含んでいないため、wshobson/agents リポジトリに対する通常のスキル導入フローを使い、その後エージェント環境で turborepo-caching を名前指定で呼び出してください。

GitHub ソースに対応した skill loader を使っている場合、対象のリポジトリパスは以下です。

https://github.com/wshobson/agents/tree/main/plugins/developer-essentials/skills/turborepo-caching

最初に読むべきファイル

まず確認すべきなのは次のファイルです。

• plugins/developer-essentials/skills/turborepo-caching/SKILL.md

このスキルは自己完結型です。スキルフォルダ内に補助的な rules/、resources/、ヘルパースクリプトはなく、実用的なガイダンスの大半はこの 1 ファイルにまとまっています。

turborepo-caching に渡すべき入力情報

turborepo-caching をしっかり活用するには、「何とか高速化したい」のような目標だけでなく、リポジトリの具体情報を渡すことが重要です。最低限、次の情報があると実用的です。

• 現在の turbo.json
• ルートの package.json
• 代表的な workspace の package.json を 1〜2 個
• 各 app / package が使っているビルドツール。たとえば Next.js、Vite、tsup、Jest
• どのタスクをキャッシュ対象にしたいか
• dist/、build/、.next/、coverage 系フォルダなど、想定する出力先
• 利用している CI プロバイダと、remote caching を使いたいかどうか

これらがないと、エージェントが返せるのは汎用テンプレート止まりになりがちです。

ざっくりした要望を強いプロンプトに変える

弱いプロンプト:

Help me optimize Turborepo caching.

より強いプロンプト:

Use the turborepo-caching skill to review my monorepo pipeline. I have apps/web with Next.js, packages/ui with tsup, and packages/config with TypeScript build scripts. Here is my current turbo.json and package scripts. I want faster CI builds, safe remote caching, and fewer cache misses when only UI code changes. Propose a revised turbo.json, explain each outputs entry, identify env vars that should affect cache keys, and call out any tasks that should not be cached.

このプロンプトが有効なのは、具体的な成果物を求めつつ、依存関係の全体像と成功条件を明示しているからです。

こうした出力を明示的に依頼する

turborepo-caching は、次のような成果物を 1 つ以上明示して依頼すると、特に使いやすくなります。

• 改訂版の turbo.json
• タスクごとのキャッシュ可否レビュー
• outputs の監査
• 環境変数の監査
• CI 向け remote caching 設定ガイダンス
• キャッシュミス調査用のチェックリスト

こうしておくと、広すぎる設計論に流れず、実際に適用できる設定案を引き出しやすくなります。

turborepo-caching の典型的な進め方

実践的な進め方は次のとおりです。

1. 現在のモノレポ構成とスクリプトを共有する。
2. タスクを build、test、lint、dev、persistent task に分類してもらう。
3. turbo.json を新規作成または見直してもらう。
4. すべての outputs、dependsOn、inputs、env 関連の判断理由を説明してもらう。
5. ローカルでタスクを実行し、キャッシュヒットとミスを比較する。
6. ログや境界ケースを持ち帰って、2 回目の見直しを行う。

レビュー工程は重要です。キャッシュが機能しない原因の多くは、出力先の見落としや、入力条件に関する暗黙の前提ミスにあります。

リポジトリを見るときに重視すべき考え方

このスキルでは、使い方の軸になる概念として次の点が重視されています。

• dependsOn は実行順序と上流ビルドとの関係を制御する
• outputs は Turborepo がキャッシュから復元できる成果物の範囲を決める
• inputs と global dependencies は、どの変更でキャッシュ結果を無効化するかを決める
• persistent は長時間動き続けるタスク向けであり、通常のビルドとは別のモデリングが必要になる

プロンプト内でこれらに触れていないと、遅いビルドの本当の原因を取りこぼしやすくなります。

turborepo-caching での良いレビュー依頼例

たとえば、次のような依頼が有効です。

Apply the turborepo-caching skill to this turbo.json. Tell me which tasks are unsafe to cache, whether .next/** is too broad for my Next.js app, whether !.next/cache/** should be excluded, and whether my .env.local and VERCEL_URL should be in globalDependencies or globalEnv. Then propose a corrected config.

これは単に「ベストプラクティスを教えて」と聞くよりも強力です。正しさを左右する具体的な設定ポイントに直接フォーカスできるためです。

問い合わせ前にリポジトリで確認しておくこと

turborepo-caching を呼び出す前に、次の点を確認しておくと効果的です。

• 各 package が成果物を安定したフォルダに出力しているか
• 生成ファイルが分かりやすい出力フォルダの外に出ていないか
• ビルドスクリプトが .env や CI 専用変数を参照していないか
• テストが snapshot、レポート、coverage 出力を生成していないか
• 非決定的なスクリプトが含まれていないか

出力が不安定だったり入力が隠れていたりすると、turbo.json 自体が正しくても、キャッシュが壊れているように見えてしまいます。

よくある導入・定着の障害

最大の障害は、ほとんど情報を渡さずに、このスキルがタスクグラフを推測してくれると期待してしまうことです。次によくあるのが、すべてのスクリプトをキャッシュ対象として扱ってしまうことです。開発サーバー、watch mode、その他の persistent なプロセスは、通常は別の扱いが必要です。さらに見落とされやすいのが、環境変数がキャッシュキーを変えうるという点で、とくにフロントエンドのビルドでは重要です。

turborepo-caching スキル FAQ

turborepo-caching は初心者にも有用ですか

はい。すでに Turborepo ベースのリポジトリを使っている、または Turborepo を使う方針が固まっているなら有用です。初心者が混同しやすい outputs、dependsOn、env 由来の無効化ルールに整理を与えてくれます。一方で、そもそもモノレポツールを採用するかどうかを検討している段階では、あまり効果的ではありません。

普通のプロンプトと何が違うのですか

通常のプロンプトだと、モノレポ一般論に寄った助言になりがちです。turborepo-caching はもっと対象が絞られていて、Turborepo のパイプライン設定と、本番運用を見据えたキャッシュ設計に焦点があります。その分、turbo.json の提案精度や、キャッシュミスの切り分けは良くなりやすいです。

どんな場合は turborepo-caching を使わないほうがよいですか

次のような場合は、このスキルは見送ったほうがよいでしょう。

• リポジトリが Turborepo を使っていない
• キャッシュ設計よりも package manager のセットアップ支援が必要
• 主な問題がビルドの正しさとは別のところにある
• タスクキャッシュではなく、フレームワーク固有のデプロイ指針が欲しい

これは設定支援のスキルであり、あらゆる性能問題を解決する万能ツールではありません。

remote caching もカバーしていますか

はい、判断レベルではカバーしています。元の内容でも、remote caching と CI/CD 最適化は明確なユースケースに含まれています。ただし、利用する CI プラットフォーム、シークレット管理上の制約、開発者間でキャッシュ成果物を共有したいかどうかは、自分で渡す必要があります。

turborepo-caching はキャッシュミスの調査にも使えますか

はい。むしろ実務上かなり有用な用途のひとつです。たとえば次の観点をレビューできます。

• outputs の不足または広すぎる指定
• 隠れたファイル依存や env 依存
• 不適切なタスク境界
• キャッシュ不向き、または persistent なタスクを通常ビルドとして扱っている問題

デバッグ目的なら、「本来キャッシュヒットするはずなのにしなかった」実例を添えるのが効果的です。

turborepo-caching は大規模モノレポ専用ですか

いいえ。小規模なモノレポでも、ビルド頻度が高い、あるいは CI コストが重いなら十分に効果があります。package、app、パイプラインの数が増えるほど価値は上がりますが、Web アプリと共通 package がある程度の構成でも十分使えます。

turborepo-caching スキルをより良く使うには

実際のタスクグラフをエージェントに渡す

turborepo-caching の精度を最も早く上げる方法は、実際のスクリプトと package 間の関係をそのまま渡すことです。どの package がどれに依存しているか、どのタスクが上流のビルド成果物を利用するかまで含めて共有してください。曖昧な説明だけだと、安全性に欠ける汎用キャッシュ設定になりがちです。

outputs を具体的に伝える

弱い結果の多くは、出力ディレクトリの情報不足が原因です。各タスクが何を書き出すのかを、正確に伝えてください。たとえば次のようにです。

• apps/web build writes .next/
• packages/ui build writes dist/
• packages/config build writes generated .js and .d.ts files in lib/

こうしておくと、推測ベースではない、実際に使える outputs 一覧を出しやすくなります。

環境依存の挙動を先に表に出す

パフォーマンス最適化のために turborepo-caching を使う場合、正しさが崩れやすいのは env の扱いです。次の情報を列挙してください。

• ビルド時に使う env vars
• CI 専用の vars
• フロントエンド公開用の vars
• 出力結果に影響する .env ファイル

そして、どの値がキャッシュキーに影響すべきか、どれは影響させるべきでないかを分けて判断してもらってください。

キャッシュ不可タスクと persistent task を早めに明示する

よくある失敗は、「全部キャッシュすればよい」と考えてしまうことです。次のようなタスクがあるなら、最初に伝えておくと結果が良くなります。

• watch mode
• ローカル開発サーバー
• 長時間動作するバックグラウンドプロセス
• デプロイのような副作用を持つスクリプト

これにより、persistent なタスクを通常のビルド手順として誤ってモデリングするのを避けやすくなります。

設定だけでなく理由も求める

turborepo-caching を使うなら、設定のダンプだけで終わらせず、主要フィールドごとの理由も必ず求めるのが有効です。たとえば次のように依頼します。

Revise my turbo.json and explain why each task has cache, outputs, and dependsOn configured the way it is. Flag any assumptions you had to make.

この形にすると、適用前に誤りや危険な前提を見つけやすくなります。

実行後に 2 回目の見直しを行う

最初の出力を受け取ったら、実際にタスクを走らせて観測結果を持ち帰ってください。

• どのコマンドがキャッシュヒットしたか
• どのコマンドが想定外にミスしたか
• 復元された成果物が正しいか
• CI とローカルで結果が違うか

2 回目の見直しでこそ、このスキルの価値が出やすくなります。実際のキャッシュミスには、初回設定だけでは推測できない隠れた入力条件が表れるからです。

安全重視の精密設定と広めのキャッシュ設定を比較してもらう

turborepo-caching を詰めるときは、次の 2 案を比較するよう依頼すると有効です。

• 無効化条件を厳密にした保守的な設定
• キャッシュ再利用を最大化する攻めた設定

「ベストな設定」を 1 つだけ求めるより、この比較のほうが意思決定に向いています。古い成果物を許容できるか、計算コストをどこまで下げたいかで、最適解は変わるためです。

プロンプトは測定可能な成果に結びつける

改善依頼では、次のような具体的な目標を含めると効果的です。

• CI のビルド時間を 40% 短縮したい
• docs だけ変更したときは apps/web を再ビルドしたくない
• 開発者間でビルドキャッシュを共有したい
• 変更のない package でテストを繰り返し実行しないようにしたい

測定可能な目標があると、よりシンプルな設計にするか、より細かく制御するかをエージェントが判断しやすくなります。