bench-wave — команда для Claude Code: что делает и как установить
Команда bench-wave запускает полный цикл бенчмарка для этапа оптимизации pipeline-diet в Speckit Companion и сохраняет метрики в сводную таблицу. Пригодится при замерах скорости и расхода токенов.
MIT ★ 110 обновлён 2026-10-19
.claude/commands/bench-wave.mdЧто делает bench-wave
Команда выполняет сквозное тестирование одной волны изменений («wave») с помощью двух ячеек Companion. Она принимает букву волны и опциональную ветку git, после чего переключает изолированное рабочее дерево bench-main, компилирует проект через npm run compile и проверяет наличие правок в файлах каталога commands/. Перед запуском тяжёлых тестов скрипт прогоняет обязательные проверки: pytest, Jest, валидацию бюджета инструкций и тест формы.
Если гейты пройдены, запускается подготовка шаблонов через node-скрипты в соседнем репозитории speckit-sandboxes и стартует процесс wave-bench. Тест длится около 40 минут. За это время он замеряет токены, вызовы и контекст без посторонней нагрузки на машине. Завершив прогон, команда добавляет строку в таблицу результатов в файле Projects/speckit companion/plans/pipeline-speed/Pipeline Speed Execution.md и переносит все заметки тест-драйверов.
Команда жёстко завязана на конкретные пути вроде ~/dev/GitHub/speckit-companion.worktrees/bench-main и репозиторий speckit-sandboxes. Без этой точной файловой структуры и настроенного окружения запустить бенчмарк не выйдет.
Какие задачи решает
- запустить полный цикл бенчмарка для волны pipeline-diet
- прогнать линтеры, тесты pytest, Jest и контроль бюджета инструкций
- подготовить окружение ячеек через скрипты
speckit-sandboxes - внести метрики времени, вызовов и токенов в план выполнения
Примеры запросов агенту
- /bench-wave B
- /bench-wave C pipeline-diet/wave-c-refactor
- /bench-wave D
Как установить bench-wave
Вручную: положить файлы
.claude/commands/bench-wave.mdВызов — /bench-wave. Для всех проектов — ~/.claude/commands/
Вручную: положить файлы
~/.codex/prompts/bench-wave.mdВызов — /prompts:bench-wave. В Codex этот формат помечен устаревшим, замена — скиллы
Вручную: положить файлы
.github/prompts/bench-wave.prompt.mdВручную: положить файлы
.gemini/commands/bench-wave.tomlGemini хранит команды в TOML: текст запроса — в поле prompt
Вопросы о bench-wave
Как установить bench-wave в Claude Code?
Сохраните файл команды по пути .claude/commands/bench-wave.md внутри вашего репозитория. Для Codex используйте путь ~/.codex/prompts/bench-wave.md.
Что делает bench-wave?
Команда автоматизирует тестирование волны оптимизации pipeline-diet: собирает рабочее дерево, проверяет лимиты инструкций и тесты, запускает 40-минутный прогон на ячейках Companion и записывает результат в markdown-план.
Что произойдёт, если упадут тесты или проверки бюджета?
Команда сразу прервёт выполнение, укажет на упавший гейт и не станет запускать бенчмарк.
Исходный текст
bench-wave.md · MIT
---
allowed-tools: Bash(. .claude/sandboxes-env.sh:*), Bash(git -C:*), Bash(npm run compile:*), Bash(python3 apps/speckit-extension/scripts/*), Bash(python3 -m pytest:*), Bash(npx jest:*), Bash(node "$SANDBOXES_REPO"/bench/*), Workflow, Read, Edit
description: Bench one pipeline-diet wave on the two Companion cells and record the row
---
## Your task
Bench one wave of the pipeline diet, start to finish, and record it. `$ARGUMENTS` is the wave letter (`B`), optionally followed by the branch; the branch defaults to `pipeline-diet/wave-<letter lowercase>`. The plan and the results table live in the vault at `Projects/speckit companion/plans/pipeline-speed/Pipeline Speed Execution.md`.
One bench at a time. Nothing else heavy runs on this machine until the row is recorded.
### Paths
Shell state does not persist between Bash calls, so start each one with this line:
```bash
. .claude/sandboxes-env.sh && eval "$(node "$SANDBOXES_REPO"/bench/paths.mjs --sh)"
```
It sets `$SANDBOXES_REPO` (the sibling `speckit-sandboxes` checkout, whose `bench/` folder is the harness) and `$BENCH_CELLS_DIR` (where the cells are baked). When you hand a path to an agent, expand it first: an agent gets the absolute path, never the variable.
### 1. The wave has to reach the cell
The bench dispatches from the pinned worktree, not from this checkout. Point it at the wave's pushed commit and rebuild the preamble:
```bash
git -C ~/dev/GitHub/speckit-companion.worktrees/bench-main fetch -q origin
git -C ~/dev/GitHub/speckit-companion.worktrees/bench-main checkout -q --detach origin/<branch>
(cd ~/dev/GitHub/speckit-companion.worktrees/bench-main && npm run compile)
```
Then prove the wave's text is what the cell will get: pick one line the wave changed and grep for it in `~/dev/GitHub/speckit-companion.worktrees/bench-main/apps/speckit-extension/commands/`.
**A node has to be in the step's `_order.yml` to reach the arm.** The Companion arms dispatch `/speckit-companion-<step>`, whose body is assembled from `nodes/<step>/_order.yml`. A part added to a preset's own `commands/` is inert for them: that body lands as the stock `/speckit-<step>` skill, which only the stock arm runs. Attaching a node for a bench means a file in `nodes/<step>/` and its name in that step's `_order.yml`; the grep above is what proves it. If it is not there, the branch was not rebuilt (`build.py`) or not pushed. Stop and fix that first.
### 2. Gates, in this checkout, on the wave branch
```bash
python3 apps/speckit-extension/scripts/build.py --check
python3 apps/speckit-extension/scripts/check_shape_parity.py
python3 apps/speckit-extension/scripts/instruction-budget.py
python3 -m pytest apps/speckit-extension/tests -q
npx jest
```
A red gate means the wave is not ready to bench. Say which one and stop.
### 3. Bake and prep
```bash
node "$SANDBOXES_REPO"/bench/sync-templates.mjs --sizes hard --speckit keep --ext code --sweep "wave <letter>"
node "$SANDBOXES_REPO"/bench/run-all.mjs prep --sizes hard --modes companion,companion-living
node "$SANDBOXES_REPO"/bench/run-all.mjs --dry-run
```
The bake prints `speckitExtBuild` as `code@<sha>`; it must be the wave's commit. The dry run prints which letter is which arm: take the two letters that are not stock. Never pass the mapping itself anywhere.
### 4. Run the round
```
Workflow name: wave-bench
args: { "wave": "<letter>", "size": "hard", "letters": ["<l1>", "<l2>"], "sweep": "wave <letter>", "benchDir": "<expanded $SANDBOXES_REPO/bench>", "cellsDir": "<expanded $BENCH_CELLS_DIR>" }
```
`benchDir` and `cellsDir` are the absolute paths the Paths line gives (`echo "$SANDBOXES_REPO/bench" "$BENCH_CELLS_DIR"`): a workflow script cannot read the environment, so it is handed both. It drives both cells, records tokens, captures alone, judges, folds the rubric, compares, and commits the round in `speckit-sandboxes`. Expect about 40 minutes. The result carries the two rows, the `calls` and `context` compare tables, the drivers' notes on what did not work as written, and the commit.
### 5. Record
Add the wave's row to the results table in the plan note (section ⑦), in the same columns as the rows above it, and write the findings under it: what moved, whether it moved more than the noise floor, and every driver note verbatim. A driver note about a command body is the most useful thing a round produces; it is what the next wave fixes first.
Then say in one paragraph what wave <letter> showed and what the next wave changes.
© alfredoperez · MIT · alfredoperez/speckit-companion