Files

T

ревью по темам: документ проекта стал направлением проверки

Замечено при сверке документов канона с составом ступеней: три документа
остались без читателя ниже wide — security.md, database.md и adr/. Проект
поддерживал их, а на 90% задач не открывал никто. Причина оказалась не в
переезде проходов, а в том, как описан состав прогона.

Список тем нигде не был записан: он существовал побочным продуктом списка
проходов. Проход уезжал в верхнюю ступень — и тема уезжала с ним беззвучно.
Отчёт честно говорил «ops не запускался» и не говорил «эксплуатацию не смотрел
никто», а нужно второе. Теперь тема первична, проход вторичен — это правило 0
конвейера, а прогон описывается таблицей «тема → дом → глубина → кто закрывает»,
и таблица есть в каждом отчёте.

Тема есть документ, список открытый. Всё, что проект кладёт в docs/, становится
темой ревью; запретить нельзя, разрешения не надо. Не темы ровно две: docs/tasks/
и docs/review — настройка самого конвейера, слой над темами. Отсюда главное:
docs/ перестал быть документацией и стал конфигурацией конвейера. Проект
настраивает проверку тем, что пишет о себе, а не отдельным файлом настроек,
который разошёлся бы с документами. Ядро — requirements, autotests, conventions,
architecture, security, operations; всё сверх разбирает basics, потому что
именных проходов конечное число, а тем столько, сколько заведёт проект.

Тема живёт файлом или каталогом, на выбор проекта: docs/security.md и
docs/security/ — одно и то же. Прежде форма была задана поимённо и обосновать её
было нечем; заодно в TODO висел вопрос «а если architecture.md разрастётся».
Теперь ответ механический: разросся — стал каталогом с README.md, и это не смена
версии. Обе формы сразу — ошибка, docs.py её ловит.

Заведён review-scope, sonnet, стадия 0, до гейта: находит документы, выводит
темы, назначает глубины, выбирает ступень с обоснованием. Довод оказался сильнее
синхронизации документов — до сих пор профиль называл тот же оркестратор,
который написал код, то есть в точке выбора глубины проверки разведённости с
автором не было вовсе, а решала она под давлением «я почти закончил». Вызывающий
пайплайн профиль больше не передаёт. Поднять и понизить ступень разметчик вправе
одинаково, но обоснование обязательно всегда.

Sonnet ему хватает потому, что вывод устроен как список: каждый файл в docs/
обязан попасть в план темой или строкой «не тема, потому что», и план сверяется с
ls docs/ за секунду. Выбор ступени — суждение, но у него три независимых
корректора: отрицательный тест quick, правило «спорный случай вниз» и сигнал
basics о заниженной ступени.

Разметчик передаёт адреса, а не пересказ. Проект однажды уже держал
review-brief.md и убрал его: второй дом расходится с первым и выглядит
актуальным. Пересказ в задании — тот же посредник, живущий один прогон.
Исключение одно: отсутствие дома, этого проход сам дёшево не выяснит.

quick и standard совпали составом и разошлись глубиной — иначе требование
«нижние ступени закрывают все темы, просто не так глубоко» не выполняется.
Глубин три, и они про способ доказательства, а не про старательность: сверка
(открыть дом, открыть дифф, сравнить), разбор (построить сценарий рассуждением),
доказательство (прогнать, померить, построить путь). Третья есть только в wide.
Цена принята: это единственное место, где профиль не выводится из списка
проходов, поэтому глубина объявляется в отчёте наравне со ступенью.

review-code переписан, и это оказалось крупнее исходной находки: код как код не
читал никто. specs сверял с требованиями, basics — с отказами окружения,
architecture — с устройством, а code был проходом только по прозаическим
конвенциям и прямо объявлял, что рантайм и логика не его. «Здесь ошибка в логике»
не говорил вообще никто. Теперь у прохода две половины: девять классов
технического дефекта (необработанная ветка отказа, пустое и нулевое, граница
диапазона, перепутанный операнд, неосвобождённый ресурс, изменение под итерацией,
неверно применённый интерфейс библиотеки, недостижимая ветка, «сделано соседнее»)
и прежняя сверка с конвенциями. Модель поднята до opus по признаку темы 35: цена
пропущенной находки — дефект в проде.

Канон повышен до версии 5: форма дома на выбор, открытый список тем, AGENTS.md
законно лежит рядом с CLAUDE.md, «Вопросы к проходам» → «Вопросы по темам» (имя
прохода переезд не переживает, тема переживает), «Недоступно проверке» — тоже по
темам. docs.py переписан под темы: ловит двойной дом, принимает обе формы,
перечисляет свои темы проекта вместо «файл вне канона».

Побочно закрыт давний пункт TODO про каталожную форму architecture.md — решать
больше нечего.

Прогон от всего этого стал дороже, а не дешевле, впервые за сессию: плюс scope в
голове каждого прогона, плюс code на opus, плюс basics теперь и в quick. Куплены
разведённость выбора ступени, видимость непокрытых тем и технический разбор кода,
которого не было вовсе.

Тема 36 в DECISIONS.md, следствия 137-140.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-08-07 08:35:11 +03:00

12 KiB

Raw Blame History

Откуда проход берёт проектную конкретику

Конвейер общий, находки — проектные. Проход, не знающий, что в этом проекте нельзя нарушать, чем краснеет гейт и сколько данных реально идёт через узел, выдаёт правдоподобные общие места: их дорого опровергать и нечем подтверждать.

Отдельного файла-брифа нет. Проектная конкретика живёт в документах канона av-dev-pm, и проход читает их напрямую: пути жёсткие, посредник не нужен, а второй дом для тех же фактов разошёлся бы и выглядел актуальным.

Определение канона — в плагине av-dev-pm, skills/canon/references/canon.md. Здесь только карта «тема → её дом → что оттуда берётся».

Карта тем

Дом бывает файлом или каталогом — docs/security.md и docs/security/ называют одну и ту же тему. Форму дома называет план разметчика; проход её не угадывает.

Тема	Дом	Что оттуда берётся
`requirements`	`openspec/specs/`, `openspec/changes/<id>/specs/`	нормативное поведение и дельты изменения
`autotests`	`CLAUDE.md`, семантика гейта	команда гейта, чем краснеет безусловно, чего в нём нет, кто гоняет дорогое
`conventions`	`docs/conventions.*`	конвенции прозой и что уже механизировано правилом
`architecture`	`docs/architecture.*`	компоненты и capability, единые точки проекта
	`docs/passport.*`	что система делает и чего не делает, граница домена
	`docs/adr/`	почему решено так, отвергнутые варианты
`security`	`docs/security.*`	периметр, недоверенный вход, из чего строятся пути и ключи, что вне модели
`operations`	`docs/architecture.*`, раздел эксплуатации	окружение, внешние зависимости поимённо, наблюдатель, характер потока
	`docs/database.*`	чем физически лежит запись, что при чтении и записи, настройки с числовым значением
	`docs/research/`	измеренные числа с провенансом, поведение внешних систем на самом деле
тема проекта	её документ в `docs/`	то, что проект счёл нужным записать

Сквозное, не привязанное к теме:

Что нужно проходу	Где лежит
инварианты с severity рядом с формулировкой	`CLAUDE.md` (и `AGENTS.md`, если он рядом), раздел инвариантов
что запускать запрещено, с путями; `testdata`; куда писать временное; имя основной ветки	`CLAUDE.md`
типовые узлы, типовые ложноположительные, вопросы по темам, триггеры профиля, недоступно проверке	`docs/review.*`, раздел настройки
прецеденты: воспроизведённые дефекты с оракулом	`docs/review.*`, журнал

Вопросы проекта привязаны к теме, а не к имени прохода. Раньше блок в docs/review.md адресовался поимённо (ops: <вопрос>), и когда проход уехал в верхнюю ступень, вопрос перестал задаваться молча. Тема переезд прохода переживает.

Сшивать обязаны проходы

Раньше эти факты лежали рядом в одном файле, и соседство работало само. Теперь они разложены по домам, и проход обязан собрать их сам — иначе снимет верное число и честно понизит находку до гипотезы, потому что сравнить будет не с чем.

Два обязательных стыка:

замер + настройка. «Пик 768 МиБ» — аномалия только рядом со строкой «запись лежит сжатой и распаковывается целиком»; «блокировка удерживалась 5.019 с» — гарантированный отказ соседа только рядом с известным таймаутом занятости. Числа в docs/research/, настройки в docs/database.md, и оба читает ops и adversary.
инвариант + обратимость. severity берётся из CLAUDE.md; если её там нет — она выводится по обратимости последствия и помечается «выведена по обратимости», а не выдаётся за решение проекта.

У basics стыков нет, и это не упущение. Он не меряет, поэтому сшивать число с настройкой ему нечего; единственное его основание для critical — инвариант из CLAUDE.md, всё остальное он формулирует условиями и оставляет гипотезой. Его вход намеренно узкий: дома тем из плана плюс инварианты и журнал. Широкий вход — это профиль wide, и там он есть у architecture.

У scope стыков нет по другой причине: он не читает содержимого. Его дело — найти дома и раздать темы, а не пересказать написанное. Пересказ сделал бы его посредником между документом и проходом, а посредник расходится с источником и при этом выглядит актуальным.

Деградация — поразрядная

Документа нет — деградирует то, что из него читалось, и только оно. Каждый проход пишет свою строку в границы покрытия; триаж собирает их в один список и не сливает в одну строку: разные пробелы чинятся разным — периметр пишется руками за десять минут, а числа требуют замера.

Кто какой документ читает — не здесь. Полный список читателей ведёт канон (Skill av-dev-pm:canon, его references/canon.md, таблица «Кто читает»); ниже — только последствие отсутствия, и оно называет самое дорогое, а не всех пострадавших. Два списка читателей уже однажды разошлись; второго раза не надо.

Нет дома	Что деградирует
`CLAUDE.md` без инвариантов	`critical` по основанию «нарушен инвариант проекта» не присваивается никем
`docs/security.*`	тема `security` остаётся без дома: вопросы задаются по коду, `critical` не ставится, периметр неизвестен
`docs/research/`	числа неизвестны темам `operations` и `requirements` — формулируют условиями, а `specs` теряет проверку «требование против наблюдения»
`docs/database.*`	замер не с чем сравнить: находка темы `operations` не поднимается выше гипотезы
`docs/passport.*`	тема `architecture` теряет границу домена и вырождается в общее мнение
`docs/adr/`	«не отменяет ли изменение записанное решение» не спрашивает никто
`docs/review.*`	`triage` отсеивает вслепую: типовых ложноположительных нет; вопросы проекта по темам не задаются
`docs/conventions.*`	вторая половина `code` идёт вхолостую: записанных конвенций нет
`docs/architecture.*`	«не появился ли второй способ» не проверяется — единых точек не знает никто; тема `operations` теряет перечень внешних зависимостей

Строка в границах покрытия обязана называть причину: «docs/security.md в проекте нет» читается иначе, чем «есть, но периметр не назван». Без причины строка неотличима от «мы просто не стали» и перестаёт читаться на третьей задаче.

Документов канона нет вовсе — проект не приведён к канону. Это не повод работать вслепую: скажи об этом строкой и предложи av-dev-pm:canon. Одна операция на проект против деградации на каждой задаче.

Правило чтения

Читай в источнике, не по памяти. Документы правятся по ходу работы, в том числе этой же задачей.
Число без провенанса — условие, а не утверждение. Число, чей источник по ссылке не подтвердился, читается как условие и называется расходящимся, а не подменяется догадкой.
Пустое, названное пустым, — это факт. «Внешних зависимостей нет — смотри на диск и на СУБД» экономит обязательный вопрос. Отсутствие строки — не факт, а пробел, и его надо назвать в границах покрытия.
Свойство, ставшее правилом линтера, из конвенций удалено и лежит в перечне механизированного в docs/conventions/README.md. Проверять его проходом — тратить внимание на уже проверенное.

12 KiB Raw Blame History Unescape Escape