Цикл работы с агентом

Info

Все, чего агент не знает и о чем не спросил, он додумает — и продолжит работу так, будто это факт. Цикл ниже нужен ровно для того, чтобы додумывать было нечего.

Цикл состоит из пяти шагов. У каждого перехода есть проверка: пока она не пройдена, переходить к следующему шагу рано.

Шаг	Что делаете вы	Проверка перехода
1. Контекст	рассказываете задачу целиком	—
2. Уточнение	агент задает вопросы	не осталось открытых вопросов, влияющих на объем работы, поведение системы или совместимость
3. Исследование	агент проверяет утверждения по коду	каждое утверждение подтверждено файлом и строкой
4. План	агент описывает результат и шаги	в плане названы границы задачи и способ проверки результата
5. Выполнение	агент реализует и проверяет	проверка выполнена и показана, а не заявлена словами

Коротко

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

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

2. Уточнение.

Прежде чем что-то делать, задай мне вопросы по всему, что осталось неоднозначным:
по объему работы, по поведению в пограничных случаях, по совместимости.
Не спрашивай очевидное — спрашивай о том, что я мог не учесть.

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

3. Исследование.

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

В ответ приходят факты со ссылками вида путь/файл.go:120. Утверждение без ссылки — повод не доверять ему.

4. План.

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

В ответ приходит план, где явно названы границы и команда проверки. Если этих двух пунктов нет — просите дописать, не переходя к реализации.

5. Выполнение.

Запусти проверку и приведи вывод команды. Не описывай результат словами.

В ответ приходит вывод команды. Фраза «все работает» без вывода результатом не является.

Если работа ушла не туда:

Остановись. Не продолжай реализацию — вернись к плану и объясни,
какое место плана привело к этим изменениям.

Шаг 1. Контекст

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

Не сокращайте описание до формулировки в одну строку. На этом шаге ценна полнота, а не аккуратность: агент лучше восстановит структуру из подробного рассказа, чем додумает недостающее из краткого.

Обязательно скажите то, чего нет в коде:

• какое поведение считается правильным с точки зрения продукта;
• какие решения уже приняты и пересматривать их не нужно;
• что находится в зоне ответственности другой команды.

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

Шаг 2. Уточнение

Попросите агента задать уточняющие вопросы до того, как он примется за работу.

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

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

Шаг 3. Исследование

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

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

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

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

Для исследования удобен режим Plan: агент читает код и ищет, но не меняет файлы. Подробнее — в разделе Агенты и субагенты.

Шаг 4. План

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

• цель — что изменится с точки зрения пользователя или системы;
• затронутые файлы и интерфейсы — названные явно;
• границы задачи — что агент сознательно не трогает;
• критерии приемки — по каким признакам работа считается выполненной;
• способ проверки — какой командой или сценарием это подтверждается.

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

Достаточно одной строки: «меняем только сервис заказов; схему базы, соседние сервисы и настройки CI не трогаем».

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

Шаг 5. Выполнение и проверка

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

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

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

Как это выглядит на одной задаче

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

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

Шаг 2. Уточнение. Агент спрашивает: отклонять весь заказ или только конфликтующие позиции; что делать с уже созданными заказами в базе; нужен ли отдельный код ошибки или подойдет существующий. Вы отвечаете: отклонять весь заказ, старые не трогаем, код ошибки существующий.

Первый вопрос — как раз тот случай, о котором вы не подумали: без ответа агент выбрал бы вариант сам.

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

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

Шаг 5. Выполнение. Агент добавляет проверку и тест, запускает go test ./services/orders/... и приводит вывод. Вы видите, что новый тест проходит, а старые не сломались.

Заметьте, что содержательная работа сделана на шагах 2 и 4: именно там решилось, что заказ отклоняется целиком и что API не меняется. Без них агент дошел бы до готового кода — просто не того.

Когда цикл не нужен

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

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

Типичные ошибки

1. Задача поставлена одной строкой, а ожидания — на страницу. Все, что осталось в голове, агент заменит собственными допущениями.
2. Пропущен шаг уточнения. Вопросы все равно возникнут, но уже в виде переделки.
3. Не названы границы задачи. Агент добавит то, о чем не просили, и это придется вычищать вручную.
4. Проверка заменена утверждением «готово». Требуйте вывод команды, а не отчет о ней.
5. Ревью без условия остановки. Каждый новый круг проверки почти всегда что-нибудь находит — это свойство самой просьбы проверить, а не признак проблем в коде. Договоритесь заранее: следующий круг запускается, только если предыдущий нашел существенный дефект.

Что дальше

1. Закрепите повторяющиеся шаги цикла в навыках, чтобы не повторять инструкции в каждом диалоге.
2. Разберитесь, как режимы Plan и Build и субагенты помогают удерживать цикл, — Агенты и субагенты.
3. Узнайте, почему длинный диалог теряет точность, — Контекст.