bazel-build-optimization

bazel-build-optimization 技能概览

bazel-build-optimization 技能能做什么

bazel-build-optimization 技能可以帮助智能体给出结构化、面向生产环境的建议，让大型仓库中的 Bazel 构建更快、也更易维护。它面向的是真实的构建系统工作场景：monorepo 搭建、remote cache 或 remote execution 落地、慢 target 分析、flaky builds、依赖图清理，以及向更可扩展的 Bazel 模式迁移。

谁适合使用它

这个技能最适合平台工程师、构建工程师、基础设施团队，以及在 Bazel 代码库中工作的高级应用开发者，尤其是当你的仓库已经大到构建速度、cache hit rate 或 rule 设计开始真正影响效率时。以下场景尤其适合：

• 缩短本地和 CI 的构建时间
• 设计 package 边界
• 配置 remote caching 或 execution
• 选择 rule 和 target 结构
• 排查慢增量构建
• 将 polyrepo 或混合 toolchain 体系迁移到 Bazel

它真正解决的工作问题

多数用户并不需要一份 Bazel 教程。他们需要的是一个助手，能面对杂乱的性能问题时，把它拆成明确的下一步：该检查什么、哪些文件最关键、哪些反模式要去掉、以及如何在速度和复杂度之间做取舍。bazel-build-optimization skill 的价值，就在于让你的提示词产出“理解架构上下文”的优化建议，而不是泛泛而谈的“开启缓存”式回答。

它和通用 build 提示词的区别

它的核心差异在于对 Bazel 概念和仓库布局的具体把握。这个技能建立在 Bazel 的基础原语之上，比如 WORKSPACE.bazel、BUILD.bazel、labels、packages、rules 和 aspects，并且会按照 Bazel 实际分析和构建 target 的方式来组织优化建议。相比一个泛泛讨论 CI 提速的宽泛提示词，它更有可能输出可执行的 Performance Optimization 建议。

适用与不适用场景

当你手头有一个真实的 Bazel 仓库、一个明确的性能问题，并且能提供文件结构、构建命令或故障症状时，就适合使用 bazel-build-optimization for Performance Optimization。

不要指望它替代：

• 官方 Bazel 文档中关于精确 rule 语法的说明
• 你们组织内部强制执行的 repo 专属构建规范
• 在完全没有 target 名称、配置、日志或耗时数据时做底层诊断

如果你的项目还没开始使用 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

这个技能基本上就是一个单文件指令包，没有额外的 helper scripts 或参考文档把关键行为藏起来。先读 SKILL.md，你就能了解它采用的架构模型、target 概念，以及智能体在推理时很可能会用到的配置模式示例。

要让这个技能发挥效果，你需要提供什么输入

bazel-build-optimization usage 的质量，很大程度取决于你给出的输入。建议至少提供：

• 你的 Bazel 版本
• 是否使用 WORKSPACE.bazel 和/或 bzlmod
• 简短的仓库布局说明
• 一个或多个慢命令，例如 bazel build //... 或某个具体 target
• 慢在哪个阶段：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.

更强版本之所以有效，是因为它给了这个技能明确的拓扑、症状、范围和成功标准。

不要只要建议，要先要诊断

最佳工作流通常是：先让技能分类问题，再提出修复方案。例如：

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/ 或类似目录下的自定义 rule 文件
• CI 日志里失败或耗时较高的命令示例

如果你只能提供一样东西，那就优先给出慢命令，以及相关 target 对应的 BUILD 文件。

你应该期待什么样的输出

一个好的 bazel-build-optimization guide 风格回答，通常应该包含：

• 可能的根因，而不只是泛泛建议
• 按优先级排序的修改项及其理由
• 能对应到你仓库实际情况的 Bazel 专有术语
• 在有帮助时给出示例配置或文件修改建议
• 用于确认优化是否有效的测量计划

如果回答只停留在“开启 cache”或“拆分模块”，却没有把建议和你的 target graph 联系起来，通常说明输入上下文还不够。

这个技能最有价值的常见工作流

这个技能在以下工作流中最能体现价值：

• monorepo 采用规划
• 首次部署 remote cache 或 remote execution
• 降低 CI 构建耗时
• target 和 package 重构
• 自定义 rule 设计评审
• 从临时脚本迁移到 Bazel 原生结构

对于一次性的语法问题，它就没那么有价值了，这类问题直接查官方文档通常更快。

采纳建议前需要先决定的取舍

在 Bazel 中做优化，经常意味着用更高的复杂度换取速度。你可以要求智能体明确指出这些取舍，例如：

• 更细粒度的 targets vs 更高的维护开销
• remote execution 的收益 vs 基础设施复杂度
• 自定义 rules vs 标准 rule 生态
• 更激进的缓存策略 vs 可复现性和调试清晰度

这一点很重要：这个技能能帮你优化，但最终要承担多少运维负担，还是要由你自己决定。

bazel-build-optimization 技能 FAQ

bazel-build-optimization 适合新手吗？

适合，前提是你已经有一个 Bazel 仓库，并且你需要的是带引导的分析，而不是一整套零基础入门课程。这个技能会涉及 targets、packages、labels 和 rules 等核心概念，但它更擅长做实际优化，而不是带你从零开始学 Bazel。

什么时候应该用它，而不是普通提示词？

当你的问题涉及 Bazel 架构、构建图设计、remote cache 或 execution、或 monorepo 扩展性时，就该用 bazel-build-optimization。普通提示词也能帮你发散思路，但这个技能更有可能围绕真正影响 Bazel 性能的文件和概念来组织答案。

它能处理 remote caching 和 remote execution 吗？

可以。源材料明确把 remote caching 和 remote execution 配置列为适用场景。如果这是你的目标，记得一并提供当前 cache 配置、CI 表现、认证模型，以及 cache hit 或 miss 的具体症状。

它能帮助做 Bazel 迁移吗？

可以，尤其适合那些要在大型代码库中推进 Bazel 的团队。这个技能很适合用来规划仓库结构、package 边界、依赖管理，以及迁移过程中的构建性能问题。

这个技能只适合超大型企业 monorepo 吗？

不是，但那确实是它最擅长的场景。较小的仓库也能受益，只要 build graph 设计、target 边界或 remote cache 行为已经开始影响开发效率。对于只有少量 targets 的非常小型仓库，做 Bazel 专项优化的额外成本，可能会超过实际收益。

这个技能哪些方面做得不够好？

这个技能本身不附带 repo 专属自动化、profiling scripts 或 enforcement rules。它提供的是指导和模板；如果你不提供文件、命令和症状，它不会自动替你检查构建系统。

它和直接阅读 SKILL.md 有什么区别？

直接阅读 SKILL.md，你能拿到模式和示例。通过智能体使用 bazel-build-optimization skill 的价值，则体现在它可以把这些模式适配到你的仓库、约束条件和性能问题上，而不是你自己手动做这层转换。

如何提升 bazel-build-optimization 技能的使用效果

给 bazel-build-optimization 技能提供性能证据，而不只是主观判断

提升 bazel-build-optimization usage 效果最快的方法，就是提供证据：

• 慢命令
• 耗时差异
• 本地与 CI 的表现差异
• cache hit rate 的观察结果
• 有代表性的 BUILD 文件

这样智能体就能基于真实症状推理，而不是重复常见的 Bazel 最佳实践。

先把问题范围收敛到一条 target 路径

除非问题确实是全局性的，否则不要一开始就用 //...。更高质量的提示词，通常来自一个慢 package、一个 flaky test target，或某一片有问题的依赖区域。先让智能体帮你解决一个聚焦案例，再把同样的方法扩展到整个仓库。

让它按优先级给出修复项，并说明预期影响

一个高质量的改进型提示词可以这样写：

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.

这样能逼出可决策的输出，而不是一份没有排序的清单。

尽量提供真实文件内容，而不是转述

能贴真实的 .bazelrc、WORKSPACE.bazel 和 BUILD.bazel 片段时，就不要只做概述。很多细小的语法和结构差异，都会直接改变 Bazel 的行为；转述式总结往往会把真正的问题遮掉。

要求给出改动前后的验证步骤

如果你希望输出更可信，可以要求技能同时说明：

• 改动前该测什么
• 第一批先改什么
• 每一步之后什么结果算成功
• 出现哪些迹象就应该考虑回滚

这样建议就会变成一个可迭代的优化闭环，而不是一次性的建议列表。

留意 bazel-build-optimization 技能的常见失效模式

这个技能表现不佳，最常见的原因是：

• 没有提供 target 名称或命令
• 没有区分本地问题和 CI 问题
• 只问“最佳实践”，却没有具体瓶颈
• 隐藏了影响 build graph 的自定义 rules 或 macros
• 想要精确语法，却不提供当前配置

如果回答看起来很泛，通常不是技能本身的问题，而是提示词过于抽象。

在第一次回答之后继续迭代

拿到初始回答后，最好继续补一轮，比如：

• 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 的价值才会变得更具体、更贴近实际。

让技能结合你的环境解释取舍

如果你的团队特别在意开发者体验、CI 成本或迁移风险，就明确说出来。想提升 bazel-build-optimization skill 输出质量，最有效的方法之一，就是把优化目标讲清楚：是追求最快 CI、最快本地迭代、最低维护成本，还是最稳妥的迁移路径。不同目标，最终建议会明显不同。