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. брифа нет — **деградированный режим** (см. ниже).

Разрешает путь конвейер, один раз, и дальше передаёт готовым. Агент, получивший
путь в задании, сам ничего не ищет.

## Деградированный режим

Брифа нет — проходы работают, но их recall падает предсказуемым образом, и это
**обязано быть названо**, а не сглажено. Каждый проход без брифа:

- не присваивает `critical` по основанию «нарушен инвариант проекта» — инвариантов
  он не знает;
- не оперирует числами объёма и потока — формулирует условиями;
- пишет в границы покрытия строку: «брифа проекта нет: инварианты, модель угроз и
  профиль нагрузки неизвестны; находки этих классов не искались».

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

## Форма

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

## Разделы

### `## Проект` — обязателен

Абзац: что система делает — и, что важнее, **чего она не делает**. Граница домена
нужна архитектурному проходу как критерий: «хранилище, а не аналитика», «единое
ядро, тонкие транспорты», «связующий сервис, а не медиатека». Без неё перенос
понятия через границу выглядит просто новым кодом.

Читают: `architecture`, `rubric`, `reimpl`, `specs`.

### `## Инварианты` — обязателен

Список того, что нарушать нельзя. Каждый пункт — три вещи:

- формулировка **как проверяемое свойство**, а не как лозунг: «точка сохраняется
  дословно: незнакомое поле не отбрасывается», а не «бережно относимся к данным»;
- **последствие нарушения** и его обратимость;
- **severity по умолчанию** — если это не `critical`, скажи прямо.

Это единственный раздел, который **цитируется формулировкой**, а не пересказывается
ссылкой: по нему присваивается severity, и пересказ здесь стоит неверной оценки.

Читают: `specs` (режим 1 — отражены ли задетые инварианты в спеке), `code`,
`adversary`, `architecture`, `triage` (ранжирование и разметка «развилка»).

### `## Гейт` — обязателен

- **Команда** целиком, включая передачу базы диффа (`task gate BASE=<база>`), и
  как база определяется по умолчанию.
- **Где логи** отдельных шагов.
- **Что означает каждый исход**: чем гейт краснеет, что предупреждает, что
  пропускается по составу диффа.
- **Шаги, которые красят безусловно, и почему.** Это самая ценная часть раздела:
  «данные под контролем версий», «структура конфига изменилась, а образец нет»,
  «миграции не накатываются с нуля» — проход обязан знать, что здесь не бывает
  «ну это мелочь».
- **Чего в гейте намеренно нет** и почему — прогон на живом корпусе, длинный
  интеграционный тест. У проверки, которую гейт не гоняет, краснота никому не
  видна; это уезжает в границы покрытия.

Читает: `gate`.

### `## Команды` — обязателен

Что проход имеет право выполнить и чем:

- **карта проекта для архитектуры** — команда, отдающая пакеты, граф зависимостей
  и инвентарь концепций (`task review:context`);
- **запуск изменения вживую** — чем поднять и как проверить поведение (нужно
  пайплайну задачи на шаге поведенческой верификации);
- **тесты, линт, дополнительные проверки** — и какие из них дорогие;
- **что запускать запрещено**: рабочая БД, боевой каталог данных, внешние
  сервисы. Формулируй запретом с путями, а не «будь осторожен».

Читают: `architecture`, `gate`, `ops`, `triage`, пайплайн задачи.

### `## Прод и поток` — обязателен

Материал для эксплуатационного прохода, и он же — половина ранжирования триажа:

- где это работает: машина, окружение, что рядом, кто перезапускает;
- **внешние зависимости поимённо** и чем каждая отказывает: не только «падает», но
  и «отвечает медленно», «молчит», «отдаёт мусор». Эксплуатационный проход
  спрашивает про каждую отдельно, и список зависимостей он взять больше неоткуда;
- **кто заметит отказ и когда** — есть ли вообще наблюдатель;
- **характер потока**: непрерывный и молчаливый, по запросу, по расписанию; есть
  ли обратная связь у отправителя;
- **измеренные числа с провенансом**: объёмы, размеры тел, темп, размеры таблиц.
  Число без источника проход обязан превратить в условие — так и напиши, откуда
  оно;
- **что обратимо, а что нет.** Падение, которое лечится повтором, и тихая потеря,
  которую нечем восстановить, — разные классы, и порядок находок в отчёте зависит
  от того, какой из них здесь главный.

Читают: `ops`, `adversary`, `triage`, `reimpl`.

### `## Модель угроз` — обязателен

- **что недоверенное** и каким каналом приходит: тело запроса, файл, аргумент
  команды, ответ внешней системы, содержимое архива;
- **из чего строятся пути и ключи** — раскладка файлов на диске, состав
  координатного ключа записи, имя каталога. Враждебный проход выводит запись за
  пределы песочницы именно отсюда, и без этого пункта он ищет вслепую;
- **что разграничивает доступ** — токены, контуры, права файлов;
- **что чувствительнее чего**: если данные дороже секретов, скажи это прямо;
- **что вне модели** — перечислить явно. Пустой пункт «вне модели» означает, что
  враждебный проход выдумает угрозу сам, и находка никогда не будет исправлена.

Читает: `adversary`.

### `## Карта` — обязателен

Где что лежит, путями:

- актуальные спеки и дельта-спеки предлагаемого изменения;
- конвенции прозой — и **какая их часть уже механизирована** правилом (её проход
  по конвенциям не проверяет);
- архитектура и решения; журнал проскочивших дефектов;
- **единые точки проекта** — где генерируются идентификаторы и время, где
  единственный парсер входного формата, где маппинг доменной ошибки в код ответа,
  где общий путь приёма. Это материал для вопроса «не появился ли второй способ»;
  если команда карты проекта их выгружает, здесь хватит ссылки на неё;
- **нумерованные артефакты** — путь миграций и правило нумерации: батч раздаёт
  номера заранее, чтобы параллельные задачи не столкнулись файлами;
- где ведутся задачи (пайплайн только читает и сообщает исход);
- `testdata` и что в них лежит; куда можно писать временное;
- **каталоги, которые не трогают вовсе**.

Читают: все проходы.

### `## Типовые узлы` — необязателен, но без него рубрика беднеет

Роды узлов, из которых состоит проект (парсер входного формата, HTTP-обработчик,
репозиторий, воркер, клиент внешнего API, CLI-команда, файловое хранилище), и по
3–5 **специфичных для рода** проверяемых свойств к каждому.

Читает: `rubric`. Без раздела рубрика выродится в общие слова и повторит
конвенции — то есть станет applicative-проходом, ради отсутствия которого она и
существует.

### `## Триггеры` — необязателен

Проектная конкретизация правила выбора профиля: какие пути и контракты означают
`deep`; что считается «поведением, видимым снаружи»; при каком изменении
запускается `reimpl`. Умолчания записаны в самом скилле и работают без этого
раздела — но общее правило говорит «изменение публичного контракта», а какой
контракт публичный, знает только проект.

Читают: скилл конвейера, пайплайн задачи.

### `## Недоступно проверке` — обязателен

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

Этот раздел целиком уезжает в границы покрытия финального отчёта. Он существует
ровно затем, чтобы «критичных проблем не обнаружено» никогда не читалось как
«проверено всё».

Читает: `triage`; каждый проход — свою часть.

## Правила ведения

- **Бриф не пересказывает документацию проекта.** Факт, записанный в `CLAUDE.md`
  или в архитектуре, попадает сюда ссылкой и одной строкой сути. Два дома для
  одного факта разъезжаются, и разошедшийся бриф хуже отсутствующего: он выглядит
  актуальным. Исключение одно — раздел инвариантов, он цитируется.
- **Числа — с провенансом.** «Тела доходили до 42 МБ (замер, ссылка)». Число без
  источника проход не имеет права использовать как утверждение.
- **Что вне модели — называется явно.** Это относится и к угрозам, и к нагрузке,
  и к классам находок, которые проект сознательно перестал проверять.
- **Бриф подчиняется промоуту.** Свойство, ставшее правилом линтера, из брифа
  вычёркивается — как и из конвенций, и из charter'ов (см.
  [promote.md](promote.md), шаг 3).
- **Когда обновлять:** сменился гейт; появился новый контур, зависимость или
  источник входа; журнал ревью получил запись вида «проход не мог этого знать».
  Планового пересмотра нет.
- **Бриф ведёт проект**, а не плагин. Плагин его только читает и никогда не
  правит.