Задача, которая решается

Четыре части поручения

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

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

Где менять. Файл, модуль, функция — любое указание места. Это самая дешёвая часть поручения и самая окупаемая: агент, которому названо место, начинает с него, а не с поиска. Если места вы не знаете — так и скажите: «найди, где считается итог корзины, и покажи мне, прежде чем править». Это тоже указание, просто другое.

Чем проверять. Команда, которую надо запустить; тест, который должен пройти; сценарий, который надо повторить руками. Без этой части «сделано» превращается в предмет спора: агент считает задачу выполненной, вы — нет, и оба по-своему правы.

Чего не трогать. Границы. Это та часть, которую пропускают чаще всего, — и именно её отсутствие даёт дифф шире задачи. «Соседние модули не трогай», «версии библиотек не обновляй», «формат выгрузки не меняй», «публичные имена функций оставь как есть».

Сравните два поручения по одной и той же задаче.

Второе поручение длиннее ровно на одно предложение. Разница в результате — между «надо разбирать полчаса» и «принято за минуту».

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

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

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

Поведение, способ и признак готовности

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

Описать можно поведение — то, что должно получиться, — или способ — то, как этого добиться. Общее правило: описывайте поведение и оставляйте выбор способа агенту.

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

Сравните.

Вторая половина этой главы — про признак готовности. Это ответ на вопрос «как мы узнаем, что сделано». Он бывает трёх видов, и все три годятся.

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

Команда. «После правки должна проходить сборка», «линтер не должен ругаться». Слабее теста, но лучше, чем ничего.

Сценарий. «Открыть корзину, положить три одинаковых товара, итог должен быть тридцать.» Годится там, где теста нет и написать его дорого; проверяете вы руками.

Отсутствие признака готовности — самая распространённая причина того, что задача «вроде сделана», а через день выясняется, что нет. Агент честно считал, что закончил: у него не было способа узнать иначе.

Ещё один довод за поведение, о котором редко думают: поведение проверяемо, а способ нет. «Не держит весь файл в памяти» можно измерить. «Переписано через генератор» можно только посмотреть глазами — и вы будете смотреть на способ вместо того, чтобы смотреть на результат. Формулировка задачи задаёт и то, как вы будете её принимать.

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

Размер задачи

Разберём теперь размер задачи — параметр, который влияет на результат сильнее формулировок.

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

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

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

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

Плохое разбиение: «сначала напиши модель, потом обработчики, потом страницу». Ни один из трёх кусков не проверяется сам по себе — работать начнёт только третий, и все ошибки первых двух вылезут разом.

Хорошее разбиение: «сначала список заказов с тремя полями, чтобы он открывался и показывал данные; потом добавим фильтр по дате; потом выгрузку». Каждый кусок работает, каждый проверяется, каждый можно принять или откатить отдельно.

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

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

Приёмы, которые решают исход

Соберём главу практических приёмов — то, что не укладывается в четыре части, но регулярно решает исход.

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

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

Приложите то, чего в коде нет. Текст ошибки целиком, а не «там ошибка». Пример входных данных. Ожидаемый вывод. Скриншот, если речь о том, как это выглядит. Всё это агент не добудет сам — а без этого будет гадать.

Скажите, чего вы уже пробовали. «Я думал, что дело в кодировке, но менял её — не помогло». Это снимает с агента целую ветку поиска и заодно говорит ему, что очевидный ответ уже проверен.

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

И отдельно — про длину поручения. Есть распространённое суеверие, что чем длиннее, тем лучше. Это не так: длинное поручение с десятью пожеланиями работает хуже короткого с четырьмя частями. Модель распределяет внимание по всему, что вы написали, и десять требований равной важности означают, что ни одно не главное.

Практический ориентир: три-пять предложений. Что, где, чем проверять, чего не трогать — и, если нужно, шаги воспроизведения. Всё, что не помещается, — либо признак, что задача крупновата, либо материал для файла правил репозитория, а не для этого конкретного поручения.

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