dev-skills/av-dev-pipeline/skills/review-pipeline/references/brief-template.md

# Шаблон брифа проекта

Образец заполнения. Контракт разделов — в
[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: ложных срабатываний
  больше трети (журнал, там же). Вернуть, если проскочит дефект «функция делает
  три вещи».