Back to Details

build-optimize

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Local build optimization

本地构建优化

Measure local wall time before changing. Preserve checks, artifacts, and failure behavior.
This skill covers local cargo, pytest, npm, pnpm, go, and just commands. Use /ci-optimize for GitHub Actions workflow timing or changes.
更改前先测量本地墙钟时间。保留检查项、构建产物和失败行为。
此 skill 涵盖本地 cargo、pytest、npm、pnpm、go 和 just 命令。 GitHub Actions workflow 的计时或变更请使用 /ci-optimize。

Discipline

规范

Iron Law: Measure the approved run plan before proposing a concrete edit.
Red Flags — stop when you notice these:
  1. An edit removes a check or artifact, changes the workload, or hides a failure.
  2. Cache operations, sample counts, warmups, or isolation differ from the approved plan.
  3. Cold and warm cohorts merge, or a blocked helper comparison becomes a speed claim.
RationalizationWhy it failsRequired action
"The warm run is faster, so every build is faster."A warm run skips cold-cache work.Report each cohort separately.
"Parallel tests are faster."Parallel workers require test isolation.Prove isolation before the plan.
"The helper is absent, so raw timings are enough."Raw timings cannot pass the comparison gate.Keep raw evidence and report comparison blocked.
铁律： 在提出具体编辑方案前，必须先测量已获批准的运行计划。
危险信号——发现以下情况时停止：
  1. 编辑会移除检查项或构建产物、改变工作负载，或隐藏失败。
  2. 缓存操作、采样次数、预热次数或隔离条件与已获批准的计划不一致。
  3. 合并了冷缓存与热缓存分组，或将受阻的 helper 对比视为性能提升依据。
合理化理由失败原因必须采取的行动
“热缓存运行更快，所以每次构建都更快。”热缓存运行跳过了冷缓存工作。分别报告每个分组。
“并行测试更快。”并行 worker 需要测试隔离。在制定计划前证明具备隔离条件。
“helper 不存在，因此原始计时就足够了。”原始计时无法通过对比门槛。保留原始证据，并报告对比受阻。

References

参考资料

Read methodology before defining the run plan. Read the matching ecosystem reference before defining the run plan. Read sibling local.md before capturing local timing. Read sibling schemas.md before constructing normalized inputs.
  • Ecosystem: rust.md, python.md, js-ts.md, go.md.
  • Timing: methodology.md.
  • Sibling adapters: 
    local.md
    and 
    schemas.md
    in the ci-optimize skill's references directory.
定义运行计划前阅读方法论。 定义运行计划前阅读对应生态系统的参考资料。 采集本地计时前阅读同级的 local.md。 构建标准化输入前阅读同级的 schemas.md。
  • 生态系统：rust.md、python.md、js-ts.md、go.md。
  • 计时：methodology.md。
  • 同级适配器：ci-optimize skill 的 references 目录中的 
    local.md
    和 
    schemas.md
    。

Workflow

工作流

  1. Read repository instructions. Identify the authoritative local command.
  2. Define a run plan with the exact command, warmup and sample counts, cache operations, isolation, output paths, and cost.
  3. Obtain explicit approval for the run plan.
  4. Measure baseline with the approved cache cohort(s).
  5. Report baseline evidence.
  6. Propose affected files, a benefit hypothesis, risks, verification, and any established rollback.
  7. Wait for explicit edit-plan approval before changing tracked source.
  8. Apply the approved change through the repository's existing edit path.
  9. Re-measure the same protocol. Verify all checks, artifacts, and failure behavior.
  10. Stop after the report or when required input is missing.
  1. 阅读仓库说明。确定权威的本地命令。
  2. 定义运行计划，明确命令、预热次数、采样次数、缓存操作、隔离条件、输出路径和成本。
  3. 获得运行计划的明确批准。
  4. 使用已批准的缓存分组测量基线。
  5. 报告基线证据。
  6. 提出受影响文件、收益假设、风险、验证方式和任何已确定的回滚方案。
  7. 更改受版本控制的源代码前，等待编辑计划的明确批准。
  8. 通过仓库现有的编辑路径应用已批准的更改。
  9. 使用相同协议重新测量。验证所有检查项、构建产物和失败行为。
  10. 完成报告后停止，或在缺少必需输入时停止。

Commands

命令

Resolve 
CI_OPTIMIZE_HELPER
from the actual loaded 
SKILL.md
directory. Resolve symlinks before appending 
../ci-optimize/scripts/ci_optimize.py
. Never derive the helper path from the consumer repository's current directory. The helper does not execute commands, edit source, install dependencies, or commit changes.
Run commands from the consumer repository's working directory:
text
python3 "$CI_OPTIMIZE_HELPER" from-hyperfine --input BEFORE-RAW.json --command 'COMMAND' --revision REVISION --environment ENV --cache-state STATE --workload-label LABEL --output BEFORE.json
python3 "$CI_OPTIMIZE_HELPER" from-hyperfine --input AFTER-RAW.json --command 'COMMAND' --revision REVISION --environment ENV --cache-state STATE --workload-label LABEL --output AFTER.json
python3 "$CI_OPTIMIZE_HELPER" compare --before BEFORE.json --after AFTER.json --minimum-samples N --output COMPARISON.json
Run this sequence separately for approved cache cohorts with distinct output paths. Use 
--force
only to replace an existing explicit output file. Keep raw evidence when the sibling helper is absent. Report comparison blocked when the helper is absent. Do not install a helper or waive the comparison gate.
从实际加载的 
SKILL.md
所在目录解析 
CI_OPTIMIZE_HELPER
。 追加 
../ci-optimize/scripts/ci_optimize.py
前先解析符号链接。 切勿根据调用方仓库的当前目录推导 helper 路径。 helper 不会执行命令、编辑源代码、安装依赖项或提交更改。
在调用方仓库的工作目录中运行命令：
text
python3 "$CI_OPTIMIZE_HELPER" from-hyperfine --input BEFORE-RAW.json --command 'COMMAND' --revision REVISION --environment ENV --cache-state STATE --workload-label LABEL --output BEFORE.json
python3 "$CI_OPTIMIZE_HELPER" from-hyperfine --input AFTER-RAW.json --command 'COMMAND' --revision REVISION --environment ENV --cache-state STATE --workload-label LABEL --output AFTER.json
python3 "$CI_OPTIMIZE_HELPER" compare --before BEFORE.json --after AFTER.json --minimum-samples N --output COMPARISON.json
对每个已批准的缓存分组单独运行此序列，并使用不同的输出路径。 仅在需要替换已有的显式输出文件时使用 
--force
。 同级 helper 不存在时，保留原始证据。 helper 不存在时，报告对比受阻。 不要安装 helper，也不要豁免对比门槛。

Evidence and report

证据与报告

Read 
COMPARISON.json
. Require 
comparability: true
. Report status, command boundary, eligible and excluded counts, medians and range, delta, checks, artifacts, limitations, next approval, and evidence paths. Preserve every excluded sample and its reason. Record approved context differences in acknowledgements. Acknowledgements cannot waive workload or validation mismatches or prove equivalent coverage. Describe observations without promising numeric gains. Return no more than 200 words. Do not rename unrelated gates, add auto-fix checks, or change CI workflows.
阅读 
COMPARISON.json
。要求 
comparability: true
。 报告状态、命令边界、纳入和排除的样本数量、中位数与范围、差异、检查项、构建产物、限制、下一步审批事项和证据路径。 保留每个被排除的样本及其原因。 在 acknowledgements 中记录已获批准的环境差异。 acknowledgements 不能豁免工作负载或验证条件不匹配的问题，也不能证明覆盖范围等价。 描述观察结果时不要承诺具体数值收益。返回内容不超过 200 个词。 不要重命名无关的门槛、添加自动修复检查或更改 CI workflow。