Спецификация для reviewer'а

1. Инженерного черновика уже недостаточно

На старте инженерный черновик спецификации действительно работает отлично: он сводит вас и Claude Code к общей задаче — что делаем, где границы, чего не трогаем, как проверим. Но у такого документа есть слабое место: он написан изнутри вашей головы, а reviewer читает снаружи. И если документ понятен только тому, кто месяц живёт проектом, значит, он всё ещё сырой.

Инженерный draft обычно отвечает на вопрос «что делаем технически». А версия для reviewer'а должна отвечать на более неприятные, но очень полезные вопросы: кому это помогает, какой кусок реально работает, что я увижу на demo, как проверить руками, чего вы не обещаете. Reviewer не обязан быть телепатом, даже если вы очень на это рассчитываете.

Поэтому здесь не происходит магии и не рождается новой сущности: я не выкидываю прежний SPEC.md и не пишу роман с нуля — делаю второй проход и вывожу из инженерного черновика текст, который выдержит холодный взгляд со стороны. А холодный взгляд, кстати, лечит scope creep и фразы вида «ну тут всё примерно понятно».

2. SPEC.md и MVP_SPEC.md: одно семейство

В этом месте многие начинают путаться в именах файлов и устраивать маленький локальный сериал под названием SPEC_final_final_real.md. Лучше не надо. Логика простая: у вас одно семейство документов на проект. Для чистого MVP-архетипа удобно MVP_SPEC.md; для capstone, где SPEC.md уже заведён, — усиливайте его, а не плодите близнеца.

Самое важное правило здесь — один source of truth. Если вы ведёте оба файла, а потом в одном user один, в другом другой, а demo-сценарий вообще третий, вы не создаёте гибкость. Вы создаёте красивую многосерийную путаницу.

Полезно также не смешивать роли документов. Спецификация отвечает за замысел, границы и проверку, а EVIDENCE_LOG.md — за следы выполнения: что пробовали, запускали, что сломалось, что проверили. Если evidence-лог уже заведён под близким именем — используйте его. Если же вы начнёте складывать в спецификацию историю всех попыток, она быстро превратится в археологический слой. Для археологии у нас есть другие файлы.

3. Reviewer хочет понять за пять минут

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

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

4. Проблема — на языке пользователя

В разделе Problem reviewer должен сначала увидеть боль, а не выбранный вами технический трюк. К этому месту проблема уже понятна вам самому — теперь важно проверить, не подменили ли вы её описанием реализации вроде «нужно сделать AI-классификацию тикетов и генерацию draft-ответов».

Ниже — уже рабочий фрагмент для нашего AI Support Agent:

## Проблема

Оператор поддержки небольшого интернет-магазина получает десятки обращений в день.
Повторяющиеся вопросы про статус заказа и возвраты съедают время на ручные ответы.
Из-за этого сложные и рискованные кейсы обрабатываются позже, чем нужно.

Если в Problem уже поселились FastAPI, классификатор, RAG, эмбеддинги и прочие вкусные технические слова — reviewer ещё не увидел боль, он уже продирается через implementation.

5. User и JTBD: из общей аудитории в живую роль

В разделе Target user / JTBD reviewer должен увидеть одну живую роль, одну рабочую ситуацию и текущий workaround. Не «магазины» и не «поддержку вообще», а конкретного человека, у которого утром забит inbox и который сейчас выкручивается заметками и копипастой.

Для архетипа AI Support Agent хорошая формулировка выглядит так:

## Целевой пользователь / JTBD

Пользователь: оператор поддержки небольшого интернет-магазина.

Когда утром inbox заполнен десятками тикетов,
я хочу быстро отделить типовые обращения от risky-case
и получить черновик ответа на простые вопросы,
чтобы не тратить время на копирование шаблонов
и не пропускать refund-запросы с большой суммой.

Полезный признак reviewer-ready блока — current workaround виден рядом, а не болтается отдельной мыслью. Иначе продукт выглядит так, будто пользователь до вас сидел в вакууме и терпеливо ждал именно ваш MVP.

6. Release slice: один маршрут вместо набора функций

В разделе Release slice reviewer должен увидеть один законченный маршрут, а не список симпатичных функций. К этому месту must-have, non-goals и forbidden zone уже выбраны — теперь важно показать, что реально работает вместе.

Теперь переведём это в текст спецификации:

## Релизный срез

Вход: sample ticket с текстом и customer id.

Основное действие: система классифицирует тикет и,
если обращение типовое, предлагает черновик ответа.

Выход: оператор видит label, draft и может принять
или отредактировать ответ.

Guardrail: refund > $100 не обрабатывается автоматически
и требует manual approval.

Как только этот маршрут зафиксирован, план проверки и demo перестают жить отдельной жизнью: оба просто воспроизводят именно его.

7. План проверки и demo: одна цепочка

В План проверки и Demo scenario reviewer должен увидеть, как это проверяется руками и показывается без шаманства. Очень многие начинающие авторы разводят план проверки и demo scenario по разным комнатам, как будто это чужие друг другу родственники. На самом деле это одна цепочка. План проверки отвечает на вопрос «как проверяем», а demo scenario делает эту проверку видимой и воспроизводимой. Если между ними нет связи, спецификация начинает звучать убедительно, но проверяется как туман.

Ниже — компактный вариант План проверки для нашего архетипа:

## План проверки

Запуск: `docker compose up`

Smoke-check:
1. Inbox открывается с 10 sample tickets.
2. Ticket #3 получает label `typical` и draft ответа.
3. Ticket #7 с refund $250 блокируется и требует manual approval.
4. В audit trail видно, что предложил AI и что сделал оператор.

Теперь посмотрите, как это превращается в demo-сценарий. Хороший способ — буквально сопоставить критерии приёмки со сценой показа:

Именно так demo перестаёт быть театром «сейчас я покликаю всё подряд, и вы сами догадаетесь, что у меня работает» и становится управляемой демонстрацией критериев приёмки. Reviewer не должен угадывать, что тут случайный клик, а что доказательство.

Ниже — уже нормальный фрагмент Demo scenario:

## Demo-сценарий

1. Открыть inbox с 10 sample tickets.
2. Выбрать типовой ticket #3 и показать classification + draft.
3. Принять draft и открыть audit trail.
4. Выбрать ticket #7 с refund $250 и показать блокировку.

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

8. Known limitations и Risks: честность

Когда автор боится писать ограничения, он обычно думает, что выглядит слабее. На практике происходит ровно обратное: сильнее выглядит проект, у которого границы названы вслух. Фраза production-ready притягивает проблемы ровно так же, как магнит притягивает скрепки. Поэтому лучше быть честным и конкретным.

Для нашего AI Support Agent раздел может выглядеть так:

## Известные ограничения

- Работаем на sample data, не на live CRM.
- Accuracy измеряется только на demo-наборе из 10 тикетов.
- Нет multi-language support.
- High-value refund не отправляется автоматически.

А рядом можно коротко обозначить риски:

## Риски

- На новых формулировках accuracy может быть ниже, чем на demo-set.
- Порог high-value refund сейчас задан правилом, а не adaptive-логикой.
- Draft ответа оценивается оператором вручную, без отдельного quality-score.

В таких разделах нет ничего стыдного. Наоборот, reviewer видит, что вы не продаёте учебный MVP как enterprise-систему, и доверие растёт. Нормально сказать: «показываем один рабочий slice, но не готовы обслуживать боевой поток магазина в понедельник утром». А вот если документ звучит так, будто завтра его можно везти в production, а проект держится на sample data и ручной проверке, — значит, завелась лишняя бравада. Её лучше аккуратно выселить.

9. Claude Code как reviewer спецификации

На этом этапе Claude Code особенно полезен не как генератор новых идей, а как reviewer документа. Это принципиально разные роли. Если вы просто попросите «улучши мою спецификацию», Claude с радостью подкинет ещё семь фич, два интеграционных направления и немного красивой жизни. Звучит заманчиво, но scope freeze после этого обычно начинает тихо плакать в углу.

Поэтому запрос лучше делать жёстче и конкретнее. Например так:

Проверь эту спецификацию как reviewer.

Не предлагай новые функции, если они не нужны для core flow.

Найди:
1. неясные формулировки для пользователя;
2. scope creep и противоречия non-goals;
3. пробелы в verification и demo-сценарии;
4. фразы, которые звучат как fake production claims.

Верни ответ кратко, по разделам.

Ещё лучше, если для такого review вы откроете новую сессию — тогда Claude посмотрит на документ холоднее, без инерции предыдущей переписки. Это тот самый случай, когда свежий взгляд реально помогает.

Удобно также просить Claude возвращать не абстрактное «надо улучшить раздел Problem», а формат вроде: «цитата из фрагмента → почему неясно → как переформулировать». Тогда review становится рабочим, а не философским. И самое главное — помните, что вам сейчас нужен не партнёр по мозговому штурму, а спокойный редактор, который заметит скользкие места.

10. Каркас готового документа

Когда все предыдущие части собраны, у вас получается очень простой, но сильный каркас: не красивость ради красивости, а документ, который читается сверху вниз без прыжков между файлами и догадок по контексту. Если у вас чистый MVP, этот каркас может жить в MVP_SPEC.md; если нет — в основном SPEC.md.

# SPEC.md

## Value proposition
...

## Проблема
...

## Целевой пользователь / JTBD
...

## Область / Не-цели
...

## Релизный срез
...

## Запретная зона
...

## Метрика успеха
...

## План проверки
...

## Demo-сценарий
...

## Известные ограничения / риски
...

Обратите внимание, что здесь нет ничего экзотического. Спецификация не обязана быть длинной, чтобы быть сильной, — она обязана быть связной. Reviewer проходит по документу и нигде не спотыкается о «подождите, а для кого это вообще?» или «а что я увижу вживую?». Если после чтения он пересказывает ваш core flow своими словами и воспроизводит demo без шаманства и телепатии — значит, документ уже выполняет свою работу. И это очень хорошее состояние для спецификации.