diff --git a/av-dev-code/agents/review-basics.md b/av-dev-code/agents/review-basics.md index 4c5176f..8f667a4 100644 --- a/av-dev-code/agents/review-basics.md +++ b/av-dev-code/agents/review-basics.md @@ -1,6 +1,6 @@ --- name: review-basics -description: "Тематический проход ревью для метки medium и приёмник проектных тем при любой метке. Запускается тогда и только тогда, когда в задании есть темы: с меткой medium это три темы ядра плюс свои темы проекта, с меткой small и large — только свои темы проекта. Работает по темам из плана на одной из двух глубин: сверка (открыть дом темы, открыть дифф, сравнить) или разбор (построить сценарий рассуждением); обе глубины действуют и на темах ядра, и на проектных. Ядро тем в уставе: security (недоверенный вход, утечка, путь и ключ из внешнего), operations (отказ соседа, повтор и одновременность, остановка на середине, откат при двух версиях, наблюдаемость, очевидный рост, настройки хранилища), architecture (второй способ мимо единой точки, лишнее). Ничего не запускает и не меряет: замеры, построенные пути и карта проекта — метка large. Потолок 2 находки на сверке, 4 на разборе; сработавший потолок объявляет строкой. Подтверждающий сигнал о заниженной метке (основной несёт code). Только чтение." +description: "Тематический проход ревью для метки medium и приёмник проектных тем при любой метке. Запускается тогда и только тогда, когда в задании есть темы: с меткой medium это три темы ядра плюс свои темы проекта, с меткой small и large — только свои темы проекта, а на прогоне без метки (сценарий обслуживания) — то, что назвал план, обычно operations на сверке. Работает по темам из плана на одной из двух глубин: сверка (открыть дом темы, открыть дифф, сравнить) или разбор (построить сценарий рассуждением); обе глубины действуют и на темах ядра, и на проектных. Ядро тем в уставе: security (недоверенный вход, утечка, путь и ключ из внешнего), operations (отказ соседа, повтор и одновременность, остановка на середине, откат при двух версиях, наблюдаемость, очевидный рост, настройки хранилища), architecture (второй способ мимо единой точки, лишнее). Ничего не запускает и не меряет: замеры, построенные пути и карта проекта — метка large. Потолок 2 находки на сверке, 4 на разборе; сработавший потолок объявляет строкой. Подтверждающий сигнал о заниженной метке (основной несёт code). Только чтение." tools: Read, Grep, Glob, Bash model: opus color: yellow @@ -22,6 +22,12 @@ color: yellow директива, и план так и скажет. Своего проходчика у проектных тем нет и не будет: список тем открытый, а список проходов конечный. +**Третья роль появляется на прогоне без метки** — так идёт сценарий +обслуживания, где изменение не меняет поведения и размечать нечего. Метки в +задании не будет; тему и глубину назовёт сам план, и работаешь ты ровно по нему. +Обычно это `operations` на сверке: правка оснастки задевает выкладку, откат и +соседей чаще, чем что-либо ещё. + **Ты запускаешься тогда и только тогда, когда тебе есть что принимать.** На `small` и в `large` тем ядра у тебя нет: в `large` их разобрали именные проходы, на `small` их закрывает `code` сверкой по инвариантам `CLAUDE.md`. При этих двух diff --git a/av-dev-code/agents/review-code.md b/av-dev-code/agents/review-code.md index f039fc5..c89059d 100644 --- a/av-dev-code/agents/review-code.md +++ b/av-dev-code/agents/review-code.md @@ -1,6 +1,6 @@ --- name: review-code -description: "Технический разбор кода изменения плюс сверка с конвенциями проекта — две половины одного прохода, обе при любой метке. Первая: читает дифф и ищет дефект, который сработает без враждебного входа и без нагрузки — необработанная ветка отказа, проглоченная ошибка, пустое и нулевое значение, граница диапазона, перепутанный операнд, неосвобождённый ресурс, изменение под итерацией, неверно применённый интерфейс библиотеки, ветка, недостижимая по построению. Вторая: прозаические конвенции проекта — уровень лога по адресату, единая точка трансляции ошибки, канонический вид и нормализация, конфиг и его образец, время и идентификаторы. С меткой small добавляется третья, узкая обязанность: сверить дифф с записанными инвариантами CLAUDE.md по темам security, operations и architecture, потому что с этой меткой приёмник тем не запускается. Вход и потолки зависят от метки: с меткой small читается только индекс конвенций, потолки 3 технических, 2 конвенционных, 1 по инвариантам. Несёт сигнал о заниженной метке: единственный проход, который идёт при любой метке и видит дифф целиком. Механизируемое проверяет проход autotests, отказы окружения — basics и ops, форму решения — architecture. Только чтение." +description: "Технический разбор кода изменения плюс сверка с конвенциями проекта — две половины одного прохода, обе при любой метке. Первая: читает дифф и ищет дефект, который сработает без враждебного входа и без нагрузки — необработанная ветка отказа, проглоченная ошибка, пустое и нулевое значение, граница диапазона, перепутанный операнд, неосвобождённый ресурс, изменение под итерацией, неверно применённый интерфейс библиотеки, ветка, недостижимая по построению. Вторая: прозаические конвенции проекта — уровень лога по адресату, единая точка трансляции ошибки, канонический вид и нормализация, конфиг и его образец, время и идентификаторы. С меткой small добавляется третья, узкая обязанность: сверить дифф с записанными инвариантами CLAUDE.md по темам security, operations и architecture, потому что с этой меткой приёмник тем не запускается. Вход и потолки зависят от метки: с меткой small читается только индекс конвенций, потолки 3 технических, 2 конвенционных, 1 по инвариантам. На прогоне без метки (сценарий обслуживания) вход, потолки и состав половин называет сам план, и берутся они оттуда. Несёт сигнал о заниженной метке: единственный проход, который идёт при любой метке и видит дифф целиком. Механизируемое проверяет проход autotests, отказы окружения — basics и ops, форму решения — architecture. Только чтение." tools: Read, Grep, Glob, Bash model: opus color: yellow @@ -17,7 +17,8 @@ color: yellow **Вторая — конвенции проекта.** Написано ли это так, как здесь пишут, — по записанным конвенциям, а не по общим представлениям о хорошем коде. -**С меткой `small` — третья половина, и она узкая.** Сверить дифф с +**С меткой `small` — и на прогоне без метки, если план включил её прямо, — +третья половина, и она узкая.** Сверить дифф с **записанными инвариантами** `CLAUDE.md` по темам `security`, `operations` и `architecture`. Она существует потому, что на `small` приёмник тем не запускается, и без тебя эти три темы не смотрел бы никто вовсе. На `medium` и в @@ -33,6 +34,11 @@ color: yellow Метка приходит в задании. **Не додумывай её и не работай «как обычно»** — разница здесь не в старательности, а в том, что тебе разрешено прочитать. +**Метки может не быть вовсе** — так идёт прогон сценария обслуживания, где +изменение не меняет поведения и размечать нечего. Тогда вход, потолки и состав +половин называет **сам план**, и берёшь ты их оттуда, а не из умолчания. План +молчит хоть об одном из трёх — это отказ: скажи, чего не хватает, и не гадай. + | | `small` | `medium` и `large` | |---|---|---| | дом конвенций | **только индекс**: перечень родов и пометки о механизированном | весь дом целиком, до чтения диффа | @@ -121,7 +127,8 @@ color: yellow `docs/conventions/`, форму дома называет план прогона. Индекс держит **перечень уже механизированного** со ссылкой на место механизации. -**Сколько ты из этого дома читаешь, решает метка.** +**Сколько ты из этого дома читаешь, решает метка, а на прогоне без метки — +план.** - **`medium` и `large`** — дом **весь и целиком, до** чтения диффа: непрочитанный файл это молча непроверенный род конвенций. @@ -210,10 +217,12 @@ color: yellow - **Тесты разбора — на реальных данных**, с проверкой идемпотентности повторного разбора. -## Половина третья — только на `small`: темы ядра против инвариантов +## Половина третья — на `small` и по прямому указанию плана: темы ядра против инвариантов С меткой `small` приёмник тем не запускается, и темы `security`, `operations` и -`architecture` остаются за тобой. **Работа узкая и точно очерченная: взять +`architecture` остаются за тобой. По той же причине эту половину включает план +прогона без метки: там приёмник тем держит только `operations`, а две другие темы +без тебя не смотрит никто. **Работа узкая и точно очерченная: взять записанные инварианты `CLAUDE.md` и сверить с ними дифф.** - `security` — инвариант про недоверенный вход, границу периметра, секреты; diff --git a/av-dev-code/agents/review-triage.md b/av-dev-code/agents/review-triage.md index dfc9ddf..50f5267 100644 --- a/av-dev-code/agents/review-triage.md +++ b/av-dev-code/agents/review-triage.md @@ -145,7 +145,7 @@ severity: ``` - **инлайн** — оркестратор чинит сам, не спрашивая и не логируя. Правка локальна, - решение однозначно, объём right-size. + решение однозначно, объём — по размеру находки. - **развилка** — цена сопоставима с переработкой, либо меняется scope, либо трогается инвариант из `CLAUDE.md`, либо надо менять спеку. Формулируй готовым вопросом с 2–3 вариантами: оркестратор перенесёт его почти дословно. diff --git a/av-dev-code/skills/resolve/references/maintain.md b/av-dev-code/skills/resolve/references/maintain.md index c2c9ae3..1c4377a 100644 --- a/av-dev-code/skills/resolve/references/maintain.md +++ b/av-dev-code/skills/resolve/references/maintain.md @@ -11,9 +11,9 @@ записанного вопроса, правило необратимого — живёт в SKILL.md и тут не пересказывается. -## Почему цикл SDD здесь не урезан, а не имеет входа +## Почему цикл SDD здесь не урезан, а остался без входа -Это не поблажка по цене, и формулировать её как «мелкая задача — короткий путь» +Это не поблажка по цене, и называть сценарий «коротким путём для мелких задач» нельзя: путь, выбираемый по самооценке размера, и есть тот самый дешёвый способ «ускориться», против которого написана вся защита сценария решения. @@ -24,7 +24,7 @@ их в актуальные спеки. Change без дельт — пустой артефакт, который потом надо архивировать, и разметчик по нему назовёт не те темы. -То есть механика цикла остаётся не пропущенной, а **без входа**. Отсюда и состав +Шаги цикла здесь не пропущены — **им нечего обрабатывать**. Отсюда и состав сценария: выпали ровно те шаги, у которых нет предмета, и не выпал ни один из тех, у которых он есть. @@ -106,10 +106,8 @@ прогоном, при отказе — человек решает сам, откатить или оставить. Коммитить его сообщением про обслуживание нельзя. -**Это единственное место сценария, где ждут ответа**, и плановым стопом оно не -становится: плановый стоп проходят все прогоны, а этот — только те, где задача -оказалась не тем, чем объявлена. Прогон, дошедший до него, стоит дороже обычного -— и это довод за проверку признака на шаге 1, а не после написанного кода. +**Прогон, дошедший до этого стопа, стоит дороже обычного** — и это довод за +проверку признака на шаге 1, а не после написанного кода. ## OpenSpec здесь не предпосылка @@ -155,7 +153,7 @@ flowchart TD in --> s1 --> s2 --> s3 --> s4 --> s5 --> s6 --> s7 --> out s1 -.->|"форма правки неизвестна"| stop1["стоп: нужна разведка"] - s2 -.->|"меняется дельта-спека"| stop2["стоп: идёт решением,
следующим прогоном"] + s2 -.->|"нашлась дельта-спека"| stop2["стоп: назвать тип,
объяснить, дать два решения"] ``` Схема — **сводка**: содержание каждого шага в его разделе ниже, и при расхождении @@ -178,8 +176,8 @@ flowchart TD дорогой откат, намеренный отказ от очевидного подхода, пересмотр прежнего решения. Стоп с названной причиной, разведка идёт следующим прогоном. -**Последний исход — не редкость, и его стоит ждать.** Незнакомое обслуживание это -выбор подхода с ценой и с тем, что становится невозможным, — предмет чекпоинта +**Последний исход — не редкость, и его стоит ждать.** Незнакомое обслуживание — +это выбор подхода с ценой и с тем, что становится невозможным, — предмет чекпоинта вариантов, а не работы без стопа. И там же решение получает законный источник для ADR: список источников канон закрыл двумя — архивный `design.md` и записка разведки, — а обслуживание не производит ни того ни другого. @@ -222,11 +220,11 @@ ADR: список источников канон закрыл двумя — а ### 2. Сделать правку -Код и конфиги — по конвенциям проекта. Правка right-size: чинится названное в -записи, а соседнее не золотится по пути. +Код и конфиги — по конвенциям проекта. Правка по размеру задачи: чинится названное в записи, соседнее не улучшается +заодно. **Гейт правится — сверь состав, а не цвет.** Красный, ставший зелёным, виден -сразу; «проверок стало на две меньше, обе зелёные» не видно ничем, а это самая +сразу; убыли проверок гейт не покажет — он зелёный и до, и после. Это самая дорогая из возможных правок оснастки: молча выключено то, чем проверяется всё остальное. Состав проверок и способ его снять — **дело проекта**: он объявляет их семантикой гейта в `CLAUDE.md`. Снимай исходное состояние **до** правки, по @@ -258,17 +256,28 @@ Change ты не передаёшь — его нет. которой здесь нет (незнакомое ушло в разведку шагом 1). Разметчик без своего корпуса вернул бы метку, выведенную из ничего. -Поэтому план у сценария **свой и постоянный**: +Поэтому план у сценария **свой и постоянный**, и глубину он называет сам — +проходы берут её из метки, а метки здесь нет: -| Тема | Дом | Кто закрывает | Когда | -| --- | --- | --- | --- | -| `autotests` | `CLAUDE.md`, семантика гейта | `review-autotests` | всегда | -| `operations` | `architecture.*`, раздел эксплуатации | `review-basics`, глубина «сверка» | всегда | -| `conventions` + технический разбор | `conventions.*` | `review-code` | дифф трогает код, а не только оснастку | +| Тема | Дом | Кто закрывает | Глубина и вход | Когда | +| --- | --- | --- | --- | --- | +| `autotests` | `CLAUDE.md`, семантика гейта | `review-autotests` | как обычно: гейт запускается целиком | всегда | +| `operations` | `architecture.*`, раздел эксплуатации | `review-basics` | **сверка**: дом темы против диффа, потолок 2 | всегда | +| `conventions` + технический разбор | `conventions.*` | `review-code` | вход `small`: только индекс конвенций; потолки 3 технических и 2 конвенционных; **третья половина включена** — сверка с инвариантами `CLAUDE.md`, потолок 1 | дифф трогает код, а не только оснастку | + +**Глубина названа в плане потому, что иначе её неоткуда взять.** Вход и потолки +`review-code` заданы меткой, у `review-basics` меткой задана и сама возможность +запуска; на прогоне без метки оба взяли бы их наугад — то есть по-разному от +прогона к прогону, и молча. + +**Третья половина `review-code` включена намеренно.** В конвейере она живёт при +метке `small`, где приёмник тем не запускается, и сверяет дифф с записанными +инвариантами `CLAUDE.md` по темам `security`, `operations` и `architecture`. +Здесь у неё та же работа: без неё `security` не смотрит вообще никто. Триаж обязателен, как и на всяком прогоне: он единственный сток и единственный, -кто сверяет план с исходом. План на его входе — не формальность: тема, -оставшаяся без отчёта, видна только ему. +кто сверяет план с исходом. На его вход подаётся этот план — вместо плана +разметки, которого нет. **Условие третьей строки проверяемое, и смотрится оно по диффу**, а не по намерению: обновление зависимости или правка файла CI кода не трогают, чистка и @@ -276,10 +285,20 @@ Change ты не передаёшь — его нет. «здесь ошибка в логике», и чистка, прошедшая без него, проверена только на то, что она собирается. -**Границы покрытия называются полностью.** Темы `requirements` и `security` в -плане нет: у первой нет предмета — дельта-спек не существует, у второй нет -проходчика на этом сценарии. Обе уезжают в доклад строкой. Отчёт, из которого -исчезло «что не смотрел никто», сообщает «проверено», не сообщая, что именно. +**Сигнал о заниженной метке на этом прогоне не работает** — метки нет, и +поднимать нечего. Его место занимает признак сценария: показалось, что глубины +мало, потому что задача крупнее заявленного, — ищи дельту, а не метку. + +**Границы покрытия называются полностью:** + +- `requirements` — предмета нет, дельта-спек не существует; +- `security` — своего прохода нет; сверена против записанных инвариантов внутри + `review-code`, а он шёл не всегда. Не шёл — тему не смотрел никто, и это + говорится прямо; +- `architecture` — то же: только против инвариантов, и только если шёл `code`. + +Отчёт, из которого исчезло «что не смотрел никто», сообщает «проверено», не +сообщая, что именно. Отработка — как в решении: помеченное `инлайн` чини сам и не логируй, `развилка` — вопросом в запись. После правок снова гейт. Отложенные находки собери в секцию @@ -369,8 +388,9 @@ Change ты не передаёшь — его нет. - **состав гейта до и после**, если правка его трогала; не сверялся — почему; - по каждому критерию приёмки: **оракул и наблюдаемый исход**; - **`Урожай`** — отложенные находки списком; -- **строка границ покрытия**: план сценария фиксирован, `requirements` и - `security` на этом прогоне не смотрел никто, и разметчик не запускался. +- **строка границ покрытия**: план сценария фиксирован, разметчик не запускался, + `requirements` не смотрел никто, а `security` и `architecture` — только против + записанных инвариантов, и то если шёл проход `code`. ## Тонкости сценария diff --git a/av-dev-code/skills/resolve/references/solve.md b/av-dev-code/skills/resolve/references/solve.md index 7e5977a..034d5b9 100644 --- a/av-dev-code/skills/resolve/references/solve.md +++ b/av-dev-code/skills/resolve/references/solve.md @@ -396,7 +396,8 @@ flowchart TD - Гейт блокирует: пока он красный, опиниативные проходы не запускаются. Чинить и перезапускать, а не «посмотреть заодно». -- Стиль правок — заточка под проект и конвенции, right-size, без золочения. +- Стиль правок — заточка под проект и конвенции, по размеру задачи, без + улучшений заодно. - **Занизить метку ревью, пропустить тему или проскочить чекпоинт — самый дешёвый способ «ускориться», и он же самый дорогой по последствиям.** Защита устроена так, что регулятора у тебя нет: метку выбирает разметчик **до того**, как ты diff --git a/av-dev-code/skills/review/SKILL.md b/av-dev-code/skills/review/SKILL.md index 3c4a5da..43b393c 100644 --- a/av-dev-code/skills/review/SKILL.md +++ b/av-dev-code/skills/review/SKILL.md @@ -654,20 +654,26 @@ change**: у работы, не меняющей поведения, дельт Разметчик без своего корпуса вернул бы величину, выведенную из ничего, — и это хуже отсутствующей метки, потому что выглядит измеренным. -**План приходит вызовом и фиксирован сценарием**, а не выводится здесь: +**План приходит вызовом и фиксирован сценарием**, а не выводится здесь. **Он же +называет глубину и вход каждого прохода** — их обычный источник метка, и без неё +проходы взяли бы их наугад: -| Тема | Кто закрывает | Когда | -|---|---|---| -| `autotests` | `review-autotests` | всегда | -| `operations` | `review-basics`, глубина «сверка» | всегда | -| `conventions` + технический разбор | `review-code` | дифф трогает код, а не только оснастку | +| Тема | Кто закрывает | Глубина и вход | Когда | +|---|---|---|---| +| `autotests` | `review-autotests` | как обычно | всегда | +| `operations` | `review-basics` | сверка, потолок 2 | всегда | +| `conventions` + технический разбор | `review-code` | вход `small` (индекс конвенций), потолки 3 и 2, третья половина включена — потолок 1 | дифф трогает код | Триаж обязателен и здесь — он единственный сток и единственный, кто сверяет план -с исходом. Темы `requirements` и `security` в плане отсутствуют: у первой нет -предмета, у второй нет проходчика на этом сценарии, — и обе обязаны быть названы -в границах покрытия. Дом плана — сценарий, а не этот скилл: -`av-dev-code:resolve`, `references/maintain.md`, раздел «Ревью — план фиксирован -сценарием». +с исходом; на его вход подаётся этот план вместо плана разметки. Тема +`requirements` в плане отсутствует за отсутствием предмета; `security` и +`architecture` закрыты только сверкой с записанными инвариантами внутри `code` — +третья половина этого прохода включается здесь по той же причине, что и при +метке `small`. Все три обязаны быть названы в границах покрытия, а **сигнал о +заниженной метке на таком прогоне не работает**: поднимать нечего. + +Дом плана — сценарий, а не этот скилл: `av-dev-code:resolve`, +`references/maintain.md`, раздел «Ревью — план фиксирован сценарием». **Правило гейта на таком прогоне работает жёстче обычного.** Правка, которая трогает сам гейт, проверяется гейтом же — инструмент проверяет себя, — поэтому @@ -865,6 +871,10 @@ Recall темы `conventions` равен длине конвенций прое стартует. Получает сырые выводы всех проходов, `git diff`, режим и **план разметки задачи**; возвращает финальный отчёт. +**На прогоне без change его место занимает план сценария** — см. «Прогон без +change»: сверять исход с планом триаж обязан и там, а другого плана в том прогоне +не существует. + **План на входе у триажа — не формальность, а сверка.** Он единственный, кто видит и то, что размечено, и то, что пришло: «тем размечено шесть, отчёты покрывают пять» — находка о самом прогоне, и заметить её больше некому. Раньше он diff --git a/av-dev-tasks/skills/tasks/SKILL.md b/av-dev-tasks/skills/tasks/SKILL.md index 7814f8f..4005670 100644 --- a/av-dev-tasks/skills/tasks/SKILL.md +++ b/av-dev-tasks/skills/tasks/SKILL.md @@ -296,11 +296,19 @@ stateDiagram-v2 **напоминает** — беклог, заведённый до появления типа, законен, и переоформлять его «заодно» здесь не просят. -**Тип не выбирает метку ревью и вообще ничего не предписывает конвейеру.** -Профиль выбирается по факту изменения, а не по типу задачи: `chore` бывает -миграцией схемы, `fix` — правкой публичного контракта. Правило «предписание -процесса в теле задачи снимается» типом не отменяется, а подтверждается: он -описывает работу, а не то, как её проверять. +**Тип не выбирает метку ревью и глубину проверки.** Профиль выбирается по факту +изменения, а не по типу задачи: `chore` бывает миграцией схемы, `fix` — правкой +публичного контракта. Правило «предписание процесса в теле задачи снимается» +типом не отменяется, а подтверждается: он описывает работу, а не то, как её +проверять. + +**Одно исполнителю тип всё же говорит — каким сценарием работу вести, и то не +один.** В плагине `av-dev-code` скилл `resolve` выбирает сценарий связкой из двух +признаков: тип **предлагает** (`chore` — обслуживание, `research` — разведка), +а подтверждает его предмет работы — есть ли что менять в спеках. Признаки +разошлись — работа останавливается, и тип меняется здесь, командой `edit --type`, +а не переклеивается исполнителем по ходу. Метку и глубину это по-прежнему не +задаёт: их называет разметка изменения, а на прогоне без change — сам сценарий. ## Как написана задача