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

# Бриф проекта — контракт

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

Поэтому проектная специфика живёт **в одном файле проекта**, а не в 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`. Он же вызывается автоматически, когда конвейер
  или пайплайн задачи не нашли брифа ни по одному пути.
- **Бриф ведёт проект**, а не плагин. Файл живёт в репозитории проекта; плагин
  его читает и заводит по шаблону, но не хранит у себя и не подменяет.