From 236d886f9e7aaa76d3f0f597cf5f375ed47d9952 Mon Sep 17 00:00:00 2001 From: Anton Vakhrushev Date: Sat, 18 Jul 2026 09:06:39 +0300 Subject: [PATCH] =?UTF-8?q?=D0=A1=D0=BA=D0=B8=D0=BB=D0=BB=D1=8B:=20=D0=B1?= =?UTF-8?q?=D0=B0=D1=82=D1=87-=D0=BE=D1=80=D0=BA=D0=B5=D1=81=D1=82=D1=80?= =?UTF-8?q?=D0=B0=D1=82=D0=BE=D1=80=20=D0=B7=D0=B0=D0=B4=D0=B0=D1=87=20+?= =?UTF-8?q?=20=D0=B2=D0=B5=D1=82=D0=BA=D0=BE=D0=BD=D0=B5=D0=B7=D0=B0=D0=B2?= =?UTF-8?q?=D0=B8=D1=81=D0=B8=D0=BC=D1=8B=D0=B9=20=D0=BF=D0=B0=D0=B9=D0=BF?= =?UTF-8?q?=D0=BB=D0=B0=D0=B9=D0=BD?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Новый скилл task-batch: проводит несколько задач беклога разом — план порядка/зависимостей, каждая задача сабагентом в своём worktree через task-pipeline, интеграция в master по одной ветке rebase/ff (линейная история), финальные тесты + сверка кода с требованиями по затронутым capability. Пред-назначение номеров миграций, потолок параллелизма 2-3, политика частичного провала (вливаем только зелёные), оговорки про семантический конфликт одной capability и изоляцию тестов. task-pipeline: коммит в текущую ветку вместо master (работает и вручную, и под оркестратором в worktree); поведенческая верификация через skill verify для нетривиальных задач. Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude/skills/task-batch/SKILL.md | 211 ++++++++++++++++++++++++++ .claude/skills/task-pipeline/SKILL.md | 28 +++- 2 files changed, 235 insertions(+), 4 deletions(-) create mode 100644 .claude/skills/task-batch/SKILL.md diff --git a/.claude/skills/task-batch/SKILL.md b/.claude/skills/task-batch/SKILL.md new file mode 100644 index 0000000..b6a176f --- /dev/null +++ b/.claude/skills/task-batch/SKILL.md @@ -0,0 +1,211 @@ +--- +name: task-batch +description: Автономно проводит несколько задач jellybit из беклога разом — планирует порядок и зависимости, гонит каждую задачу отдельным сабагентом в своём git worktree через task-pipeline, интегрирует в master по одной ветке через rebase/ff (линейная история), в конце прогоняет все тесты и сверяет код с требованиями по каждой затронутой capability. Использовать, когда пользователь просит взять/сделать несколько задач из беклога сразу. +--- + +# Батч задач (jellybit) + +Оркестратор **набора** задач по Spec Driven Development. Планирует порядок, +раскидывает задачи по изолированным worktree, каждую проводит через полный цикл +`task-pipeline`, затем сводит в master линейной историей и делает финальную +сверку. Тонкая обёртка над `task-pipeline` — не переизобретай её шаги, вызывай +как есть. + +Работай **максимально автономно**. Зови пользователя (через **AskUserQuestion**) +только на реальных развилках — как в `task-pipeline`. Механику — планирование, +worktree, rebase, интеграцию, чистку — делаем без спроса. + +Перед стартом прочитай `CLAUDE.md`, `README.md`, `BRIEF.md`, +`docs/specs/architecture.md`, если ещё не в контексте. + +## Ключевое отличие от одиночного пайплайна + +`task-pipeline` коммитит **прямо в master** (память `commit-directly-to-master`). +Здесь это невозможно для параллельных задач, поэтому батч — **осознанное +исключение**: заводим временные ветки/worktree лишь как средство изоляции, а +конечное состояние — та же линейная trunk-based история master через rebase + +fast-forward. Ветки после вливания удаляем. Дух памяти (линейный master без +мусорных мёрджей) сохраняется. + +## Модель исполнения + +- Каждая задача = **один автономный сабагент** (`general-purpose`, чтобы иметь + доступ к Skill и Agent для вложенных ревью-чекпоинтов), работающий **только в + своём worktree** и прогоняющий `task-pipeline` целиком на этой задаче. +- Оркестратор (главный агент) не пишет код задач сам — он планирует, заводит + worktree, запускает сабагентов, интегрирует ветки в master и делает финальную + сверку. +- Стиль правок внутри — заточка под проект и конвенции, right-size, без золочения + (память `convention-design-approach`). + +## Шаги + +### 1. Выбрать набор задач + +- Если набор задан (список slug'ов/файлов, «топ-3 высоких», «эти три») — используй. +- Иначе покажи кандидатов из `docs/backlog/README.md` (высокий приоритет, не + `[идея]`) через **AskUserQuestion** (multiSelect) и дай выбрать. +- `[идея]`-задачи включаются, но помни: сабагент проведёт их сперва через + `opsx:explore` (см. `task-pipeline`) — это тяжелее и может упереться в развилку. + +Прочитай файл каждой выбранной задачи и связанные спеки/ADR/черновики. + +### 2. Спланировать порядок, зависимости и конфликты (автономно) + +Для каждой задачи определи по её файлу и `capability-map` (память): + +- **Затронутые capability** (из 11: identity, ingest, download-tracking, + recognition, metadata-match, review, file-layout, state-reconciliation, + notifications, web-ui, live-status). +- **Жёсткие зависимости**: задача B строится на результате A → A строго раньше B. +- **Миграции БД — пред-назначение номеров** (не сериализация). Определи, какие + задачи, вероятно, добавят миграцию (новая таблица/столбец/индекс/связь), и + **заранее раздай им номера**: посмотри последний номер в + `internal/store/migrations/` и назначь `0012`, `0013`, … по одной на задачу. + Номер уходит в charter сабагента (шаг 4). Так migration-задачи можно гнать + параллельно — файлы миграций не столкнутся, а `docs/specs/database.md` + (ER-схема) правят разные строки, textual-конфликт при rebase мелкий и решается + на интеграции. +- **Жёстко сериализуем** (не гоняем одновременно) только настоящие пересечения: + - **Одна capability на несколько задач**: две задачи, правящие одну capability + (тем более один и тот же `### Requirement` в её спеке), дают не текстовый, а + **семантический** конфликт при `archive` — сериализуем по смыслу, а не только + по файлам. + - Пересечение по одним и тем же исходникам. +- **Мягкие конфликты** (обычно авто-мёрджатся при rebase, сериализовать не надо): + `docs/backlog/README.md` (каждая задача убирает свою строку) и + `openspec/specs/` разных capability (archive вливает дельты) — разные + строки/файлы. + +Собери план: **волны** параллельно-безопасных задач + сериализованный хвост +конфликтоопасных, с учётом зависимостей. Покажи план короткой репликой и иди +дальше. **AskUserQuestion — только** если порядок реально неоднозначен или +задачи глубоко связаны продуктово. + +### 3. Свежий master как база + +Убедись, что рабочее дерево чистое и master свежий (`git status`, при наличии +remote — `git fetch` и синк). Зафиксируй базовый коммит. **Новые ветки бери от +свежего master**; ветки следующей волны — от master, уже включающего результат +предыдущих волн. + +### 4. Прогнать волны + +**Потолок параллелизма — 2–3 задачи одновременно.** Каждая задача тянет полный +`task-pipeline` + вложенные ревью + `task test`/`go build`, поэтому больше трёх +разом душат домашнюю машину и провоцируют гонки. Волну шире трёх бей на под-пачки +по ≤3 и гони их последовательно. + +Для каждой задачи в под-пачке: + +1. Заведи worktree + ветку от текущего вершинного master: + `git worktree add -b task/ master`. Путь — рядом с репо или в + `./tmp/` (память `use-project-tmp-dir`; НЕ в системном `/tmp`). Имя ветки — + `task/`. +2. Запусти **по одному сабагенту на задачу, все в одном сообщении** (конкурентно, + но не больше трёх), `subagent_type: general-purpose`. Charter сабагента: + - Работай **строго в своём worktree** ``; в другие каталоги и в master + не лезь. + - Прогони skill **`task-pipeline`** ровно на этой задаче (``/файл), + полный цикл SDD с промежуточными ревью-чекпоинтами. + - Если задаче на шаге 2 назначен **номер миграции** — используй строго его + (`internal/store/migrations/<номер>_*`), не бери «следующий свободный» сам. + - **Ревью-чекпоинты**: попробуй запустить агентов `jellybit-review-specs` / + `jellybit-review-code` через Agent tool (как в `task-pipeline`). Если + вложенный запуск сабагента недоступен — проведи ревью **инлайн**, используя + charter'ы `.claude/agents/jellybit-review-*.md` как чеклист. Чекпоинт «ревью + спек ДО кода» не пропускай. + - **Коммит.** `task-pipeline` коммитит в текущую ветку — а это твоя + `task/` в worktree, так что специально ничего переопределять не нужно. + Всё остальное (`opsx:archive`, чистка беклога `docs/backlog/.md` + + строка индекса, синк спек/ADR) ложится коммитами туда же. Master не трогай, + ветку не переключай, ничего не пушь, новых worktree не создавай. + - `task test` / `task lint` в своём worktree — добейся зелёного. + - Верни отчёт: что сделано, какие развилки решались, изменённые файлы, + **добавлял ли миграцию и её номер**, затронутые capability, статус + тестов/линта, все неразрешённые вопросы. + +Если сабагент упирается в развилку, которую `task-pipeline` выносит на +пользователя, — он останавливает свою задачу и возвращает вопрос; оркестратор +собирает такие вопросы и выносит их пользователю (**AskUserQuestion**), остальные +задачи при этом продолжаются. + +### 5. Интегрировать в master — rebase + fast-forward, по одной ветке + +Сводим ветки в master **строго последовательно** (линейная история), в порядке +зависимостей — по одной ветке за раз. Вливаем **только зелёные** ветки: +провалившиеся/зависшие задачи в интеграцию не берём (см. политику ниже). + +Для каждой готовой (зелёной) ветки `task/`: +- `git rebase master task/` — перенос ветки на текущую вершину master. +- Резолв конфликтов (их почти нет — конфликтоопасное сериализовано, номера + миграций розданы заранее). Если rebase дал неавтоматический конфликт — **не + форсируй**: прерви (`git rebase --abort`), оставь ветку/worktree как есть и + вынеси развилку пользователю (это признак нераспознанного пересечения). +- `git checkout master && git merge --ff-only task/`. +- После каждой интеграции: `task test` (+ `task lint`) на master. **Красное — + откати эту интеграцию** (`git reset --hard` на прошлую вершину master), ветку с + worktree сохрани, вынеси пользователю. Master **никогда** не остаётся + полузелёным. +- Только после зелёного: `git worktree remove ` и `git branch -d task/`. + +Так каждая следующая ветка ребейзится на уже обновлённый master — история +линейна, каждая задача = свой осмысленный коммит (или несколько по фазам apply). + +**Политика частичного провала.** Если задача упала (сабагент вернул +неразрешённую развилку, тесты в её worktree красные, rebase/merge конфликтует) — +она **не блокирует остальные**: интегрируем все зелёные, упавшую оставляем в её +worktree и ветке нетронутой (ничего не удаляем), и в финальном докладе (шаг 8) +перечисляем провалившиеся с их отчётами и причиной. Пользователь потом решит: +дожать вручную, переназначить, отложить. + +### 6. Финальный гейт — все тесты + +На master после всех интеграций: `task test` + `task lint` (+ `task build`). +Зелёное — обязательно. + +### 7. Финальная сверка кода с требованиями — по затронутым capability + +Собери **объединение затронутых capability** по всем задачам. Запусти **по одному +сабагенту-ревьюверу на каждую затронутую capability, все в одном сообщении** +(параллельно), `subagent_type: jellybit-review-specs`. Каждому дай: +- имя capability и путь `openspec/specs//spec.md`; +- интегрированный diff `git diff <база>..HEAD`, сфокусированный на файлах этой + capability; +- задание: сверить **код на master с требованиями** capability — покрытие + `### Requirement` (все содержат `SHALL`/`MUST`), сценарии `GIVEN/WHEN/THEN`, + инварианты безопасности данных, непротиворечивость код↔спека после слияния + нескольких задач (косвенные рассинхроны на стыках). + +Опционально, если задач много и они пересекаются, добавь один +`jellybit-review-code` на весь интегрированный diff (архитектура/конвенции/стиль +сквозняком). Замечания отрабатывай как в `task-pipeline`: мелочь чини инлайн, +развилки — на пользователя; после правок — снова `task test`/`task lint`. + +### 8. Прибраться и доложить + +- Убери worktree/ветки **только успешно влитых** задач (`git worktree remove` + + `git branch -d` уже сделаны на шаге 5); в конце `git worktree prune`. + Worktree/ветки **провалившихся** задач **не трогай** — они нужны пользователю + для ручного дожатия. +- Доложи кратко: какие задачи сделаны, план волн и порядок интеграции, какие + развилки решались, коммиты по задачам, итог финальной сверки, ссылки на + архивные change. **Отдельно перечисли провалившиеся** задачи с причиной, их + отчётом и путём к оставленному worktree/ветке. + +## Тонкости + +- **Номера миграций раздаёт оркестратор** (шаг 2), сабагент берёт назначенный, а + не «следующий свободный» — тогда migration-задачи безопасны параллельно. +- **Изоляция параллельных тестов.** Прежде чем гнать несколько `task test` разом, + убедись, что тесты не делят фиксированный TCP-порт или файл БД (обычно берут + `t.TempDir()`/эфемерный порт — тогда ок). Если делят — гони такие тесты + последовательно, а не в параллельной под-пачке. +- Ревью выполненного — **до** чистки беклога; это забота `task-pipeline` внутри + каждого сабагента (память `review-before-backlog-cleanup`). Оркестратор + дублировать не должен. +- Не пропускай `openspec validate --strict` — это тоже внутри `task-pipeline`. +- Если сабагент вернул крупную переработку/смену подхода — это развилка, не + вливай молча, вынеси пользователю. +- Держи пользователя в цикле короткими репликами на переходах фаз (план → волны → + интеграция → финальная сверка), но не проси подтверждать механику. diff --git a/.claude/skills/task-pipeline/SKILL.md b/.claude/skills/task-pipeline/SKILL.md index a7a48d9..39976bf 100644 --- a/.claude/skills/task-pipeline/SKILL.md +++ b/.claude/skills/task-pipeline/SKILL.md @@ -82,6 +82,14 @@ description: Автономно проводит задачу jellybit чере goose + синк ER-схемы `docs/specs/database.md`, htmx по web-ui-конвенции. Прогони `task test` и `task lint` (или `task build`), добейся зелёного. +**Поведенческая верификация (нетривиальные задачи с рантайм-поверхностью).** Если +задача меняет реальное поведение (новый флоу, схема БД, эндпоинт/htmx-путь, разбор +входа) — зелёных юнит-тестов мало: прогони через Skill **`verify`**, чтобы +прокатить изменение end-to-end и увидеть его вживую, а не только в тестах. +Пропусти для чисто внутренних правок без наблюдаемого рантайма (рефактор, доки, +правка только тестов). Под `task-batch` verify идёт в worktree задачи — портами/БД +не конфликтуй с соседними прогонами. + ### 7. Ревью кода — сабагент(ы) Второй чекпоинт. Ревьюеры — кастомные агенты из `.claude/agents/` (запускай их @@ -117,16 +125,28 @@ Charter'ы агентов самодостаточны — детальный п ### 10. Коммит -Коммить **прямо в master**, без feature-веток (память -`commit-directly-to-master`). Сообщение — по-русски, в стиле недавних коммитов -(`git log --oneline -8`): область + суть. Одна задача — один осмысленный коммит -(или несколько по фазам, если так шёл apply). +Коммить **в текущую ветку** (`git rev-parse --abbrev-ref HEAD`), сам ветку не +создавай и не переключай, ничего не пушь. Это работает в обоих режимах: + +- **Ручной запуск** — HEAD обычно на `master`, коммит идёт прямо в него, без + feature-веток (память `commit-directly-to-master`). +- **Под оркестратором `task-batch`** — HEAD на ветке задачи в изолированном + worktree (`task/`); коммит идёт туда, а слияние в `master` через rebase/ff + делает оркестратор. Ничего дополнительно делать не нужно. + +Сообщение — по-русски, в стиле недавних коммитов (`git log --oneline -8`): область ++ суть. Одна задача — один осмысленный коммит (или несколько по фазам, если так +шёл apply). Готово — доложи пользователю кратко: что сделано, какие развилки решались, ссылки на архивный change и спеки. ## Тонкости +- **Не завязывайся на master и корень репо.** Скилл работает в текущем worktree и + на текущей ветке: не делай `git checkout`/`switch`, не создавай веток, не + пушь. При одиночном запуске это master, под `task-batch` — ветка задачи в своём + worktree; поведение одинаковое. - Не пропускай `openspec validate --strict` перед архивацией. - Тривиальная задача: шаги 2 и 4 пропускаются; ревью кода (шаг 7) оставляем, но одним сабагентом на всё. Два параллельных ревьювера — только на нетривиальных.