Метод thin-spec для AI-фич, которые не уходят в сторону

Почему работа над AI-фичами уходит в сторону

Работа над AI-фичами часто начинает уходить в сторону ещё до того, как написан код. Команда открывает чат, пишет промпт и оценивает результат. Это кажется быстрым. Но при этом пропадает то, что удерживает всех на одной линии: понятное описание проблемы пользователя обычными словами.

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

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

Размытые цели только ухудшают ситуацию. Фразы вроде «сделать ответы поддержки лучше» или «улучшить onboarding» могут привести к очень разным черновикам. Один инструмент напишет текст. Другой построит логику маршрутизации. Третий добавит аналитику и настройки, о которых никто не просил. Всё это может выглядеть отполированным. Но не факт, что хоть что-то решает настоящую проблему.

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

Метод thin-spec останавливает это отклонение на раннем этапе. Сначала напишите короткую формулировку проблемы. Затем добавьте жёсткие критерии приемки. И только после того, как границы ясны, дайте инструменту дописать рутинные детали. Такой простой порядок сильно сокращает переделки.

Что нужно thin-spec

Thin-spec короткий, но не расплывчатый. Он даёт инструменту достаточно направления, чтобы тот не начал фантазировать, и ничего лишнего.

Начните с одной формулировки проблемы. Держите её в нескольких строках. Укажите, у кого проблема, что сейчас идёт не так и что должно происходить вместо этого. Если для объяснения нужно три абзаца, задача всё ещё слишком туманная.

Обычно достаточно четырёх частей:

• кто чувствует проблему
• что ломается или занимает слишком много времени
• какой результат считается достаточно хорошим для этой версии
• где фича применяется, а где нет

Потом добавьте небольшой набор жёстких критериев приемки. Это простые проверки «проходит/не проходит». Коллега должен суметь протестировать их за несколько минут.

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

Non-goals тоже нужны. Назовите, что фича не будет делать, какие данные она не может использовать и какие крайние случаи вы оставляете на потом. Так объём работы не начнёт тихо раздуваться в середине процесса.

Смысл простой: люди задают границы. Инструменты заполняют пробелы.

Опишите проблему в нескольких строках

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

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

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

Например: «Сотрудник поддержки, который просматривает новый тикет, не может понять, сообщал ли клиент о той же проблеме в последние 30 дней. Сотрудник вручную открывает несколько прошлых тикетов и читает заметки. Достаточно хорошо для этой версии: когда тикет открывается, система показывает до трёх вероятно связанных тикетов с коротким объяснением для каждого совпадения. Если совпадений нет, ничего не показывать».

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

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

Перед тем как двигаться дальше, прочитайте абзац один раз и задайте прямой вопрос: смогут ли два человека представить один и тот же пользовательский момент, опираясь только на эти строки? Если нет, сократите текст ещё раз.

Напишите thin-spec за один проход

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

Начните с проблемы, а не с интерфейса. Напишите три–пять предложений о том, у кого проблема, что сейчас идёт не так и что должно измениться. Используйте простой язык.

Потом запишите пять–восемь критериев приемки. Покройте нормальный сценарий, грязный вход и одну-две вещи, которые не должны происходить ни при каких условиях. Используйте конкретные формулировки вроде «возвращает один понятный ярлык» или «не отправляет ответ без одобрения человека».

Добавьте два–три non-goals до того, как попросите инструмент помочь. Это экономит время, потому что сразу отсекает типичные лишние вещи: аналитику, админ-настройки или полный редизайн старого экрана.

Простой порядок может выглядеть так:

1. Опишите проблему несколькими предложениями.
2. Добавьте понятные критерии приемки.
3. Перечислите non-goals.
4. Попросите инструмент подготовить текст, тесты и заметки по крайним случаям.
5. Сверьте черновик с критериями приемки до того, как кто-то начнёт разработку.

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

Задайте критерии приемки, которые инструмент не сможет обойти

Критерии приемки удерживают работу над AI-фичами в здравых рамках. Слабая спецификация всё ещё может породить красивый черновик, поэтому проверки должны быть достаточно ясными, чтобы человек мог проверить их своими глазами.

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

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

Числа помогают, потому что они заставляют принимать решения. Например:

• принимать CSV до 5 000 строк
• выдавать первый результат меньше чем за 15 секунд
• если confidence падает ниже 0.75, помечать строку на проверку
• если вход пустой, показывать ошибку и не вызывать модель
• оставлять исходный текст пользователя видимым на экране проверки

Слова вроде «быстро» и «просто» создают проблемы, потому что каждый понимает их по-своему. Заменяйте их лимитом по времени, порогом или видимым поведением. «Быстро» превращается в «показывает черновик ответа меньше чем за 8 секунд». «Просто» превращается в «сотрудник поддержки может одобрить или отклонить черновик в один клик».

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

Пусть инструменты допишут остальное

Когда в спецификации уже есть ясная формулировка проблемы и жёсткие критерии приемки, можно позволить инструменту заняться рутинными деталями. Но не давайте ему переписывать правила.

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

Держите сгенерированные детали отдельно от исходной спецификации. Thin-spec храните в одном файле. AI-вывод сохраняйте в отдельном черновике для тестов, крайних случаев и заметок по реализации. Так ревью проходит быстрее и безопаснее. Если инструмент начинает выдумывать бизнес-правила, можно удалить черновик и запустить генерацию заново, не трогая настоящую спецификацию.

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

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

Простой пример на основе support inbox

Небольшой команде поддержки не нужна длинная спецификация, чтобы сделать что-то полезное. Представьте, что один сотрудник вставляет цепочку писем клиента во внутренний инструмент. Инструмент читает переписку, предлагает ответ и добавляет тег срочности, чтобы команда понимала, на что отвечать первым.

Задача узкая, а значит, хорошо подходит для thin-spec. Вы не просите модель перестраивать поддержку целиком. Вы просите её сделать две вещи: набросать ответ и отсортировать сообщение по срочности.

Короткая формулировка проблемы может выглядеть так:

«Когда сотрудник поддержки вставляет цепочку писем клиента, система пишет черновик ответа в тоне компании и помечает цепочку как low, normal, high или manual review. Черновик должен использовать только факты из переписки. Если данных не хватает, он должен их запросить».

Критерии приемки удерживают сборку в нужном русле:

• Если клиент пишет: «Мой заказ всё ещё не пришёл», но не указывает номер заказа, черновик запрашивает номер заказа. Он не выдумывает его и не обещает статус доставки, который нельзя проверить.
• Если в цепочке есть угрозы, оскорбления или признаки того, что кому-то может быть небезопасно, система помечает это как manual review или high urgency. Ответ остаётся спокойным и коротким.
• Если в переписке есть номер заказа и простой вопрос о доставке, система может подготовить обычный ответ и поставить тег срочности в зависимости от проблемы.
• Если модель не уверена, она говорит меньше и передаёт случай человеку.

Именно последнее правило особенно важно. Слабый черновик стоит нескольких секунд на исправление. Уверенный, но неверный ответ может привести к возвратам, чарджбэкам или злому клиенту.

Ошибки, которые зря тратят время

Большинство задержек связано не с самой моделью. Они возникают из-за расплывчатых инструкций вокруг неё.

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

Ещё одна ошибка — писать критерии приемки как описание кода, а не как результат. «Использовать vector store», «вызвать эту функцию» или «сортировать этим промптом» — это выбор реализации, а не правила «проходит/не проходит». Хороший критерий описывает, что должен получить пользователь. «Черновик ответа сохраняет правильную сумму возврата» — полезно. «Использовать chain of thought и шаг оценки» — нет.

Команды также теряют время, когда меняют правила только внутри промптов и больше нигде. Так появляется скрытая спецификация. Один человек обновляет system prompt. Другой читает старый документ. Через неделю уже никто не понимает, виноват ли инструмент или правила просто изменились.

Если правило важно, оно должно быть в общей спецификации и в критериях приемки.

Важна и ответственность. Если за финальную спецификацию никто не отвечает, она превращается в кучу комментариев, правок промпта и сообщений в чате. Инженеры строят по одной версии. Продукт видит другую. А потом в путанице винят инструмент.

Признаки проблемы легко заметить:

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

Быстрая проверка перед стартом разработки

Thin-spec должен выдержать холодное чтение. Если новый коллега не может объяснить проблему за 30 секунд, значит спецификация всё ещё туманная.

Перед началом разработки прочитайте формулировку проблемы вслух. Затем прочитайте каждый критерий приемки и задайте один прямой вопрос: два разных человека оценили бы это одинаково? Если нет, перепишите.

Быстрое ревью занимает примерно пять минут:

• попросите человека вне планировочного чата пересказать проблему простыми словами
• проверьте каждый критерий приемки на чёткий результат «да/нет»
• добавьте хотя бы один путь отказа на случай отсутствующих данных, плохого входа или неясного намерения
• вынесите non-goals в отдельный короткий блок, чтобы никто не принял их за незавершённую работу

Так вы ловите отклонение, пока исправить его ещё дёшево. «Предлагайте ответы на письма клиентов» звучит неплохо, но оставляет слишком много пространства. Добавьте такие случаи, как «не обещать сумму возврата без данных по заказу» и «показывать “нужна проверка человеком”, когда намерение сообщения неясно», и у команды уже будет на что опираться.

Что делать дальше вместе с командой

Выберите одну небольшую фичу на этой неделе и проверьте на ней метод thin-spec. Не начинайте с большой миграции или сложного ключевого процесса. Возьмите что-то ограниченное, например правило тегов для входящих сообщений, блок предложений ответа или простое админ-действие, которое и так вызывает споры.

Сделайте процесс простым. Один человек пишет короткую формулировку проблемы. Другой — жёсткие критерии приемки. Затем пусть AI-инструменты подготовят из этого тикеты, крайние случаи или заметки по реализации. Если черновик уходит в сторону, значит спецификация всё ещё слишком туманная.

После релиза сравните эту фичу с прошлым AI-проектом. Смотрите не на мнения, а на переделки. Посчитайте, сколько раз команде пришлось переписывать промпты, заново открывать тикеты, менять поведение после ревью или дважды объяснять одно и то же правило. Даже приблизительного сравнения достаточно. Если thin-spec сокращает хотя бы один-два раунда путаницы, метод уже окупился.

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

Если у вашей команды и дальше получаются неровные результаты, может помочь внешняя проверка. Oleg Sotnikov на oleg.is работает как Fractional CTO и startup advisor, и такая процессная работа естественно входит в эту роль. Свежий взгляд на то, как команда пишет спецификации, использует AI-инструменты и переходит от черновика к релизу, может выявить пробелы, которые изнутри кажутся нормой.

Начинайте с малого. Измеряйте переделки. Сохраняйте шаблон. Потом повторите тот же тест на следующей неделе.