dev-skills/av-dev-pipeline/skills/project-brief/SKILL.md

name, description

name	description
project-brief	Заводит или обновляет бриф ревью проекта (docs/review-brief.md) — файл, откуда конвейер ревью берёт инварианты, команду гейта, модель угроз, объёмы, прецеденты и карту проекта. Вызывать, когда брифа нет (это обнаруживают review-pipeline, task-pipeline и task-batch на старте), когда сменился гейт или появилась новая зависимость, и по прямой просьбе завести или обновить бриф.

Заведение брифа проекта

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

Поэтому заведение брифа — шаг, а не документ. Этот скилл его выполняет.

• Контракт разделов — контракт брифа.
• Форма и образцы заполнения — шаблон.

Когда вызывается

• Автоматически, без спроса: av-dev-pipeline:review-pipeline, av-dev-pipeline:task-pipeline и av-dev-pipeline:task-batch разрешают путь к брифу на старте и, не найдя его ни по одному пути, зовут этот скилл. Это не развилка и не повод остановиться — заведение брифа делается молча, как любая другая механика.
• По событию: сменился гейт; появился новый контур, зависимость или источник входа; в журнал ревью попала запись вида «проход не мог этого знать»; свойство промоутнулось в правило линтера (тогда пункт из брифа вычёркивается).
• По просьбе человека.

Планового пересмотра нет.

Шаг 1. Убедиться, что брифа действительно нет

Порядок разрешения пути — тот же, что у конвейера:

1. путь, названный в задании;
2. docs/review-brief.md;
3. .claude/review-brief.md.

Файл есть, но неполон (нет обязательного раздела, раздел пуст, числа без провенанса) — это не заведение с нуля: дозаполняй недостающее и не переписывай то, что уже выверено. Разошедшийся бриф хуже отсутствующего, но переписанный поверх выверенного — хуже разошедшегося.

Шаг 2. Собрать материал из проекта

Бриф выводится из проекта, а не сочиняется. Источники по убыванию плотности:

Раздел брифа	Откуда берётся
## Проект	CLAUDE.md / AGENTS.md, паспорт или README — абзац «что это и чего оно не делает»
## Инварианты	раздел инвариантов CLAUDE.md, архитектура, журнал решений; цитируются формулировкой
## Гейт	Taskfile.yml / Makefile / justfile / CI — сама цель гейта, состав её шагов, коды и логи
## Команды	тот же файл задач: карта проекта, поднять вживую, тесты, дорогое вне гейта, запрещённое
## Прод и поток	документация по деплою и архитектуре, конфиг и его образец, схема БД, файл наблюдений на живых данных
## Модель угроз	конфиг (токены, права), раскладка файлов на диске, схема ключей, места приёма недоверенного входа
## Карта	дерево репозитория: спеки, конвенции, архитектура, журнал ревью, миграции, testdata, основная ветка
## Типовые узлы	дерево пакетов: какие рода узлов реально есть
## Прецеденты	журнал ревью, архивные отчёты триажа, git log по починкам
## Недоступно проверке	журнал ревью (что решили не проверять) плюс общий список из контракта

Прочитай CLAUDE.md и всё, на что он ссылается, до того, как писать первую строку. Бриф, собранный из одного файла, повторяет его и потому бесполезен.

Шаг 3. Заполнить

Идёшь по контракту раздел за разделом. Четыре правила ведения, из-за которых брифы портятся чаще всего:

1. Не пересказывай документацию. Факт, записанный в CLAUDE.md или в архитектуре, попадает сюда ссылкой и одной строкой сути. Исключение — раздел инвариантов: он цитируется дословно, потому что по нему присваивается severity.
2. Числа — с провенансом. «Тела доходили до 42 МБ (замер, docs/local-research.md)». Число без источника проход обязан превратить в условие, то есть оно бесполезно.
3. Пустой пункт называется пустым. «Внешних зависимостей нет — смотри на диск и на СУБД» стоит целого прохода: без этой строки эксплуатационный проход потратит обязательный вопрос впустую или выдумает зависимость. То же про угрозы вне модели, про отсутствующие прецеденты, про отсутствие наблюдателя.
4. Не выдумывай четыре вещи. Измеренные числа; периметр модели угроз; то, что в этом проекте необратимо; и кто обязан гонять дорогую проверку вне гейта — всё это из кода не выводится. Не нашёл в документации — спроси человека на шаге 4, а до ответа напиши пункт словом «неизвестно» с пометкой, что он ждёт ответа. Придуманное число здесь дороже отсутствующего: проход сошлётся на него как на замер.
5. Что выведено, а не прочитано, — помечай. Чаще всего это severity у инвариантов: проекты редко пишут её рядом с формулировкой, и её приходится выводить по обратимости последствия. Пометка «выведена по обратимости» стоит трёх слов и сообщает проходу, чьё это суждение, — а он по ней ставит critical. То же для периметра, восстановленного из конфига, и для чисел, чей источник по ссылке не подтвердился.

Шаг 4. Показать человеку

Бриф — единственный файл, который конвейер читает как истину, поэтому он показывается, а не заводится молча:

• покажи готовый файл (или дифф, если это обновление);
• отдельным коротким списком назови, что выведено из проекта, а что предположено или осталось неизвестным — по этим строкам человек и правит;
• если на шаге 3 остались вопросы из класса «не выдумывай три вещи», задай их здесь, разом и с вариантами.

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

Бриф ведёт проект. Файл кладётся в репозиторий проекта и коммитится вместе с той работой, в ходе которой заведён. Плагин его больше не правит — он только читает.

Шаг 5. Вернуться в вызвавший шаг

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

Если завести нельзя

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

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