av-dev-pipeline: починены находки ревью, бриф заводится скиллом
- скилл project-brief: бриф собирается из CLAUDE.md, архитектуры, Taskfile и конвенций и показывается человеку. Раньше единственная инструкция по его созданию лежала внутри шаблона, поэтому деградированный режим был не аварийным, а единственным: critical по основанию «нарушен инвариант» недостижим ни на одной задаче - rebase перенесён внутрь worktree задачи: прежняя форма падала на занятой ветке, и агент уводил весь батч в провалившиеся с ложной причиной - контракт брифа дополнен восемью слотами; проверен заполнением на обоих проектах, незаполнимых нет. Прецедент healthlog вынут из общего charter'а в бриф — там он вмёрз вместе с числами - шов: пайплайн задачу не закрывает и записи учёта не трогает, урожай отдаёт списком, правило остатка — ссылкой на av-dev-tasks - деградированный абзац во всех девяти проходах, вопрос 9 в ops, пространство имён в вызовах, раздел предпосылок
This commit is contained in:
@@ -10,18 +10,48 @@ description: Автономно проводит одну задачу чере
|
||||
|
||||
Это тонкая обёртка над каноническими скиллами `opsx:explore` / `opsx:propose` /
|
||||
`opsx:apply` / `opsx:archive` — вызывай их через Skill, не переизобретай их шаги.
|
||||
Ревью — скилл `review-pipeline`, он же держит правило выбора профиля.
|
||||
Ревью — скилл `av-dev-pipeline:review-pipeline`, он же держит правило выбора
|
||||
профиля.
|
||||
|
||||
## Предпосылки
|
||||
|
||||
- **OpenSpec и скиллы `opsx:*`** — внешняя обвязка, на которой стоят шаги 2, 3, 6
|
||||
и 8, а также проход `review-specs` и профиль `design` (они завязаны на
|
||||
`openspec/changes/<id>/specs/*/spec.md` и на `openspec validate --strict`). В
|
||||
проекте без OpenSpec эти шаги упадут на «нет такого скилла»: либо подключаем
|
||||
OpenSpec, либо цикл вырождается в «прочитать задачу → код → ревью кода →
|
||||
коммит», и об отсутствии спекового контура говорится в докладе.
|
||||
- **Скиллы зовутся с пространством имён** — `av-dev-pipeline:review-pipeline`,
|
||||
`av-dev-pipeline:project-brief`. Короткое имя может разрешиться в устаревшую
|
||||
проектную копию, и это произойдёт молча.
|
||||
- **Проектные копии этих скиллов и агентов удаляются при установке плагина**
|
||||
(`.claude/skills/{task-pipeline,review-pipeline,task-batch}`,
|
||||
`.claude/agents/<проект>-review-*.md`). Две копии одного скилла расходятся, и
|
||||
побеждает та, что короче названа.
|
||||
|
||||
Перед стартом прочитай `CLAUDE.md` проекта и то, на что он ссылается
|
||||
(архитектура, конвенции), если ещё не в контексте. Проектные факты, нужные ревью
|
||||
— инварианты, команда гейта, объёмы, модель угроз, — живут в брифе
|
||||
— инварианты, команда гейта, объёмы, модель угроз, прецеденты, — живут в брифе
|
||||
(`docs/review-brief.md`, контракт — в references конвейера ревью).
|
||||
|
||||
**Брифа нет ни по одному пути — заведи его, а не работай в деградированном
|
||||
режиме.** Вызови Skill **`av-dev-pipeline:project-brief`**: он соберёт бриф из
|
||||
`CLAUDE.md`, архитектуры, файла задач и конвенций, покажет человеку и вернёт
|
||||
путь, который дальше передаётся ревью. Это механика: спрашивать разрешения не
|
||||
нужно. Один шаг один раз на проект — против деградации на каждой задаче.
|
||||
|
||||
## Границы: чем пайплайн не владеет
|
||||
|
||||
- **Беклогом, спринтом, целями и приоритетами.** Задача приходит извне. Пайплайн
|
||||
её не выбирает, не приоритизирует, не заводит и не переоценивает; если в
|
||||
проекте есть свой процесс управления задачами — он и решает, что брать.
|
||||
- **Записями учёта.** Пайплайн **не закрывает задачу**, не двигает её по
|
||||
статусам, не правит индекс и не зовёт скриптов учёта. Он сообщает исход;
|
||||
закрытие — акт владельца спринта **после приёмки**, и оно происходит снаружи.
|
||||
Закрыть задачу самому — значит закрыть её до коммита и до всякой приёмки, то
|
||||
есть заверить собственную работу.
|
||||
- **Заведением задач из урожая ревью.** Отложенные находки отдаются **списком**
|
||||
(см. шаг 7); превращать их в задачи — работа того, кто ведёт задачи проекта.
|
||||
- **Определением ценности.** «Нужна ли эта функциональность» — не вопрос
|
||||
пайплайна ни на одном шаге.
|
||||
|
||||
@@ -47,12 +77,17 @@ description: Автономно проводит одну задачу чере
|
||||
поимённо, непущенные проходы названы в границах покрытия;
|
||||
3. change заархивирован, дельты влиты в актуальные спеки;
|
||||
4. коммит сделан в текущую ветку;
|
||||
5. **критерии приёмки, если проект их дал**, проверены поимённо, у каждого назван
|
||||
оракул и исход. Критерии приходят снаружи; пайплайн их не сочиняет и не
|
||||
занижает. Расхождение «критерии закрыты, а суть задачи не достигнута» — дефект
|
||||
критериев, и о нём сообщается, а не молча дорабатывается.
|
||||
5. **критерии приёмки, если проект их дал, выписаны поимённо, и по каждому назван
|
||||
оракул и наблюдаемый исход** — «прогнал вот это, увидел вот то». Это **доклад,
|
||||
а не сертификация: приёмка — не работа пайплайна.** Исполнитель, ставящий себе
|
||||
галочку «принято», проверяет свою работу своим же взглядом — по границе это
|
||||
может делать только декоррелированный приёмщик. Критерии приходят снаружи;
|
||||
пайплайн их не сочиняет и не занижает. Расхождение «по каждому критерию исход
|
||||
есть, а суть задачи не достигнута» — дефект критериев, и о нём сообщается, а
|
||||
не молча дорабатывается.
|
||||
|
||||
Пункты 1–4 — своё. Пункт 5 — внешнее, и проверяется только если оно дано.
|
||||
Пункты 1–4 — своё. Пункт 5 — внешнее: пайплайн доводит его до наблюдаемого
|
||||
исхода и передаёт дальше.
|
||||
|
||||
## Принцип автономности
|
||||
|
||||
@@ -73,13 +108,23 @@ description: Автономно проводит одну задачу чере
|
||||
3. Доведи остаток до конца и закоммить. Задача не «висит на вопросе», она сделана
|
||||
в объявленных границах.
|
||||
|
||||
**Что остатком не является** — две оговорки, без которых правило вредит:
|
||||
**Что остатком не является — правило живёт не здесь.** Канонический текст с обеими
|
||||
оговорками — в плагине `av-dev-tasks`, скилл `av-dev-tasks:session`, раздел
|
||||
`## Вопрос, блокер, необратимое`, подраздел «Отличать вопрос от застревания».
|
||||
Правило принадлежит управлению задачами, потому что решает **сделана задача или
|
||||
вышла**, — это исход планирования, а не исполнения. **Ссылайся, не
|
||||
пересказывай:** копия, заведённая здесь, уже однажды разошлась с оригиналом и
|
||||
потеряла из перечня самое необратимое — запись **наружу**.
|
||||
|
||||
- **остаток, который записывает в хранилище или в журнал состояние, зависящее от
|
||||
нерешённого, — не остаток.** Решение поднимается до начала записи. Иначе
|
||||
нерешённое материализуется в данные, а данные переживают решение;
|
||||
- **остаток, из которого пропала польза, названная в постановке, — не остаток.**
|
||||
Это исход «не доведена», а не «сделана в границах».
|
||||
Коротко, чтобы знать, когда идти читать: остаток проверяется двумя порогами —
|
||||
**материализация нерешённого** (запись состояния, зависящего от неотвеченного
|
||||
вопроса) и **пол по пользе** (из остатка пропала польза, названная в постановке).
|
||||
Оба порога — стоп: первый поднимает решение до начала записи, второй даёт исход
|
||||
«не доведена».
|
||||
|
||||
Плагин `av-dev-tasks` не подключён — правило не отменяется, а становится
|
||||
осторожнее: прежде чем записать зависящее от нерешённого куда бы то ни было —
|
||||
в хранилище, в журнал, в витрину или наружу, — спрашивай человека.
|
||||
|
||||
Нет полезного остатка — задача заканчивается исходом «не доведена», вопрос
|
||||
записан, ничего не коммитится наполовину.
|
||||
@@ -137,10 +182,10 @@ description: Автономно проводит одну задачу чере
|
||||
|
||||
### 4. (Нетривиальная) Ревью предложения — профиль `design`, ДО кода
|
||||
|
||||
Первый чекпоинт. Вызови Skill **`review-pipeline`** с профилем `design`, ссылкой
|
||||
на change `<id>` и путём к брифу. Он запустит `review-specs` (режим «дизайн ДО
|
||||
кода»), `review-rubric` (фаза 1: приёмочные критерии для задуманного узла) и
|
||||
`review-architecture` по предложению.
|
||||
Первый чекпоинт. Вызови Skill **`av-dev-pipeline:review-pipeline`** с профилем
|
||||
`design`, ссылкой на change `<id>` и путём к брифу. Он запустит `review-specs`
|
||||
(режим «дизайн ДО кода»), `review-rubric` (фаза 1: приёмочные критерии для
|
||||
задуманного узла) и `review-architecture` по предложению.
|
||||
|
||||
Смысл профиля: архитектурная находка на готовом коде стоит переписывания и
|
||||
потому игнорируется — та же находка здесь стоит абзаца обсуждения. Рубрику из
|
||||
@@ -170,17 +215,16 @@ description: Автономно проводит одну задачу чере
|
||||
**Сервис не оставляем лежать.** Если запуск упал — почини или откати до конца
|
||||
шага.
|
||||
|
||||
### 7. Ревью кода — Skill `review-pipeline`
|
||||
### 7. Ревью кода — Skill `av-dev-pipeline:review-pipeline`
|
||||
|
||||
Второй чекпоинт. Вызови Skill **`review-pipeline`**, дав ссылку на change `<id>`,
|
||||
базу диффа, путь к брифу, профиль **и режим запуска**. Профиль выбирается по
|
||||
факту изменения, а не по ощущению важности; общее правило — в скилле, проектные
|
||||
триггеры — в брифе:
|
||||
Второй чекпоинт. Вызови Skill **`av-dev-pipeline:review-pipeline`**, дав ссылку
|
||||
на change `<id>`, базу диффа, путь к брифу, профиль **и режим запуска**.
|
||||
|
||||
- миграция схемы, новый пакет, публичный контракт, правило идентичности или
|
||||
слияния данных → `deep`;
|
||||
- иначе меняется поведение, видимое снаружи → `standard`;
|
||||
- иначе (багфикс, локальная правка, доки) → `quick`.
|
||||
**Правило выбора профиля живёт в скилле конвейера** (раздел «Профили»), проектные
|
||||
триггеры — в разделе `## Триггеры` брифа. Здесь оно не пересказывается: три
|
||||
копии одного правила расходятся, и работать будет та, которую прочитали
|
||||
последней. Помни ровно одно — **профиль выбирается по факту изменения, а не по
|
||||
ощущению важности**, и посмотри таблицу перед вызовом.
|
||||
|
||||
**Режим по умолчанию последовательный, и обосновывать его не надо.** Параллельно
|
||||
гоняем только тогда, когда об этом попросили явно **и назвали набор** — какие
|
||||
@@ -195,41 +239,54 @@ description: Автономно проводит одну задачу чере
|
||||
покрытия.
|
||||
|
||||
**Сверь состав прогона с таблицей профилей в скилле, прежде чем коммитить.**
|
||||
Пропуск прохода не отличим от прохода без находок: гейт зелёный, спеки сошлись,
|
||||
отчёт выглядит полным. Единственный, кто мог бы заметить пропуск, — триаж, а он
|
||||
заполняется тем, что ему подали. Отчёт обязан называть запущенные проходы
|
||||
**поимённо и с исходом**; непущенный идёт строкой «не запускался» в границы
|
||||
покрытия. Реестр короткий (4–8 проходов) — сверка стоит одного взгляда, а
|
||||
молчащий пропуск уже стоил семи находок и отдельной задачи на их дозакрытие.
|
||||
Отчёт обязан называть запущенные проходы **поимённо и с исходом**; непущенный
|
||||
идёт строкой «не запускался» в границы покрытия. Реестр короткий (4–8 проходов) —
|
||||
сверка стоит одного взгляда. Почему это правило существует, объясняет раздел
|
||||
«Профили» скилла конвейера; здесь — само требование.
|
||||
|
||||
Отработай так же, как шаг 5: помеченное `инлайн` чини сам и не логируй,
|
||||
`развилка` — вопросом в запись (он уже сформулирован триажем, его остаётся
|
||||
перенести). После правок — снова гейт.
|
||||
|
||||
**Урожай — списком, не задачами.** Отложенные находки (реальный `major` не для
|
||||
этого мерджа, развилка, решённая «потом», пачка `nit`) собери в секцию доклада
|
||||
`Урожай`: формулировка, оракул, провенанс. Задачи из него **заводит не пайплайн**
|
||||
— у того, кто ведёт задачи проекта, своя нарезка, свой формат и свои правила
|
||||
дублей. Твоя обязанность — не потерять и передать.
|
||||
|
||||
**Границы покрытия из отчёта не выбрасывай** — они уезжают в финальный доклад
|
||||
сжатой строкой. Отчёт, из которого исчезло «что проверить было невозможно»,
|
||||
превращается в ложное ощущение проверенности.
|
||||
|
||||
Отчёт триажа сохрани вместе с change (`openspec/changes/<id>/review/`): по нему
|
||||
потом видно, что было найдено и что из этого осталось незаведённым.
|
||||
**Отчёт триажа сохрани вместе с change (`openspec/changes/<id>/review/`) — это
|
||||
обязательно, а не «если удобно».** По нему потом видно, что было найдено и что из
|
||||
этого осталось в урожае. И это единственный **независимый** артефакт о составе
|
||||
прогона: под оркестратором `task-batch` именно по нему сверяют полноту ревью
|
||||
ветки, а не по твоей прозе — она написана тем же, кто мог проход и пропустить.
|
||||
|
||||
### 8. Архивировать — `opsx:archive`
|
||||
|
||||
Вызови Skill `opsx:archive`: change уезжает в архив, дельты вливаются в
|
||||
актуальные спеки.
|
||||
|
||||
### 9. Синк документации и закрытие задачи
|
||||
### 9. Синк документации
|
||||
|
||||
Ревью выполненного — **до** закрытия. Затем:
|
||||
Ревью выполненного — до этого шага. Затем:
|
||||
|
||||
- суть переехавшего решения — в документацию проекта (архитектура, журнал
|
||||
решений), если её там ещё нет;
|
||||
- менялась схема — её описание обновлено тем же change;
|
||||
- новое, узнанное о внешнем формате или о данных, — в тот файл проекта, который
|
||||
это накапливает; такой файл обычно ценнее кода;
|
||||
- **задача закрывается процедурой проекта** — своей у пайплайна нет. Есть скилл
|
||||
или скрипт беклога — вызови его; нет — скажи в докладе, что задача сделана и
|
||||
закрытие остаётся за вызывающим. Не выдумывай формат чужого индекса.
|
||||
- воспроизведённый дефект (свой или чужой) — в раздел `## Прецеденты` брифа:
|
||||
класс, симптом, чем воспроизведён, чем закончилось. Это единственный артефакт,
|
||||
который делает следующее ревью умнее.
|
||||
|
||||
**Задачу пайплайн не закрывает.** Записи учёта — индекс, статус, спринт — он не
|
||||
трогает вовсе: закрытие происходит **после приёмки** и делается владельцем
|
||||
спринта, а пайплайн на этом шаге стоит до коммита и до всякой приёмки. Скриптов
|
||||
и скиллов учёта не зови — их у тебя и нет: пути между плагинами не разрешаются, и
|
||||
моста здесь намеренно не проложено. Твоё дело — назвать исход в докладе.
|
||||
|
||||
### 10. Коммит
|
||||
|
||||
@@ -242,13 +299,17 @@ description: Автономно проводит одну задачу чере
|
||||
сделано», тело списком 1–3 пункта, без трейлеров). Одна задача — один осмысленный
|
||||
коммит.
|
||||
|
||||
Готово — доложи кратко:
|
||||
Готово — доложи кратко. Доклад и есть выход пайплайна: **задача остаётся
|
||||
открытой**, её закрывает владелец спринта после приёмки.
|
||||
|
||||
- **исход** задачи одним из трёх слов и, если не «сделана», чем ограничен
|
||||
результат;
|
||||
- что сделано, какие вопросы записаны и куда;
|
||||
- ссылка на архивный change;
|
||||
- исход по каждому критерию приёмки, если они были;
|
||||
- ссылка на архивный change и хеш коммита;
|
||||
- по каждому критерию приёмки, если они были: **оракул и наблюдаемый исход** —
|
||||
это доклад приёмщику, а не отметка «принято»;
|
||||
- **`Урожай`** — отложенные находки списком (формулировка, оракул, провенанс).
|
||||
Задачи из него заводит тот, кто ведёт задачи проекта;
|
||||
- **одна строка границ покрытия**: какой профиль и режим гонялись, какие проходы
|
||||
не запускались и что проверить было невозможно. Доклад без неё сообщает
|
||||
«проверено», не сообщая, что именно.
|
||||
@@ -270,5 +331,4 @@ description: Автономно проводит одну задачу чере
|
||||
- **Занизить профиль ревью или пропустить проход — самый дешёвый способ
|
||||
«ускориться», и он же самый дорогой по последствиям.** Защита одна: профиль
|
||||
выбирается по факту изменения, состав сверяется поимённо, а непущенное
|
||||
называется в отчёте. Пропуск, названный строкой, стоит строки; пропуск молчащий
|
||||
стоил семи находок.
|
||||
называется в отчёте строкой.
|
||||
|
||||
Reference in New Issue
Block a user