Writing an executable spec

Рабочая спека состоит из трёх слоёв, и у каждого своя функция. Скелет выглядит так:

# spec: экспорт отчёта в CSV

## Намерение
Бухгалтерия выгружает месячный отчёт в свою систему.
Сегодня данные копируют руками из таблицы — 40 минут и ошибки.

## Ограничения
- Не менять существующий эндпоинт /api/reports — им пользуется мобильное приложение.
- Экспорт доступен только ролям accountant и admin.
- Кодировка UTF-8 with BOM: файл должны открывать в Excel.

## Критерии приёмки
- AC-1: ...

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

Ограничения — это инварианты: что нельзя трогать, какие роли, лимиты и совместимости обязательны. Именно ограничения чаще всего теряются в ad-hoc промптинге, потому что они «очевидны» автору. Критерии приёмки — проверяемые утверждения, по которым фича принимается. Три слоя не пересекаются: «зачем», «что нельзя», «как проверим». Если абзац не попадает ни в один слой — вероятно, это деталь реализации, и ей место в плане, а не в спеке.

Критерий приёмки хорош, если два разных человека, прочитав его, одинаково ответят «выполнен или нет». Два рабочих шаблона. Первый — Given/When/Then из BDD:

- AC-1. Дано: отчёт за март содержит 10 000 строк.
  Когда: пользователь с ролью accountant нажимает «Экспорт в CSV».
  Тогда: файл скачивается не дольше 5 секунд
  и открывается в Excel без ошибок кодировки.

- AC-2. Дано: пользователь с ролью viewer.
  Когда: он запрашивает POST /api/reports/export.
  Тогда: ответ 403, кнопка экспорта в UI не отображается.

Второй — EARS (Easy Approach to Requirements Syntax), удобный для системных требований: «КОГДА <триггер>, СИСТЕМА ДОЛЖНА <реакция>». Например: «КОГДА экспорт длится дольше 30 секунд, СИСТЕМА ДОЛЖНА прервать задачу и показать ошибку с идентификатором для поддержки».

Сравните с типичным непроверяемым критерием: «экспорт должен быть быстрым и удобным». Быстрым — это сколько? Удобным — по чьей оценке? Каждое прилагательное без числа превращается в спор на приёмке. Правило: скорость — в секундах и перцентилях, объём — в строках и мегабайтах, доступ — в ролях, ошибки — в кодах и текстах. И обязательно включайте негативные сценарии: пустой отчёт, нет прав, обрыв соединения. Агенты генерируют happy path сами, а вот граничные случаи — только если они названы.

Противоположная крайность недоспецификации — спека-роман: двадцать страниц, где намерение повторено пять раз разными словами, критерии перемешаны с пожеланиями, а посередине — рассуждение о том, какую библиотеку CSV выбрать. Такой документ не читает никто: человек устаёт, а у агента важное ограничение с двенадцатой страницы проигрывает конкуренцию за внимание случайным деталям.

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

Отдельная дисциплина — честность про неизвестное. Если вы не знаете, нужна ли поддержка отчётов больше 100 тысяч строк, не угадывайте — пометьте: [NEEDS CLARIFICATION: максимальный размер отчёта?]. Spec Kit использует ровно такие маркеры: агент на шаге clarify задаст вопросы по каждому, и решение примет человек, а не генератор. Ориентир размера: спека фичи — одна-две страницы. Всё, что длиннее, обычно означает, что фичу пора резать на несколько.

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

Практические правила. Одна сущность — одно имя: если в спеке «отчёт», «выгрузка» и «документ» означают одно и то же, договоритесь об одном термине; агент может решить, что это три разные вещи. Один критерий — одно проверяемое утверждение: «файл скачивается быстро и содержит все колонки» — это два критерия, и на приёмке они могут разойтись. Списки вместо прозы: ограничения и критерии — маркированными пунктами с идентификаторами (AC-1, AC-2), чтобы на них можно было ссылаться в тестах, коммитах и ревью.

Структура тоже несёт смысл: заголовки разделов — это якоря, по которым агент навигирует. Стандартный порядок «намерение → ограничения → критерии» работает лучше произвольного, потому что агент видит рамку до деталей. Полезная финальная проверка — прогон спеки через самого агента: «прочитай спеку и перечисли все места, где тебе пришлось бы угадывать». Пять минут такого аудита дешевле, чем итерация переделки после implement.