Глава 6. Спецификация вместо задания

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

Звучит банально ровно до момента, когда выясняется, что именно считать точной постановкой.

Прототип стал техническим заданием Самое интересное изменение последнего года описали так: уровень абстракции уехал настолько, что само техническое задание теперь и есть рабочий проект, только в миниатюре.

История из практики. Руководитель, вместо того чтобы полдня рассказывать, что он хочет увидеть от продукта, берёт низкокодовый конструктор, собирает рабочий процесс сам и показывает прототип. А дальше говорит: сделайте мне это агентами и в прод.

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

ГЛАВНОЕ ПРО ПОСТАНОВКУ Можешь показать вместо того, чтобы описывать, показывай. Работающая миниатюра, набросок интерфейса, пример готового результата, набор тестов, кусок кода из другого проекта. Спецификацией может быть что угодно, что снимает неоднозначность. Формат текста тут никакой не священный.

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

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

Документ Что внутри Кто читает

Центральная спецификация про- Что за система, границы, ключе- Все агенты, всегда екта вые решения

Спецификация под новую функ- Что именно делаем сейчас, кри- Агент на этой задаче цию терии готовности

План реализации Разбивка на пункты в нужном Агент, по одному пункту порядке

Спецификация вместо задания

Документ Что внутри Кто читает

Файл прогресса Что сделано, что заблокировано, Агент пишет, человек читает что пропущено

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

ПУТЬ ЗАДАЧИ

Идея Требования Спецификация План Реализация Проверка

что хотим что должно быть как проверим в каком порядке делаем годится или нет

Один файл или несколько Спор без универсального ответа, но с внятными аргументами с обеих сторон.

За один центральный документ. Несколько файлов хуже поддерживаются: агент что-то меняет в одном и забивает на второй, и через неделю они разъезжаются. Один файл на четыре-пять тысяч строк держится нормально.

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

КАК РЕШИТЬ У СЕБЯ Ориентируйся на связность. Области реально независимы и меняются по отдельности, разбивай. Правки постоянно задевают несколько областей сразу, держи один файл, иначе будешь ловить рассинхрон. Практический признак: правишь один файл и каждый раз лезешь во второй, значит объединяй нахуй.

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

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

Правильная спецификация отвечает на три вопроса.

Что должно получиться. Не как это сделать, а что появится в мире.

Как это проверить. Конкретно: какая команда, какой файл, какой ответ.

Спецификация вместо задания

Когда переходить дальше. Явный запрет двигаться к следующему пункту, пока текущий не закрыт по критериям.

Полный конвейер У команд, которые прошли этот путь до конца, конвейер выглядит примерно одинаково.

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

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

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

КУДА УХОДИТ ВРЕМЯ

Задача поставлена как?

Одним абзацем в чате Спецификацией с критериями

быстро начали, долго переделываем медленно начали, один проход

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

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

ПРОВЕРКА СПЕЦИФИКАЦИИ НА ДОСТАТОЧНОСТЬ 1. Есть ли в ней хоть одно утверждение, которого не понять, посмотрев на код? Нет, значит спецификация не нужна, хватит кода. 2. Может ли агент по ней однозначно сказать, готова задача или нет? Нет, значит добавляй критерии. 3. Есть ли в ней то, что уже написано в коде? Убирай, эти двое разъедутся. 4. Прочитай её вслух. Места, где ты запнулся, агент поймёт неправильно.

Спецификация вместо задания

Чего спецификация не решает Честности ради. От одного класса проблем спецификация не спасает: от того, чего ты сам не знаешь.

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

Поэтому спецификация проверку не отменяет, а делает возможной. Разные слои, и нужны оба, без вариантов.

Что запомнить Показывай вместо того, чтобы описывать, если можешь. Прототип понимается однозначнее текста.

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

Спецификация без критериев проверки это разрешение объявить готовым что угодно.

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

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

← Маршрут новичка · оглавление · Требования, понятные агенту →

Спросить книгу может любой, кто вошёл в Neuraldeep Hub: агент ищет ответ по тексту и приводит цитату со ссылкой на главу.