av/dev-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

av-dev-pipeline: бриф удалён, проходы читают документы канона напрямую

Browse Source 
- удалены скилл project-brief и контракт брифа; вместо них references/
  project-facts.md — карта «что нужно проходу → где лежит» и таблица
  поразрядной деградации по документам
- девять charter'ов, review-pipeline, task-pipeline и task-batch переписаны
  на пути канона; OpenSpec стал объявленной предпосылкой без ветки деградации
- шаг синка документации переписан в построчный доклад, закрытие задачи —
  вызовом скилла av-dev-pm:tasks вместо строки-слота из CLAUDE.md
- по находкам ревью: docs.py звал tasks.py из чужого каталога и выдавал его
  отказ окружения за дрейф; сверка миграций не видела рабочее дерево;
  плейсхолдер краснел вместо замечания; сверка capability проходила по
  совпадению с именем пакета; tasks.py не читал docs/.pm.json; скилл docs
  пересказывал канон в пяти местах
This commit is contained in:
av
2026-08-03 14:28:55 +03:00
parent ad1779b81f
commit 9cef45252c
26 changed files with 687 additions and 1232 deletions
Download Patch File Download Diff File Expand all files Collapse all files
av-dev-pipeline/skills/review-pipeline/references/brief-template.md
-289
View File
@@ -1,289 +0,0 @@
# Шаблон брифа проекта
Образец заполнения. Контракт разделов — в
[project-brief.md](project-brief.md); заводит бриф по этому образцу скилл
`av-dev-pipeline:project-brief` — руками копировать не надо, но читать полезно.
Курсивом даны пояснения — их из готового брифа убирают. Примеры взяты из двух
разных проектов (коллектор данных с непрерывным потоком и связующий сервис вокруг
внешних демонов), чтобы было видно, как один и тот же раздел выглядит при разной
природе проекта.
---
## Проект
*Абзац: что делает — и чего не делает.*
> Коллектор выгрузок с телефона. Принимает доставки, хранит их и отдаёт другим
> сервисам. Это **хранилище, а не аналитика**: принять, дедуплицировать,
> сохранить, отдать. Не переименовывать поля источника, не интерпретировать
> значения; свёртка считается только в ответе на запрос.
> Связующий сервис между качалкой и медиасервером: принимает задание, качает,
> распознаёт содержимое, раскладывает файлы ссылками. **Не медиатека и не
> плеер** — ничего не хранит сверх метаданных о раскладке.
## Инварианты
*Проверяемое свойство + последствие + severity по умолчанию. Цитируются
формулировкой. Severity проект обычно не пишет — тогда она выводится по
обратимости и помечается: «по умолчанию `critical` (выведена по обратимости)».*
- **Точка сохраняется дословно.** Незнакомое поле не отбрасывается, число не
округляется при записи. Нарушение — необратимая потеря: сырой архив живёт
14 дней, дальше истина только в свёртке. По умолчанию `critical`.
- **Источник неприкосновенен.** Только `mkdir`/`link(2)`/`unlink` собственных
ссылок; файлы под каталогом загрузок не трогаются никогда. Нарушение —
повреждение чужих данных, необратимое. По умолчанию `critical`.
- **Сохранили — значит приняли.** Код ответа отражает доставку, а не разбор:
непонятое содержимое — `200`, тело уже на диске. Нарушение стоит доставки,
которую отправитель не повторит. По умолчанию `critical`.
- **Секреты и данные пользователя не в логах.** Тело запроса — только на `DEBUG`
и с обрезкой. По умолчанию `critical`.
- **Агрегации при записи нет.** Нарушение искажает историю молча и
диагностируется только сверкой с внешним источником, то есть месяцами позже.
По умолчанию `major`, `critical` — если испорченное невосстановимо.
## Гейт
- **Команда:** `task gate BASE=<база>`; база по умолчанию —
`git merge-base HEAD master`, на `master` — `HEAD~1`.
- **Логи шагов:** `tmp/gate/<шаг>.log`. Сводка печатает `OK`/`FAIL`/`WARN`/`SKIP`;
краснит гейт только `FAIL`.
- **Шаги:** сборка, `vet`, линтеры, форматирование, тесты, повторный прогон на
флаки, `-race`, покрытие изменённых строк, накат миграций с нуля, поиск
секретов, `govulncheck`.
- **Красят безусловно** *(перечислить с причиной — это главная часть раздела)*:
- `no-user-data` — файл из каталога данных попал под контроль версий: убрать
обычным коммитом уже нельзя;
- `config-samples` — структура конфига изменилась, а образец нет: забытое поле
обнаруживается не тестом, а тем, что через полгода о нём никто не знает;
- `migrations` — миграции не накатываются с нуля: восстановление перестаёт
работать ровно тогда, когда оно нужно;
- `er-schema` — миграция тронута, а схема в документации не обновлена.
- **Чего в гейте намеренно нет:** прогон на живом корпусе (`task verify:archive`)
— минута работы и данные, которых нет ни на какой другой машине. У этой
проверки краснота не видна никому до следующей задачи, которая до неё
дотянется, — говори об этом в границах покрытия.
## Команды
- Карта проекта для архитектурного прохода: `task review:context > tmp/review-context.md`
- Поднять изменение вживую: `task restart`, логи — `task logs`
- Тесты и линт: `task test`, `task lint`
- **Дорогое вне гейта, с адресатом:** `task verify:archive` (минута, живые
данные). **Кто и когда обязан:** пайплайн задачи — после любого изменения
разбора входного формата или правила слияния, до архивации change; вручную —
человек перед выкладкой. Не прогонялась — строка в границы покрытия, а не
молчание.
- **Запускать запрещено:** ничего, что пишет в `./data`, в рабочую БД и в боевой
каталог архива. Замеры — только на копиях в `./tmp`.
## Прод и поток
*Первая строка — главный вопрос эксплуатации этого проекта.*
> **Главный вопрос:** поток идёт непрерывно и молча, отправитель об отказе не
> узнает и не повторит — значит, дороже всего тихо потерянная доставка, а не
> упавший сервис.
> *(В сервисе, который сам опрашивает чужих демонов, первая строка была бы
> противоположной: «главный вопрос — что происходит, когда внешний сервис
> отвечает медленно, а не когда он упал».)*
- **Где:** один статический бинарь в контейнере на домашнем сервере, перед ним
обратный прокси с TLS, SQLite на диске. Ни оркестратора, ни реплик, ни дежурной
смены.
- **Внешние зависимости и как каждая отказывает:** прокси — рвёт соединение на
длинном теле; диск — заполняется и тормозит; СУБД — отдаёт «занято» под
параллельной записью; приложение-источник на телефоне — молча перестаёт слать.
*(В другом проекте здесь были бы качалка, медиасервер, LLM и база метаданных, и
каждая — со своим «отвечает медленно», а не только «упала».)*
*(Если зависимостей нет — так и пишут: «внешних зависимостей нет, смотри на
диск и на СУБД». Пустой пункт называется пустым.)*
- **Кто заметит отказ:** один пользователь-владелец, в лучшем случае вечером, а
скорее не заметит вовсе.
- **Характер потока:** телефон шлёт непрерывно и молча; обратной связи у
отправителя нет, об отказах он не сообщает, расписание плавает. Тихо
сломавшаяся доставка — главный эксплуатационный риск.
- **Представление данных и настройки хранилища:** запись — сжатый BLOB, читается
и пересобирается целиком на каждой операции (`internal/store`); журнал СУБД —
WAL; таймаут занятости — 5000 мс (`config.example.toml`); лимит тела приёма —
64 МБ; ретеншен сырого архива — 14 дней.
- **Числа (с провенансом):** нижний слой — порядка 135 тыс. точек в сутки
(замер, `docs/local-research.md`); тела доходили до 42 МБ (там же); запись —
read-modify-write под конкурентными доставками (`docs/architecture.md`).
- **Обратимость:** падение сервиса обратимо — отправитель дошлёт широким
проходом. Потеря или порча точки необратима. Поэтому тихая порча весит больше,
чем «сервис вернул 500».
## Модель угроз
*Первая строка — периметр.*
> **Периметр:** сервис открыт наружу через обратный прокси, недоверенным считается
> всё, что приходит по HTTP. Злоумышленник в локальной сети — вне периметра.
> *(У сервиса в доверенном контуре первая строка противоположна: «контур
> доверенный, публичного интернета здесь нет — не выдумывай его; недоверенное
> здесь — то, что отдают внешние демоны и трекеры».)*
> *(Контур ещё не развёрнут — тогда периметров два: «целевой — за прокси с TLS;
> сегодняшний — только локальная машина, токены пусты осознанно. **Находки
> строятся против целевого**, отсутствие TLS сегодня находкой не является».)*
- **Недоверенное:** тело доставки целиком (имена метрик, единицы, формы точек,
метки времени, глубина вложенности, размер); заголовки доставки, часть которых
участвует в решениях; содержимое архива внешнего экспорта (имена файлов внутри
zip мы не формировали); параметры читающего API.
- **Из чего строятся пути и ключи:** файл сырого архива —
`raw/ГГГГ/ММ/ДД/<ulid>.json.gz`, дата берётся из времени приёма, имя — из
генератора идентификаторов; ключ записи — `метрика + слой + начало + конец`,
источник в ключ не входит.
- **Разграничение:** статические токены в `Authorization: Bearer`, раздельные на
запись и на чтение; конфиг под `0600`.
- **Что дороже:** данные пользователя дороже токена. Путь, по которому значение
доезжает до лога выше `DEBUG`, до ответа с ошибкой или до `testdata` в git, —
полноценная находка, а не замечание по гигиене.
- **Вне модели:** злоумышленник в локальной сети; вредоносный оператор;
компрометация поставщика данных; мультиарендность. Находки этих классов не
выводятся — они никогда не будут исправлены.
## Карта
- **Основная ветка:** `master`. От неё берутся ветки задач, в неё вливается батч,
база диффа по умолчанию — `git merge-base HEAD master` (на самой ветке `HEAD~1`).
- Актуальные спеки: `openspec/specs/<capability>/spec.md`
- Дельта-спеки изменения: `openspec/changes/<id>/specs/*/spec.md`
- **Нарезка capability и что из неё переехало в спеки:** режем по домену
(`ingest`, `storage`, `read-api`, `mcp`), а не по транспорту. В актуальные
спеки перенесены `ingest` и `storage`; `read-api` описан только в
`docs/architecture.md`, `mcp` — пока только в коде. Пробел в спеке по этим двум
темам — не находка, а известное состояние.
- Конвенции прозой: `docs/conventions.md` *(в другом проекте это каталог из
нескольких файлов — тогда перечисляют все:
`docs/conventions/{logging,errors,config,database,web-ui}.md`)*. Механизировано
и потому **не проверяется проходом по конвенциям**: форма логов,
`fmt.Print*`/`os.Getenv`/`time.Now` мимо единых точек, сравнение ошибок,
сторонние пакеты ошибок — всё это правила в `.golangci.yml`.
- Архитектура и решения: `docs/architecture.md`
- **Наблюдения на живых данных:** `docs/local-research.md` — что реально шлёт
источник и чем это расходится с его документацией. *(Не ведём — так и пишут:
«наблюдений на живых данных не ведём».)*
- Журнал проскочивших дефектов: `docs/review-journal.md`
- **Единые точки:** идентификаторы — `internal/ident`; время — `store.Now()`;
разбор дат входного формата — один парсер в `internal/parse`; маппинг доменной
ошибки в код ответа — одна точка в `internal/httpapi`; путь приёма — `ingest`,
общий для HTTP и CLI. Инвентарь целиком выгружает `task review:context`.
- **Нумерованные артефакты:** миграции — `internal/store/migrations/NNNN_*.sql`,
номер монотонный, следующий свободный смотреть там же.
- Задачи: `docs/backlog/` *(пайплайн только читает и сообщает исход)*
- Реальные пакеты для тестов разбора: `internal/parse/testdata` — там данные
пользователя с вычищенными токенами, наружу не копировать
- Временное: `./tmp` (не системный `/tmp`)
- **Не трогать:** `./data` — боевой архив и БД
## Типовые узлы
*Род узла + 3–5 специфичных проверяемых свойств.*
- **Разбор входного формата** — поведение на усечённом и враждебном входе,
границы размера, отсутствие паники, детерминизм, судьба незнакомых полей.
- **HTTP-обработчик приёма** — валидация формы конверта до записи, лимит тела и
архивная бомба, что попадает в ответ, а что в лог, отсутствие доменной логики
в транспорте.
- **Обработчик читающего API** — предсказуемость размера ответа, поведение при
пустом диапазоне, коды ответа на невозможный запрос.
- **Репозиторий** — границы транзакции, конкурентная запись того же ключа,
откуда берутся время и id, что возвращается при отсутствии записи,
идемпотентность повторной записи.
- **Файловое хранилище с ретеншеном** — атомарность записи, поведение при
неполной записи и нехватке места, что удаляется и по какому критерию, можно ли
удалить лишнее.
- **CLI-команда пересборки** — идемпотентность повторного прогона, поведение при
отмене на середине, что остаётся после падения, отчёт для человека.
- **Клиент внешнего сервиса** — таймаут, протяжка `context`, поведение при
«медленно» против «упало», ретраи и их граница.
## Прецеденты
*Воспроизведённые случаи этого проекта: класс — симптом — чем воспроизведён —
чем закончилось. Прецедентов нет — так и пишут: «прецедентов не накоплено».*
- **Вырожденный ответ библиотеки, неотличимый от штатного.** Симптом: пересборка
докладывала «журнал разобран целиком», а часть записей не доезжала. Причина:
контрольная точка журнала СУБД под занятой блокировкой возвращала `-1` вместо
пары чисел, и сравнение `-1 >= -1` читалось как успех — 1492 тика из 5502.
Воспроизведено экспериментом на стенде (`tmp/probe-checkpoint/`), из
документации драйвера не следовало. Закончилось: явная проверка вырожденного
значения + вопрос 8 в эксплуатационном проходе.
- **Канонизация внутри транзакции.** Симптом: соседняя доставка получала «база
занята». Причина: пересборка держала блокировку записи 5.019 с при таймауте
занятости 5000 мс — канонизация и хеширование шли внутри транзакции.
Воспроизведено замером на копии БД. Закончилось: вынос канонизации из
транзакции; числа — в раздел `## Прод и поток`.
- **Пик памяти на распаковке.** Симптом: контейнер убивался по памяти на крупных
доставках. Причина: сжатая запись распаковывалась целиком, пик 768 МиБ на теле
40 МБ. Воспроизведено прогоном на реальном пакете из `testdata`. Закончилось:
потоковая обработка; факт «запись — сжатый BLOB» вынесен в бриф, потому что без
него замер не читается как аномалия.
## Типовые ложноположительные
*Находки, которые здесь выглядят убедительно и всегда неверны. Пусто — так и
пишут.*
- «Значения из входа надо нормализовать перед записью» — инвариант требует
дословного хранения; нормализация тут порча, а не улучшение.
- «Приём должен отвечать ошибкой на непонятое содержимое» — инвариант «сохранили
— значит приняли»; отправитель доставку не повторит.
- «Порядок ключей в JSON стабилен, канонизация избыточна» — наблюдение на живых
данных говорит обратное.
- «Вынести в конфиг» про значения, заданные внешним форматом.
## Вопросы к проходам
*Производные от журнала: вопрос конкретному проходу плюс ссылка на запись, из
которой он взялся. Пусто — так и пишут.*
- `ops`: что произойдёт при откате бинаря поверх уже накатившейся миграции —
стартует ли старая версия молча (журнал, запись 2026-05-12).
- `adversary`: имена файлов внутри архива внешнего экспорта мы не формировали —
проверь путь от имени в архиве до операции с файловой системой (журнал, запись
2026-06-03).
## Триггеры
- `deep`: миграция в `internal/store/migrations/`, новый пакет `internal/*`,
изменение контракта читающего API, правило слияния или вывод слоя.
- «Видимое снаружи» (то есть `standard`): эндпоинт, форма ответа, код ответа
приёма, формат лога.
- `reimpl` запускается, когда изменение вводит **новое правило слияния,
идентичности или разбора**.
## Недоступно проверке
### Не проверит ни один проход
*Принципиальные границы. По факту промаха не пересматриваются.*
- Поведение внешнего приложения-источника на следующем его обновлении.
- Что реально лежит в системе-источнике: сверить можно только ручным экспортом,
а он делается раз в 2–3 месяца.
- Поведение таблицы под объёмом нескольких лет истории и реальный профиль
нагрузки.
- Завязка внешних потребителей на текущую форму ответа.
- Суждение «этой функциональности не должно существовать».
### Перестали проверять сознательно
*Что, когда, почему и где записано. Пересматривается первым, как только что-то
проскочило. Пусто — так и пишут: «сознательно ничего не отключали».*
- **Поимённая сверка со стайлгайдами языка** — с 2026-05, вместе с упразднением
прохода про идиоматичность (журнал ревью, запись 2026-05-04). Класс обратимый:
портит форму кода, не данные.
- **Правило линтера про длину функции** — снято 2026-06-18: ложных срабатываний
больше трети (журнал, там же). Вернуть, если проскочит дефект «функция делает
три вещи».
av-dev-pipeline/skills/review-pipeline/references/calibration.md
+1 -1
View File
@@ -45,7 +45,7 @@
Отсюда два следствия:
- **правка charter'а — правка для всех проектов.** Прежде чем сужать
формулировку под свою боль, проверь, не место ли ей в брифе: предмет проверки
формулировку под свою боль, проверь, не место ли ей в документах проекта: предмет проверки
живёт там, метод — в charter'е;
- **удаление прохода из плагина требует замера на двух проектах**, а не на одном:
класс, не всплывший здесь, мог быть единственным работающим там.
av-dev-pipeline/skills/review-pipeline/references/finding-contract.md
+5 -5
View File
@@ -32,12 +32,12 @@
- **Находка без поля «Последствие» не выводится вовсе.** Пустое «Последствие:
ухудшает читаемость» равносильно отсутствию поля.
- **`nit` допустим только при нарушении записанной конвенции** — со ссылкой на
файл и раздел конвенций проекта (путь — из раздела `## Карта` брифа) либо на
файл и раздел конвенций проекта (`docs/conventions/`) либо на
правило линтера. Если правило механизируемо, но не механизировано — это не
находка ревью, это `Promote candidate` (см. [promote.md](promote.md)).
- **`critical` по основанию «нарушен инвариант проекта» требует брифа.** Ссылка
идёт на пункт раздела `## Инварианты` дословно. Без брифа такое основание
недоступно — см. [project-brief.md](project-brief.md), деградированный режим.
- **`critical` по основанию «нарушен инвариант проекта» требует инвариантов.**
Ссылка идёт на пункт раздела инвариантов `CLAUDE.md` дословно. Без них основание
недоступно — см. [project-facts.md](project-facts.md), поразрядная деградация.
- **Расхождение — не дефект, пока не названо последствие.** Особенно для прохода
независимой реализации: «я бы сделал иначе» без последствия не выводится.
@@ -52,7 +52,7 @@
Шкала привязана к обратимости, а не к громкости: класс «необратимо и молча»
всегда весит больше класса «шумно и лечится повтором». Что здесь необратимо,
говорит раздел `## Прод и поток` брифа.
говорит `CLAUDE.md` — что в этом проекте необратимо.
## Блок границ покрытия
av-dev-pipeline/skills/review-pipeline/references/project-brief.md
-413
View File
@@ -1,413 +0,0 @@
# Бриф проекта — контракт
Конвейер общий, а находки — проектные. Проход, не знающий, что в этом проекте
нельзя нарушать, чем краснеет гейт и сколько данных реально проходит через узел,
выдаёт правдоподобные общие места: их дорого опровергать и нечем подтверждать.
Поэтому проектная специфика живёт **в одном файле проекта**, а не в charter'ах
агентов. Charter описывает **метод** прохода (что он делает и почему именно так),
бриф — **предмет** (что здесь дорого, чем это меряется, где лежит).
Шаблон для заполнения — [brief-template.md](brief-template.md).
## Где лежит и как находится
Порядок разрешения пути, одинаковый для скилла и для каждого агента:
1. путь, названный в задании конвейера (`бриф: <путь>`) — конвейер обязан его
передавать каждому проходу;
2. `docs/review-brief.md`;
3. `.claude/review-brief.md`;
4. брифа нет ни по одному пути — **он заводится**, скиллом
`av-dev-pipeline:project-brief`, и прогон продолжается по заведённому.
Разрешает путь конвейер, один раз, и дальше передаёт готовым. Агент, получивший
путь в задании, сам ничего не ищет.
## Деградированный режим — исход, а не умолчание
Он включается ровно тогда, когда бриф **завести не удалось**: репозиторий
доступен только на чтение, человек прямо запретил, инварианты вывести неоткуда.
Во всех остальных случаях брифа быть обязано.
Каждый проход в этом режиме:
- не присваивает `critical` по основанию «нарушен инвариант проекта» — инвариантов
он не знает;
- не оперирует числами объёма и потока — формулирует условиями;
- пишет в границы покрытия строку: «брифа проекта нет (<причина>): инварианты,
модель угроз и профиль нагрузки неизвестны; находки этих классов не искались».
Причина обязательна: без неё строка неотличима от «мы просто не стали», и
одинаковая строка в каждом отчёте перестаёт читаться на третьей задаче.
Триаж сводит эти строки в одну и выносит в финальный отчёт. Отсутствие брифа —
дыра покрытия, а не нейтральное умолчание.
## Форма
Markdown. Разделы — заголовки второго уровня с **точными именами** из списка
ниже: по ним агенты находят свой кусок. Порядок разделов свободен, лишние разделы
допустимы и игнорируются, отсутствующий раздел работает как деградированный режим
для тех проходов, которые его читают.
## Разделы
### `## Проект` — обязателен
Абзац: что система делает — и, что важнее, **чего она не делает**. Граница домена
нужна архитектурному проходу как критерий: «хранилище, а не аналитика», «единое
ядро, тонкие транспорты», «связующий сервис, а не медиатека». Без неё перенос
понятия через границу выглядит просто новым кодом.
Читают: `architecture`, `rubric`, `reimpl`, `specs`.
### `## Инварианты` — обязателен
Список того, что нарушать нельзя. Каждый пункт — три вещи:
- формулировка **как проверяемое свойство**, а не как лозунг: «точка сохраняется
дословно: незнакомое поле не отбрасывается», а не «бережно относимся к данным»;
- **последствие нарушения** и его обратимость;
- **severity по умолчанию** — если это не `critical`, скажи прямо.
Это единственный раздел, который **цитируется формулировкой**, а не пересказывается
ссылкой: по нему присваивается severity, и пересказ здесь стоит неверной оценки.
**Оговорка про severity, потому что она единственная не цитируется.** Проекты
почти никогда не пишут severity рядом с инвариантом — её приходится выводить, и
правило вывода одно: **по обратимости последствия**. Необратимо и молча —
`critical`; лечится повтором, видно сразу — ниже. Выведенная severity помечается
словом «выведена по обратимости», а не выдаётся за решение проекта: проход ставит
по ней `critical`, и он вправе знать, чьё это суждение. Лучший исход — дописать
severity туда, откуда цитируется формулировка, и тогда пометка снимается.
Читают: `specs` (режим 1 — отражены ли задетые инварианты в спеке), `code`,
`adversary`, `architecture`, `triage` (ранжирование и разметка «развилка»).
### `## Гейт` — обязателен
- **Команда** целиком, включая передачу базы диффа (`task gate BASE=<база>`), и
как база определяется по умолчанию.
- **Где логи** отдельных шагов.
- **Что означает каждый исход**: чем гейт краснеет, что предупреждает, что
пропускается по составу диффа.
- **Шаги, которые красят безусловно, и почему.** Это самая ценная часть раздела:
«данные под контролем версий», «структура конфига изменилась, а образец нет»,
«миграции не накатываются с нуля» — проход обязан знать, что здесь не бывает
«ну это мелочь».
- **Чего в гейте намеренно нет** и почему — прогон на живом корпусе, длинный
интеграционный тест. У проверки, которую гейт не гоняет, краснота никому не
видна; это уезжает в границы покрытия.
Читает: `gate`.
### `## Команды` — обязателен
Что проход имеет право выполнить и чем:
- **карта проекта для архитектуры** — команда, отдающая пакеты, граф зависимостей
и инвентарь концепций (`task review:context`);
- **запуск изменения вживую** — чем поднять и как проверить поведение (нужно
пайплайну задачи на шаге поведенческой верификации);
- **тесты, линт, дополнительные проверки** — и какие из них дорогие;
- **дорогие проверки вне гейта — с адресатом.** Мало сказать «`verify:archive`
идёт минуту»: назови, **кто и когда обязан** её гонять — какой класс изменения
её требует, кто её запускает (проход, пайплайн, человек) и что делать, если она
не прогонялась. Без адресата дорогая проверка не гоняется никогда, а её
краснота не видна никому. **Адресат в проекте не записан нигде — тогда бриф его
назначает**, и назначение помечается: «адресат назначен брифом, владельцем не
подтверждён». Это тот же класс, что выведенная severity у инварианта: слот
честнее заполнить назначением с пометкой, чем оставить пустым;
- **что запускать запрещено**: рабочая БД, боевой каталог данных, внешние
сервисы. Формулируй запретом с путями, а не «будь осторожен».
Читают: `architecture`, `gate`, `ops`, `triage`, пайплайн задачи.
### `## Прод и поток` — обязателен
Материал для эксплуатационного прохода, и он же — половина ранжирования триажа.
**Первой строкой — главный вопрос эксплуатации этого проекта.** Один заголовок
покрывает противоположные постановки: «поток идёт непрерывно и молча, отправитель
об отказе не узнает» и «мы опрашиваем чужие сервисы, и главный вопрос — что
делать, когда сосед отвечает медленно». От того, какая из них здесь главная,
зависит порядок находок в отчёте, а вывести её проход не может — он видит
одинаковый код.
Дальше:
- где это работает: машина, окружение, что рядом, кто перезапускает;
- **внешние зависимости поимённо** и чем каждая отказывает: не только «падает», но
и «отвечает медленно», «молчит», «отдаёт мусор». Эксплуатационный проход
спрашивает про каждую отдельно, и список зависимостей он взять больше неоткуда.
**Зависимостей почти нет — так и напиши**: «внешних зависимостей нет, смотри на
диск и на СУБД». Пустой пункт, не названный пустым, проход тратит впустую или
заполняет выдумкой;
- **кто заметит отказ и когда** — есть ли вообще наблюдатель;
- **характер потока**: непрерывный и молчаливый, по запросу, по расписанию; есть
ли обратная связь у отправителя;
- **представление данных и настройки хранилища.** Чем физически лежит запись
(сжатый BLOB, JSON-строка, колонки), что происходит при чтении и записи
(распаковка целиком, read-modify-write), и **настройки, у которых есть
числовое значение**: таймаут занятости СУБД, режим журналирования, лимит тела,
размер пула, ретеншен. Это не украшение раздела: ровно эти два факта
превращают **замер** в находку. Замеренный пик памяти — аномалия только если
известно, что запись лежит сжатой и распаковывается целиком; замеренная
длительность удержания блокировки — гарантированный отказ соседа только если
известно, чему равен таймаут занятости. Без этих фактов проход снимет верное
число и честно понизит находку до гипотезы, потому что сравнить его будет не с
чем. Цена пропущенного пункта здесь не «не найдём», а **«найдём и не
починим»**. Числа с провенансом — в следующем пункте, воспроизведённые случаи —
в разделе `## Прецеденты`;
- **измеренные числа с провенансом**: объёмы, размеры тел, темп, размеры таблиц.
Число без источника проход обязан превратить в условие — так и напиши, откуда
оно. **Замер и настройка — разные пункты, и путать их нельзя:** настройка
(`busy_timeout`, лимит тела, размер пула) живёт пунктом выше и говорит, чему
равен порог; замер говорит, что происходит на самом деле. Проекту без
наблюдаемой нагрузки нечего писать во втором пункте — **так и напиши**:
«измеренных чисел нагрузки нет, всё, что ниже, — настройки». Тогда проход
формулирует условиями осознанно, а не потому, что не нашёл;
- **что обратимо, а что нет.** Падение, которое лечится повтором, и тихая потеря,
которую нечем восстановить, — разные классы, и порядок находок в отчёте зависит
от того, какой из них здесь главный.
Читают: `ops`, `adversary`, `triage`, `reimpl`.
### `## Модель угроз` — обязателен
**Первой строкой — периметр.** «Сервис открыт наружу; злоумышленник в локальной
сети неинтересен» и «контур доверенный, публичного интернета здесь нет, не
выдумывай его» — это один и тот же заголовок при противоположной постановке, и
враждебный проход не может выбрать между ними сам. Периметр, объявленный первой
строкой, задаёт смысл всему остальному разделу.
**Периметров может быть два — целевой и сегодняшний**, если контур ещё не
развёрнут: «целевой — открыт наружу за прокси с TLS; сегодняшний — только
локальная машина, токены пусты осознанно». Тогда назови оба и скажи прямо,
**против какого строятся находки**. Иначе враждебный проход либо завалит отчёт
находками «нет TLS» по сегодняшнему состоянию, либо не станет искать дефекты,
спящие до выкладки, — оба исхода стоят прохода целиком.
Дальше:
- **что недоверенное** и каким каналом приходит: тело запроса, файл, аргумент
команды, ответ внешней системы, содержимое архива;
- **из чего строятся пути и ключи** — раскладка файлов на диске, состав
координатного ключа записи, имя каталога. Враждебный проход выводит запись за
пределы песочницы именно отсюда, и без этого пункта он ищет вслепую;
- **что разграничивает доступ** — токены, контуры, права файлов;
- **что чувствительнее чего**: если данные дороже секретов, скажи это прямо;
- **что вне модели** — перечислить явно. Пустой пункт «вне модели» означает, что
враждебный проход выдумает угрозу сам, и находка никогда не будет исправлена.
Читает: `adversary`.
### `## Карта` — обязателен
Где что лежит, путями:
- **основная ветка** — её имя. Отсюда берутся ветки задач, в неё вливается батч,
от неё считается база диффа по умолчанию (`git merge-base HEAD <основная>`).
Батч подставляет это имя в каждую команду git; взять его больше неоткуда, а
угадывание между `master` и `main` ломает интеграцию целиком;
- актуальные спеки и дельта-спеки предлагаемого изменения;
- **нарезка capability и миграционное состояние спек** — по какому признаку
проект режет capability (по домену, по транспорту, по подсистеме), какие из них
уже перенесены в актуальные спеки, а какие ещё живут только в документации или
в коде. Проход по спекам иначе примет непереехавшую тему за пробел в спеке, а
архитектурный — за отсутствие понятия;
- конвенции прозой — **файл или каталог файлов**, путями; и **какая их часть уже
механизирована** правилом. Механизация бывает **в нескольких местах сразу**:
конфиг линтера, собственный анализатор и — чаще всего незамеченное —
**тест-сканер исходников** (правило про направление зависимостей, форму
миграций, логику в транспорте), который внешне неотличим от обычного теста.
Перечисли все места: непойманное место механизации означает, что проход по
конвенциям будет добросовестно проверять уже проверенное;
- **наблюдения на живых данных** — где записано, как внешний мир ведёт себя на
самом деле (что реально шлёт источник, чем документация формата расходится с
практикой, какие числа сняты с живого потока). Их спрашивают `specs`, `reimpl`
и `ops`, и все трое — «из раздела `## Карта`». Отдельного файла нет — **так и
напиши**, и перечисли суррогаты: спеки, где наблюдения рассыпаны, комментарии в
адаптерах, `testdata`. Отдельный файл — лучшая форма, потому что при нескольких
внешних источниках наблюдения иначе не сойдутся в одном месте; но честный
перечень суррогатов лучше молчания, от которого три прохода ищут
несуществующий путь;
- архитектура и решения; журнал проскочивших дефектов;
- **единые точки проекта** — где генерируются идентификаторы и время, где
единственный парсер входного формата, где маппинг доменной ошибки в код ответа,
где общий путь приёма. Это материал для вопроса «не появился ли второй способ»;
если команда карты проекта их выгружает, здесь хватит ссылки на неё;
- **нумерованные артефакты** — путь миграций и правило нумерации: батч раздаёт
номера заранее, чтобы параллельные задачи не столкнулись файлами;
- где ведутся задачи (пайплайн только читает и сообщает исход);
- `testdata` и что в них лежит; куда можно писать временное;
- **каталоги, которые не трогают вовсе**.
Читают: все проходы.
### `## Типовые узлы` — необязателен, но без него рубрика беднеет
Роды узлов, из которых состоит проект (парсер входного формата, HTTP-обработчик,
репозиторий, воркер, клиент внешнего API, CLI-команда, файловое хранилище), и по
3–5 **специфичных для рода** проверяемых свойств к каждому.
**Рода, а не инвентарь того, что сейчас лежит в пакетах.** Список пишется по
природе проекта: род, который проект уже задумал, но ещё не написал, включать
полезно (рубрика на него понадобится ровно на той задаче, где его заводят); а
род, случайно оказавшийся в коде в одном экземпляре, — нет. Иначе раздел
протухает на каждой задаче и требует пересмотра, которого никто не делает.
Читает: `rubric`. Без раздела рубрика выродится в общие слова и повторит
конвенции — то есть станет applicative-проходом, ради отсутствия которого она и
существует.
### `## Прецеденты` — обязателен, хотя бы строкой «пусто»
**Воспроизведённые случаи этого проекта, с оракулом.** Не «здесь бывают гонки», а
«такой дефект здесь уже был, вот чем он воспроизведён»: что оказалось не так,
каким экспериментом или тестом это показано, какими числами, где это записано.
Каждый пункт — четыре вещи:
- **класс дефекта** — так, чтобы проход узнал его в другом месте;
- **как проявился** — симптом, который увидел человек;
- **чем воспроизведён** — команда, тест, стенд, замер. Без этого пункт
превращается в байку. **Регрессионный тест, написанный вместе с починкой,
годится** наравне с независимым экспериментом: он исполняемый и падает на
старом коде, а это всё, что требуется от оракула. Слабее он ровно в одном —
сформулирован уже зная ответ; это отмечается словом, а не служит поводом
выбросить пункт;
- **чем закончилось** — починка, правило линтера, пункт брифа, «ничего».
Зачем раздел существует. Прецедент — самая сильная опора, какая у прохода вообще
бывает: он проектный, воспроизводимый и уже однажды оказался правдой. Пока слота
не было, прецеденты вмерзали в charter'ы проходов — то есть каждый проект читал
про чужую контрольную точку в чужой СУБД и искал её у себя. Charter описывает
**форму класса**, бриф — **случай**.
Источники: журнал проскочивших дефектов, архивные отчёты триажа, `git log` по
починкам. Прецедентов нет — так и напиши: «прецедентов не накоплено», и это
честнее пустого раздела.
Читают: все проходы — свой класс; `triage` — как готовый оракул.
### `## Типовые ложноположительные` — необязателен, но без него отсев слепой
Находки, которые в **этом** проекте выглядят убедительно и всегда неверны. Это
единственный проектный вход в шаг триажа «отсев вкусовщины»: общие критерии
(«не меняет поведения, не влияет на стоимость следующего изменения, не нарушает
записанного») ловят вкусовщину, но не ловят находку, которая нарушает общее
правило **осознанно**.
Каждый пункт — формулировка находки, какой её выдаёт проход, плюс одна строка
«почему здесь это не дефект». Типичные обитатели: «дословное хранение надо
нормализовать» там, где дословность — инвариант; «повтор надо сделать
идемпотентным» там, где повтор невозможен по построению; «это надо вынести в
конфиг» там, где значение задано внешним протоколом.
Читает: `triage`.
### `## Вопросы к проходам` — необязателен
Проектные вопросы, адресованные **поимённо** конкретному проходу. Главный их
источник — журнал проскочивших дефектов: запись «проход не мог этого знать» чаще
всего лечится фактом в другом разделе, но иногда лечится не фактом, а
**вопросом**: «`ops`, спроси про поведение при откате бинаря поверх новой схемы»,
«`adversary`, проверь имена внутри архива». Такие вопросы живут здесь, а не в
charter'е: charter общий для всех проектов, а вопрос выведен из промаха в этом.
**Журнал — не единственный источник, а лучший.** У молодого проекта журнал пуст,
и слот тогда заполняется из того, что есть: незакрытые находки аудита, известное
расхождение кода с документацией, место, где решение принято «пока так». Правило
одно и не смягчается — **у каждого вопроса указан провенанс**, и по нему видно,
насколько он выстрадан: «журнал, запись такая-то» весит больше, чем «открытая
находка аудита».
Форма: `<имя прохода>: <вопрос> (<провенанс>)`. Проход, увидев свой блок, задаёт
эти вопросы **дополнительно** к обязательным — и отвечает на них в выводе явно.
Читают: проходы, названные поимённо.
### `## Триггеры` — необязателен
Проектная конкретизация правила выбора профиля: какие пути и контракты означают
`deep`; что считается «поведением, видимым снаружи»; при каком изменении
запускается `reimpl`. Умолчания записаны в самом скилле и работают без этого
раздела — но общее правило говорит «изменение публичного контракта», а какой
контракт публичный, знает только проект.
Читают: скилл конвейера, пайплайн задачи.
### `## Недоступно проверке` — обязателен, и делится на два подраздела
Раздел целиком уезжает в границы покрытия финального отчёта — он существует ровно
затем, чтобы «критичных проблем не обнаружено» никогда не читалось как «проверено
всё». Но внутри лежат **два разных класса**, и смешивать их нельзя: при следующем
промахе один пересматривается, другой нет.
#### `### Не проверит ни один проход`
Принципиально недоступное: поведение внешних систем и их будущих версий, реальный
профиль нагрузки, соответствие сохранённого действительности, завязка внешних
потребителей на текущую форму, суждение «а нужна ли эта функциональность».
Этот список не пересматривается по факту промаха: дефект отсюда — не ошибка
конвейера, а его честная граница. Он меняется только когда меняется сам проект
(появился стенд, появился второй потребитель, появилась телеметрия).
#### `### Перестали проверять сознательно`
Решения о сужении: перестали звать проход, понизили профиль правилом, сузили
класс проверяемого, сняли правило линтера как шумное. Каждый пункт — **что
перестали, когда и почему**, со ссылкой на запись журнала ревью.
Этот список **пересматривается первым**, как только что-то проскочило: первый
вопрос по любому пропущенному дефекту — «не тот ли это класс, который мы перестали
проверять». Пункт, из-за которого дефект проскочил, либо возвращается, либо
получает строку «оставляем, цена поимки выше цены дефекта» с датой.
Оба подраздела обязательны; пустой называется пустым.
Читает: `triage`; каждый проход — свою часть.
## Правила ведения
- **Бриф не пересказывает документацию проекта.** Факт, записанный в `CLAUDE.md`
или в архитектуре, попадает сюда ссылкой и одной строкой сути. Два дома для
одного факта разъезжаются, и разошедшийся бриф хуже отсутствующего: он выглядит
актуальным. Исключение одно — раздел инвариантов, он цитируется.
- **Числа — с провенансом, и провенанс проверяется переходом по ссылке.** «Тела
доходили до 42 МБ (замер, ссылка)». Число без источника проход не имеет права
использовать как утверждение. Отдельный и более коварный случай — **число, чей
источник по ссылке не подтверждается**: в документе по ссылке другое число, или
его там нет вовсе. Такое число не выбрасывается и не переписывается по догадке:
оно остаётся с пометкой «расходится с источником: там <что нашли>», а проход
обязан читать его как условие, а не как замер. Молча подставить «правильное»
число хуже всего — расхождение перестанет быть видно, а причина его останется.
- **Пустой пункт называется пустым.** «Внешних зависимостей нет — смотри на диск
и на СУБД», «прецедентов не накоплено», «наблюдений на живых данных не ведём»,
«измеренных чисел нагрузки нет», «сознательно ничего не отключали». Отсутствие
строки читается проходом как «здесь не написали», и он тратит обязательный
вопрос впустую либо заполняет пробел выдумкой. Прямое «пусто» стоит одной
строки и экономит проход целиком.
- **Назначенное помечается назначенным.** Бриф отражает решения проекта, но
местами оказывается **первым** местом, где решение вообще записано: severity у
инварианта, адресат дорогой проверки, периметр, восстановленный из конфига.
Так можно — молчать хуже, — но пометка обязательна («выведена по обратимости»,
«назначен брифом, владельцем не подтверждён»). Проход имеет право знать, чьё
это суждение, а владелец — увидеть, что за него что-то решили.
- **Что вне модели — называется явно.** Это относится и к угрозам, и к нагрузке,
и к классам находок, которые проект сознательно перестал проверять (последние —
в свой подраздел `## Недоступно проверке`, а не вперемешку с принципиальным).
- **Бриф подчиняется промоуту.** Свойство, ставшее правилом линтера, из брифа
вычёркивается — как и из конвенций, и из charter'ов (см.
[promote.md](promote.md), шаг 3).
- **Когда обновлять:** сменился гейт; появился новый контур, зависимость или
источник входа; журнал ревью получил запись вида «проход не мог этого знать»;
воспроизвели дефект — он идёт в `## Прецеденты`. Планового пересмотра нет.
- **Заводится и обновляется шагом, а не руками** — скиллом
`av-dev-pipeline:project-brief`. Он же вызывается автоматически, когда конвейер
или пайплайн задачи не нашли брифа ни по одному пути.
- **Бриф ведёт проект**, а не плагин. Файл живёт в репозитории проекта; плагин
его читает и заводит по шаблону, но не хранит у себя и не подменяет.
av-dev-pipeline/skills/review-pipeline/references/project-facts.md
+85
View File
@@ -0,0 +1,85 @@
# Откуда проход берёт проектную конкретику
Конвейер общий, находки — проектные. Проход, не знающий, что в этом проекте
нельзя нарушать, чем краснеет гейт и сколько данных реально идёт через узел,
выдаёт правдоподобные общие места: их дорого опровергать и нечем подтверждать.
Отдельного файла-брифа **нет**. Проектная конкретика живёт в документах канона
`av-dev-pm`, и проход читает их напрямую: пути жёсткие, посредник не нужен, а
второй дом для тех же фактов разошёлся бы и выглядел актуальным.
Определение канона — в плагине `av-dev-pm`,
`skills/canon/references/canon.md`. Здесь только карта «что нужно проходу →
где это лежит».
## Карта
| Что нужно проходу | Где лежит |
| --- | --- |
| что система делает и **чего не делает**, граница домена | `docs/passport.md` |
| инварианты **с severity рядом с формулировкой** | `CLAUDE.md`, раздел инвариантов |
| команда гейта, чем краснеет безусловно, чего в нём нет, кто гоняет дорогое | `CLAUDE.md`, семантика гейта |
| что запускать запрещено, с путями; `testdata`; куда писать временное; имя основной ветки | `CLAUDE.md` |
| компоненты и capability, окружение, внешние зависимости поимённо, наблюдатель, характер потока, единые точки проекта | `docs/architecture.md` |
| чем физически лежит запись, что при чтении и записи, настройки с числовым значением | `docs/database.md` |
| периметр, недоверенный вход, из чего строятся пути и ключи, что вне модели | `docs/security.md` |
| измеренные числа **с провенансом**, поведение внешних систем на самом деле | `docs/research/` |
| конвенции прозой и **что уже механизировано** правилом | `docs/conventions/` |
| почему решено так, отвергнутые варианты | `docs/adr/` |
| типовые узлы, типовые ложноположительные, вопросы к проходам, недоступно проверке | `docs/review.md`, раздел настройки |
| прецеденты: воспроизведённые дефекты с оракулом | `docs/review.md`, журнал |
| нормативное поведение и дельты изменения | `openspec/specs/`, `openspec/changes/<id>/specs/` |
## Сшивать обязаны проходы
Раньше эти факты лежали рядом в одном файле, и соседство работало само. Теперь
они разложены по домам, и **проход обязан собрать их сам** — иначе снимет верное
число и честно понизит находку до гипотезы, потому что сравнить будет не с чем.
Два обязательных стыка:
- **замер + настройка.** «Пик 768 МиБ» — аномалия только рядом со строкой
«запись лежит сжатой и распаковывается целиком»; «блокировка удерживалась
5.019 с» — гарантированный отказ соседа только рядом с известным таймаутом
занятости. Числа в `docs/research/`, настройки в `docs/database.md`, и оба
читает `ops`, `adversary`, `reimpl`.
- **инвариант + обратимость.** severity берётся из `CLAUDE.md`; если её там
нет — она **выводится по обратимости последствия** и помечается «выведена по
обратимости», а не выдаётся за решение проекта.
## Деградация — поразрядная
Документа нет — деградирует то, что из него читалось, и **только оно**. Каждый
проход пишет свою строку в границы покрытия; триаж сводит их в одну.
| Нет документа | Что деградирует |
| --- | --- |
| `CLAUDE.md` без инвариантов | `critical` по основанию «нарушен инвариант проекта» не присваивается никем |
| `docs/security.md` | `adversary` не знает периметра — формулирует условиями, `critical` не ставит |
| `docs/research/` | числа неизвестны `ops`, `adversary`, `reimpl` — все трое формулируют условиями |
| `docs/database.md` | замер не с чем сравнить: находка не поднимается выше гипотезы |
| `docs/passport.md` | `architecture` теряет границу домена и вырождается в общее мнение |
| `docs/review.md` | `triage` отсеивает вслепую: типовых ложноположительных нет |
| `docs/architecture.md` | «не появился ли второй способ» не проверяется — единых точек не знает никто |
Строка в границах покрытия обязана называть **причину**: «`docs/security.md` в
проекте нет» читается иначе, чем «есть, но периметр не назван». Без причины
строка неотличима от «мы просто не стали» и перестаёт читаться на третьей задаче.
**Документов канона нет вовсе** — проект не приведён к канону. Это не повод
работать вслепую: скажи об этом строкой и предложи `av-dev-pm:canon`. Одна
операция на проект против деградации на каждой задаче.
## Правило чтения
- **Читай в источнике, не по памяти.** Документы правятся по ходу работы, в том
числе этой же задачей.
- **Число без провенанса — условие, а не утверждение.** Число, чей источник по
ссылке не подтвердился, читается как условие и **называется расходящимся**, а
не подменяется догадкой.
- **Пустое, названное пустым, — это факт.** «Внешних зависимостей нет — смотри
на диск и на СУБД» экономит обязательный вопрос. Отсутствие строки — не факт,
а пробел, и его надо назвать в границах покрытия.
- **Свойство, ставшее правилом линтера, из конвенций удалено** и лежит в
перечне механизированного в `docs/conventions/README.md`. Проверять его
проходом — тратить внимание на уже проверенное.
av-dev-pipeline/skills/review-pipeline/references/promote.md
+8 -6
View File
@@ -24,7 +24,7 @@
проход, чьи находки не доезжают никогда, — кандидат на `drop` (см.
[calibration.md](calibration.md)).
- Место записи — конвенции проекта, файл или нужный файл каталога (путь — в
разделе `## Карта` брифа). Если
каталог `docs/conventions/`). Если
тема относится к поведению системы, а не к тому, как мы пишем код, — это не
конвенция, а требование: заводится дельта-спека обычным путём.
@@ -51,7 +51,7 @@
хук блокирует любой коммит, и правило снимут первым же раздражённым движением.
Приводить код в соответствие — часть шага 2, отдельным коммитом.
## Шаг 3. Удаление из конвенций, из брифа и из промптов
## Шаг 3. Удаление из конвенций и из промптов
**Шаг, который пропускают чаще всего, и единственный, ради которого затевались
первые два.**
@@ -61,13 +61,15 @@
- из файла конвенций убирается формулировка правила; остаётся, если нужно, одна
строка «проверяется линтером `<имя>`» — но только там, где без неё раздел
теряет связность;
- **из брифа проекта** убирается соответствующий пункт, а в разделе `## Карта`
правило переезжает в перечень «механизировано и потому проходом по конвенциям
не проверяется»;
- правило переезжает в **перечень механизированного в
`docs/conventions/README.md`** — со ссылкой на место механизации: конфиг
линтера, собственный анализатор, тест-сканер исходников. Непойманное место
означает, что проход будет добросовестно проверять уже проверенное;
- из контекста инструмента спек убирается дубль, если он там был.
Charter'ы проходов при этом **не правятся**: они общие и живут в плагине, а
предмет проверки приходит из брифа. Именно поэтому шаг 3 стал дешевле, чем был:
предмет проверки приходит из документов проекта. Именно поэтому шаг 3 дешевле,
чем был:
вычеркнуть строку в одном файле проекта, а не в девяти промптах.
Практический критерий: **в прозаических конвенциях остаётся только то, что
av-dev-pipeline/skills/review-pipeline/references/review-journal.md
+54 -29
View File
@@ -1,42 +1,64 @@
# Журнал проскочивших дефектов
# Журнал дефектов
Артефакт проекта, а не плагина: файл живёт в репозитории (путь — в разделе
`## Карта` брифа, по умолчанию `docs/review-journal.md`). Здесь описано, зачем он
и какой формы, потому что без него конвейер не учится: находки закрываются,
причины непоймания теряются, и один и тот же класс проскакивает второй раз.
Артефакт проекта, а не плагина: файл живёт в репозитории — **`docs/review.md`**,
слот канона `av-dev-pm`. Здесь описано, зачем он и какой формы, потому что без
него конвейер не учится: находки закрываются, причины непоймания теряются, и один
и тот же класс проскакивает второй раз.
Тот же файл держит **настройку конвейера под проект** — типовые узлы, типовые
ложноположительные, вопросы к проходам, недоступно проверке. Это не соседство по
случаю: все четыре раздела — производные калибровки, а журнал им источник.
## Что туда попадает
Дефект, который **прошёл ревью и всплыл позже**. Записывается **сразу**, а не
ретроспективно: со временем теряется не сам факт, а причина непоймания —
единственное, ради чего журнал существует.
**Воспроизведённый дефект — с пометкой `проскочил` или `пойман ревью`.**
Записывается **сразу**, а не ретроспективно: со временем теряется не сам факт, а
причина непоймания — единственное, ради чего журнал существует.
Реализованные задачи, находки ревью и принятые решения сюда не пишутся: у них
есть коммит, спека и задача. Здесь только промахи конвейера.
Пометка делит журнал на две выборки с разным назначением:
- **проскочил** — эвал-сет для калибровки конвейера. Реальный промах сильнее
синтетической пробы: синтетические смещены в сторону тех, которые уже умеешь
придумывать;
- **пойман ревью** — прецеденты с оракулом. Самая сильная опора, какая у прохода
бывает: проектная, воспроизводимая и однажды уже оказавшаяся правдой. Без
журнала они остаются только в отчётах триажа в архиве change, где их никто не
ищет.
Реализованные задачи и принятые решения сюда не пишутся: у них есть коммит, спека
и `docs/adr/`.
Отдельно сюда попадают **решения о составе прогонов**: перестали звать проход,
понизили профиль правилом, сузили класс проверяемого. Не потому, что это промах,
а потому, что здесь лежит цена: если что-то теперь проскочит, первый вопрос —
«не тот ли это класс, который мы перестали проверять».
Каждое такое решение обязано получить **строку в брифе** — в подразделе
`### Перестали проверять сознательно` раздела `## Недоступно проверке`. Журнал
хранит «почему тогда так решили», бриф — то, во что смотрит каждый прогон.
Решение, оставшееся только в журнале, в границы покрытия не доедет.
Каждое такое решение обязано получить строку в подразделе **«Перестали проверять
сознательно»** раздела «Недоступно проверке» того же файла. Журнал хранит «почему
тогда так решили», раздел настройки — то, во что смотрит каждый прогон. Решение,
оставшееся только в журнале, в границы покрытия не доедет.
## Форма записи
```
## ГГГГ-ММ-ДД — <краткое последствие>
## ГГГГ-ММ-ДД — <краткое последствие> [проскочил|пойман]
- **Где:** путь:строка либо «конвейер, а не код»
- **Симптом:** как обнаружилось, кем и когда
- **Причина:** что на самом деле было не так
- **Почему не поймали:** какой проход обязан был найти и что ему помешало
- **Что меняем:** правило прохода, шаг гейта, конвенция, пункт брифа — либо
«ничего, цена поимки выше цены дефекта»
- **Чем воспроизведён:** тест, команда, замер — с числами
- **Почему не поймали:** только для проскочивших — какой проход обязан был найти
и что ему помешало
- **Что меняем:** правило прохода, шаг гейта, конвенция, факт в документе
проекта — либо «ничего, цена поимки выше цены дефекта»
```
Пункт «чем воспроизведён» отличает запись от байки: без него на неё нельзя
сослаться как на оракул. Регрессионный тест, написанный вместе с починкой,
годится наравне с независимым экспериментом — он исполняемый и падает на старом
коде. Слабее он ровно в одном: сформулирован уже зная ответ, и это отмечается
словом.
Последний пункт важнее остальных. Вывод «ничего не меняем» — законный исход: не
всякий дефект стоит того, чтобы усложнять ради него ревью каждой задачи.
@@ -44,24 +66,27 @@
Три адреса, и выбор между ними — половина ценности журнала:
- **в бриф проекта** — если проход не мог знать факта: объём, характер потока,
что здесь необратимо, какой шаг гейта красит безусловно. Самый частый адрес и
самый дешёвый. Сюда же — **воспроизведённый случай** (раздел `## Прецеденты`:
класс, симптом, чем воспроизведён, чем закончилось) и **вопрос конкретному
проходу**, если промах лечится не фактом, а заданным вопросом (раздел
`## Вопросы к проходам`). Прежде чем править charter, проверь, не хватит ли
этих двух разделов: charter общий для всех проектов, бриф — про этот.
- **в документ проекта** — если проход не мог знать факта. Адрес зависит от рода
факта, и карта их всех — [project-facts.md](project-facts.md): объём и
измеренное число → `docs/research/`; настройка хранилища → `docs/database.md`;
что необратимо и какой шаг гейта красит безусловно → `CLAUDE.md`; периметр и
недоверенный вход → `docs/security.md`. **Вопрос конкретному проходу**, если
промах лечится не фактом, а заданным вопросом, → раздел «Вопросы к проходам»
того же `docs/review.md`. Самый частый адрес и самый дешёвый. Прежде чем
править charter, проверь, не хватит ли факта или вопроса: charter общий для
всех проектов, документ — про этот.
- **в конвенции или в правило линтера** — если свойство выражается
детерминированно (процедура — [promote.md](promote.md)).
- **в charter прохода** — если сломан **метод**, а не знание. Правка charter'а
меняет поведение во всех проектах, поэтому она требует калибровки
([calibration.md](calibration.md)) и обоснования, почему это не лечится
брифом.
([calibration.md](calibration.md)) и обоснования, почему это не лечится фактом
в документе проекта.
## Что журнал даёт конвейеру
- **пробы для калибровки** — реальный проскочивший дефект сильнее синтетического:
синтетические смещены в сторону тех, которые уже умеешь придумывать;
- **пробы для калибровки** — выборка по пометке `проскочил`;
- **готовые оракулы** — выборка по пометке `пойман ревью`: находка того же
класса подтверждается ссылкой на запись, а не рассуждением;
- **основание для правил конвейера** — требование называть запущенные проходы
поимённо, отказ от чисел, производных от размера корпуса, и правило
последовательного прогона выведены из конкретных записей, а не из общих