системный анализ · 5 минут
Спека, которую агент не переврёт: 12 проверок перед тем, как отдать задачу
Агент не задаёт уточняющих вопросов. Он берёт спецификацию, достраивает недостающее и выдаёт результат, который выглядит правдоподобно. Проблема не в том, что он ошибается: проблема в том, что достраивает он каждый раз по-своему, и вы узнаёте об этом на приёмке.
Ниже двенадцать мест, где спецификация оставляет агенту свободу. Пройдите по списку до того, как он начнёт писать. Каждый пункт занимает минуту, и каждый закрывает одно решение, которое иначе примут за вас.
Источники
1. У каждого требования есть цитата и ссылка на источник, а не ваш пересказ.
Агент не отличает требование заказчика от вашего домысла и уравнивает их в правах. Кто ведёт source map, этот пункт уже закрыл.
2. В спецификации нет ссылок на контекст, которого в ней нет.
«Как в прошлом проекте», «см. Confluence», «по аналогии с биллингом» — агент не пойдёт смотреть, он придумает.
3. Противоречия между источниками названы вслух, и указано, какое требование победило.
Иначе агент выберет то, которое ближе к концу текста.
Язык
4. Каждый термин определён один раз, синонимов нет.
«Клиент», «пользователь», «абонент» в одном документе превращаются в три разные сущности в модели данных.
5. Ни одного «и так далее», «аналогично», «и прочее».
Список, который вы не дописали, агент допишет. Это будет его список.
6. Каждое «должен» имеет проверяемый критерий.
«Быстро» становится «не дольше 300 мс на 95-м перцентиле», иначе проверить результат нечем.
Границы
7. Написано, чего делать не надо.
Незаданная граница — самое частое место, где агент дописывает лишнюю функциональность и вы платите за её сопровождение.
8. Описаны негативные сценарии, а не только happy path.
Happy path агент соберёт и без вас. Стоимость создаётся на остальных ветках.
9. Для каждой сущности сказано, что происходит при её отсутствии, удалении и дубле.
Три состояния, которые не приходят в голову, пока не сломается прод.
Решения
10. Решения, принятые вами молча, записаны как решения.
Всё, что вы выбрали «потому что очевидно», через месяц не сможет объяснить никто, включая вас. Для таких решений есть Decision Log.
11. Формат результата задан примером, а не описанием.
Кусок целевого артефакта работает лучше двух абзацев про то, каким он должен быть.
Проверка
12. Спецификация проходит тест на постороннего.
Дайте коллеге, который не в проекте. Если он задаёт вопросы по фактам, а не по смыслу — агент задавать не станет, он ответит сам.
Забрать версию для печати
Одна страница, только формулировки, без пояснений. Оставьте адрес, PDF и Markdown придут письмом.
Прислать PDFЧасто спрашивают
Чем спецификация для агента отличается от обычного ТЗ?
Ничем по составу и многим по строгости. Человек, наткнувшись на пробел, приходит и спрашивает. Агент закрывает пробел молча и каждый раз по-своему, поэтому приемлемо неточные места становятся источником расхождений.
Сколько времени занимает проверка по списку?
Около двенадцати минут на среднюю задачу, по минуте на пункт. Дольше всего идут границы и негативные сценарии: их обычно не писали вовсе.
Нужно ли проходить все двенадцать пунктов каждый раз?
На коротких задачах хватает первых шести. Полный список окупается там, где результат агента идёт в продакшн или задача передаётся между людьми.
Почему нельзя просто попросить агента задавать уточняющие вопросы?
Можно, и он их задаст. Но отвечать всё равно придётся вам, а список вопросов будет зависеть от формулировки запроса и меняться от прогона к прогону.
Что делать, если спецификацию писал не я?
Пройти по списку и вынести найденное автору отдельным списком вопросов. Это быстрее, чем переписывать, и оставляет ответственность там, где она была.