Spec из разговора: grilling, затем `/to-spec`

Зачем это нужно

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

Поэтому spec не пишут сразу. Сначала агент изучает код и расспрашивает вас, пока у вас обоих не сложится одинаковое понимание задачи. Только потом это понимание записывают в документ.

Как это устроено

Процесс большой задачи в курсе выглядит так: grilling → spec → tickets → реализация каждого ticket → проверка по spec. Этот Bite — про первые два шага.

Grilling — сессия, в которой вопросы задаёт агент. Документация Claude Code описывает тот же приём: для крупной фичи начните с короткого промпта и попросите Claude проинтервьюировать вас инструментом AskUserQuestion — о реализации, UI/UX, крайних случаях и компромиссах. В Cadence для этого есть skill /grill-me.

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

Дальше идут раунды вопросов. На каждый вопрос агент предлагает свой вариант ответа, и часто достаточно короткого «согласен» или «делай как считаешь лучше, потом измерим». Если вопрос написан жаргоном, попросите агента zoom out: «объясни проще, с более общей точки зрения». Агент переформулирует вопрос, и вы отвечаете осознанно, а не наугад. Grilling заканчивается, когда у агента не остаётся вопросов.

Spec пишет skill /to-spec. Он не задаёт вопросов заново: он ждёт, что grilling уже прошёл в этом разговоре, и превращает его в документ, который публикует в ваш issue tracker (см. 6.2). Skill объявлен с disable-model-invocation: true — по документации это значит, что Claude не запустит его сам, только вы командой /to-spec. Так и нужно: момент «понимание сложилось, пишем» выбираете вы.

Шаблон spec в Cadence такой:

• Problem Statement и Solution — проблема и решение глазами пользователя;
• User Stories — длинный нумерованный список «As an , I want , so that »;
• Implementation Decisions — модули, интерфейсы, изменения схемы, API-контракты;
• Testing Decisions, Out of Scope, Further Notes.

Problem и Solution дают агенту «зачем»: на развилке, которой нет в spec, он принимает решение, исходя из цели фичи. Номера user stories пригодятся позже: ticket или коммит может сослаться на «story 35».

Перед публикацией /to-spec в Cadence спрашивает, на каком test seam — шве, где тесты подключаются к коду, — проверять фичу. Документация Claude Code советует похожее: полезная spec самодостаточна, называет затронутые файлы и интерфейсы, перечисляет, что вне рамок, и заканчивается шагом сквозной проверки, который доказывает, что фича работает.

Практика

В Cadence запустите grilling про дашборд аналитики для преподавателя. Если skill /grill-me ещё не подключён, начните с промпта из документации:

I want to build an instructor analytics dashboard. Interview me in detail
using the AskUserQuestion tool. Ask about technical implementation, UI/UX,
edge cases, concerns, and tradeoffs.

Ответьте на два-три раунда вопросов, хотя бы раз попросите zoom out, затем выполните /to-spec. Обратите внимание, какие крайние случаи предложил агент — например, пустой экран для нового преподавателя без продаж. Не начинайте реализацию: spec ещё нужно разрезать на tickets (см. 6.4).

Подводные камни

• /to-spec без grilling. Skill пересказывает разговор. Если разговора не было, в spec окажутся догадки агента.
• Конкретные пути и код в spec. Spec может пролежать до реализации несколько дней, а файлы за это время переедут. Оригинал советует описывать модули и интерфейсы, а не строки кода.
• Spec как пересказ, который вы не прочитали. Автор оригинала признаётся, что почти не читает свои spec: они редко расходятся с разговором. Это его выбор; пока у вас мало опыта, хотя бы пробегите Out of Scope и Testing Decisions.

Вывод: spec — это не текст, который вы сочиняете, а запись понимания, к которому вы с агентом пришли в grilling.

Проверь себя

Источники

• Anthropic, Best practices for Claude Code
• Anthropic, Extend Claude with skills
• По мотивам AI Coding Crash Course, AI Hero