bazel-build-optimization

bazel-build-optimization スキルの概要

bazel-build-optimization スキルでできること

bazel-build-optimization スキルは、大規模リポジトリで Bazel を高速化しつつ保守しやすくするための、構造化された実運用向けアドバイスをエージェントに行わせるためのスキルです。対象は実際のビルド基盤の課題です。たとえば、モノレポ構成、remote cache や remote execution の導入、遅いターゲット解析、 flaky builds、依存グラフの整理、よりスケーラブルな Bazel パターンへの移行などに向いています。

どんな人に向いているか

このスキルは、Bazel ベースのコードベースを扱う platform engineers、build engineers、infra teams、シニアアプリケーション開発者に最適です。特に、ビルド速度、キャッシュヒット率、rule 設計が無視できない規模のリポジトリで力を発揮します。以下のような支援が必要な場合に特に有効です。

• ローカルおよび CI のビルド時間を短縮したい
• package 境界を設計したい
• remote caching または execution を構成したい
• rule や target の構造を見直したい
• incremental build の遅さを調査したい
• polyrepo や mixed toolchain 構成を Bazel に移行したい

本当に解決したい仕事

多くのユーザーが必要としているのは Bazel の入門講座ではありません。欲しいのは、散らかった性能問題を見て、具体的な次の一手に落とし込めるアシスタントです。何を確認すべきか、どのファイルが重要か、どのアンチパターンを外すべきか、速度と複雑さをどうトレードオフすべきか。bazel-build-optimization skill は、汎用的な「キャッシュを使いましょう」といった助言ではなく、アーキテクチャを踏まえた最適化提案を引き出したいときに役立ちます。

汎用的な build プロンプトとの違い

違いは、Bazel 固有の概念と repo レイアウトに対する具体性です。このスキルは WORKSPACE.bazel、BUILD.bazel、labels、packages、rules、aspects といった Bazel の基本要素に根ざしており、Bazel が実際にどのようにターゲットを評価・ビルドするかに沿って最適化を組み立てます。そのため、CI 速度全般を問う広いプロンプトよりも、Performance Optimization に対して実行しやすい助言を返しやすくなります。

向いているケース・向いていないケース

実際の Bazel リポジトリがあり、明確な性能課題があり、ファイル構成・ビルドコマンド・症状のいずれかを共有できるなら、bazel-build-optimization for Performance Optimization を使う価値があります。

ただし、以下を置き換えるものではありません。

• 正確な rule 構文を確認するための公式 Bazel docs
• 組織固有の repo-specific build policies
• target 名、config、logs、timing data なしで行う低レベル診断

まだプロジェクトで Bazel を使っておらず、単に汎用的なツール比較だけがしたい場合は、このスキルはやや特化しすぎています。

bazel-build-optimization スキルの使い方

bazel-build-optimization のインストール前提

skills 互換環境で、wshobson/agents リポジトリからこのスキルをインストールします。実用的なインストールコマンドは次のとおりです。

npx skills add https://github.com/wshobson/agents --skill bazel-build-optimization

インストール後は、一般的なコーディング支援ではなく Bazel 専用の最適化支援が必要な場面で呼び出してください。

プロンプトを書く前にまず読むべきファイル

最初に確認すべきなのは次です。

• plugins/developer-essentials/skills/bazel-build-optimization/SKILL.md

このスキルは主に単一の instruction file で構成されており、重要な挙動が helper scripts や reference docs に分散しているわけではありません。まず SKILL.md を読むことで、エージェントが推論に使いやすいアーキテクチャの見方、target の概念、設定パターンの例を把握できます。

このスキルがうまく機能するために必要な入力

bazel-build-optimization usage の質は、与える入力に大きく左右されます。できるだけ次の情報を渡してください。

• 使用している Bazel version
• WORKSPACE.bazel と bzlmod のどちらを使っているか、または両方か
• repo レイアウトの簡単な説明
• bazel build //... や特定 target など、遅いコマンドを 1 つ以上
• 遅さが出ている箇所: analysis、fetch、compile、test、link、remote execution のどれか
• CI とローカルで挙動が違うか
• .bazelrc、ルートの BUILD.bazel、代表的な package の BUILD.bazel などの関連ファイル

この文脈がないと、エージェントは広く浅いヒューリスティックしか返せません。

曖昧な目的を強いプロンプトに変える

弱いプロンプト:

Help optimize our Bazel build.

より強いプロンプト:

Use the bazel-build-optimization skill. We have a monorepo with apps/ and libs/, Bazel 7, remote cache enabled but poor cache hit rates in CI. Incremental builds are slow after changes in libs/utils. Review this .bazelrc, root BUILD.bazel, and libs/utils/BUILD.bazel. Identify likely dependency and target-graph issues, suggest a prioritized remediation plan, and show what to measure before and after.

後者が機能しやすいのは、スキルに対して topology、症状、調査範囲、成功条件を明確に渡しているからです。

推奨だけでなく診断を求める

最もよい進め方は、まず問題の分類をさせ、その後で修正案を出させることです。たとえば次の流れです。

1. まずボトルネックのカテゴリを特定する
2. package と target の構造を点検する
3. 効果が大きく変更量が小さいものから提案する
4. 検証手順を定義する

こうすると、エージェントが根拠の薄い rule 書き換え案にいきなり飛びつくのを防げます。

実用的で通りやすいプロンプトパターン

次のようなパターンは比較的うまく機能します。

• Audit these BUILD files for over-broad dependencies and target granularity issues.
• Propose a remote caching rollout checklist for this Bazel monorepo.
• Explain why this target likely invalidates too much of the graph.
• Compare current layout against a better package structure.
• Help migrate this repo to more scalable Bazel conventions without breaking CI.

これらの依頼は、このスキルが本来カバーしている範囲とよく一致しています。

エージェントに共有するとよいリポジトリファイル

高品質な bazel-build-optimization install と活用につなげるには、次のファイルが特に有用です。

• .bazelrc
• .bazelversion
• WORKSPACE.bazel
• ルートの BUILD.bazel
• 遅い箇所にある代表的な BUILD.bazel をいくつか
• tools/bazel/rules/ などにある custom rule files
• CI logs から取った、失敗または低速なコマンド例

1 つしか共有できないなら、遅いコマンドと、その target に関係する BUILD files を優先してください。

期待できる出力

よい bazel-build-optimization guide 型の回答には、次の要素が含まれるはずです。

• 一般論ではなく、ありそうな root causes
• 優先順位付きの変更案とその理由
• あなたの repo に結びついた Bazel-specific terminology
• 必要に応じた config やファイル修正例
• 改善を確認するための measurement plan

回答が target graph との関係に触れず、単に「enable cache」「split modules」とだけ言うなら、入力情報が足りていない可能性が高いです。

このスキルが価値を出しやすい典型ワークフロー

このスキルは、特に次のワークフローで有効です。

• monorepo 導入計画
• 初回の remote cache または remote execution セットアップ
• CI build time の短縮
• target と package のリファクタリング
• custom rule design のレビュー
• ad hoc scripts から Bazel-native structure への移行

一方で、単発の構文質問にはあまり向きません。そうした場合は公式 docs のほうが早いことがあります。

助言を採用する前に考えるべきトレードオフ

Bazel の最適化では、シンプルさと速度のトレードオフがしばしば発生します。エージェントには、たとえば次のような論点を明示させるとよいです。

• より細かい target 分割 vs 保守コストの増加
• remote execution の利点 vs infra の複雑さ
• custom rules vs 標準 rule ecosystem
• 積極的な caching vs 再現性とデバッグのしやすさ

重要なのは、このスキルは最適化を手助けできても、どの程度の運用負荷を受け入れるかを決めるのは最終的に自分たちだという点です。

bazel-build-optimization スキル FAQ

bazel-build-optimization は初心者にも向いていますか？

はい。すでに Bazel repo があり、入門コースよりもガイド付きの思考整理が必要な人には向いています。targets、packages、labels、rules といった基本概念には触れますが、ゼロから Bazel を学ぶための教材というより、実務の最適化支援に強いスキルです。

通常のプロンプトではなく、いつこれを使うべきですか？

問題が Bazel architecture、build graph 設計、remote cache / execution、モノレポのスケーリングに関わるなら bazel-build-optimization を使う価値があります。通常のプロンプトでもアイデア出しはできますが、このスキルのほうが Bazel の性能を実際に左右するファイルや概念に沿って回答を組み立てやすくなります。

remote caching や remote execution の支援にも使えますか？

はい。元の内容でも、remote caching と remote execution の構成は明確に想定ユースケースに含まれています。そこが目的なら、現在の cache 設定、CI の挙動、auth model、cache hit / miss の症状を一緒に渡してください。

Bazel への移行にも役立ちますか？

はい。特に大きなコードベースを Bazel に寄せていくチームには有用です。移行時の repository structure、package boundaries、dependency management、build-performance 面の検討に役立ちます。

このスキルは巨大な enterprise monorepo 専用ですか？

いいえ。ただし、そのような環境が最も得意です。より小さな repo でも、build graph 設計、target 境界、remote cache の挙動が重要なら恩恵があります。逆に target が数個しかない非常に小さな repo では、Bazel 固有の最適化にかかる手間のほうが効果を上回ることがあります。

このスキルがあまり得意でないことは何ですか？

このスキルには、repo 固有の automation、profiling scripts、enforcement rules は付属していません。ガイダンスやテンプレートは示せますが、ファイル・コマンド・症状を渡さない限り、あなたの build system を自動で精査してくれるわけではありません。

SKILL.md を直接読むのと何が違いますか？

SKILL.md を読むと、パターンや例は把握できます。一方、エージェント経由で bazel-build-optimization skill を使う価値は、それらのパターンを自分で翻訳し直すのではなく、あなたの repo、制約、性能課題に合わせて適用してもらえる点にあります。

bazel-build-optimization スキルを改善するには

意見ではなく性能の根拠を渡す

bazel-build-optimization usage の質を最も早く高める方法は、根拠を渡すことです。

• 遅いコマンド
• timing の差分
• ローカルと CI の違い
• cache hit-rate の観測結果
• 代表的な BUILD files

こうした情報があれば、エージェントは一般的な Bazel のベストプラクティスを繰り返すのではなく、実際の症状に基づいて推論できます。

まず 1 つの target path に範囲を絞る

問題が本当に全体的なものでない限り、最初から //... を対象にしないでください。1 つの遅い package、1 つの flaky test target、1 つの問題ある dependency 領域から始めたほうが、プロンプトの質は上がります。絞ったケースでうまくいったら、同じパターンを repo 全体に広げるのが効果的です。

期待効果つきで優先順位を付けさせる

改善に効く強いプロンプトの例:

Use the bazel-build-optimization skill and rank the top 5 changes by likely impact, implementation cost, and risk. Include how each change should affect analysis time, cacheability, or incremental rebuild behavior.

こう依頼すると、順不同の checklist ではなく、意思決定に使える形の出力を引き出せます。

要約ではなく実際のファイル内容を共有する

可能なら、実際の .bazelrc、WORKSPACE.bazel、BUILD.bazel の断片を貼ってください。Bazel では、細かな syntax や構造の違いが挙動を大きく左右します。要約ベースの説明では、肝心の問題が抜け落ちがちです。

変更前後の検証手順も要求する

出力への信頼性を高めるには、スキルに次を含めるよう求めてください。

• 変更前に何を測るべきか
• 最初に何を変えるべきか
• 各ステップ後にどうなれば成功か
• どんな兆候があればロールバックを検討すべきか

こうすると助言が単発の提案一覧ではなく、最適化のループとして機能します。

よくある失敗パターンに注意する

このスキルの精度が出にくい主な理由は次のとおりです。

• target 名やコマンドが共有されていない
• ローカルの問題と CI の問題が区別されていない
• 具体的なボトルネックなしに「best practices」だけを求めている
• build graph を形作る custom rules や macros を隠している
• 現在の config を見せずに正確な syntax を期待している

回答が抽象的に感じられるなら、たいていはプロンプトが抽象的すぎます。

最初の回答のあとで反復する

初回の回答を受けたら、次のような形で続けると効果的です。

• Here is the current BUILD file after change 1. What remains problematic?
• Cache hit rates improved locally but not in CI. Reassess likely causes.
• We cannot use remote execution. Re-rank the optimization plan.

通常、bazel-build-optimization for Performance Optimization の価値がより具体的に出てくるのは、この 2 回目以降のやり取りです。

自分たちの環境でのトレードオフ説明を求める

チームが developer experience、CI cost、migration risk を重視するなら、その点を明示してください。bazel-build-optimization skill の出力品質を上げる最善の方法は、最適化の目的を明確にすることです。最速の CI を求めるのか、ローカル反復を速くしたいのか、保守性を優先するのか、安全な移行を重視するのかで、推奨は変わります。