Примеры запросов

Частые задачи и то, как их сформулировать агенту. Приёмы, которые за ними стоят, разобраны в Лучших практиках и Подходах к разработке. Короткие формулировки собраны по типам задач, развёрнутые многострочные примеры в разделе Большие запросы.

Из чего состоит хороший запрос

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

Часть	Зачем	Пример формулировки
Место	Чтобы агент не читал полпроекта	«в export/stream.py, особенно буферизация»
Ограничения	Чтобы правка не расползлась	«без новых зависимостей, публичный интерфейс не меняй»
Образец	Чтобы результат совпал с принятым в проекте	«по образцу pages/settings.tsx»
Критерий готовности	Чтобы агент проверил себя сам	«после правки прогони make test и покажи вывод»

Сравни: «почини выгрузку» против «выгрузка CSV обрывается на файлах больше 50 МБ. посмотри export/stream.py, особенно буферизацию. сначала воспроизведи падающим тестом, потом устрани причину».

Разобраться в проекте

• «проведи меня по проекту: с чего начинается входящий запрос, через какие слои проходит и где заканчивается. если есть архитектура, набросай схему».
• «объясни, за что отвечает internal/billing/, и покажи, кто его вызывает».
• «субагентом изучи, как в проекте устроена авторизация, и верни краткий итог: где точка входа, какие роли, где хранятся сессии».

Понять код

• «что делает retryWithBackoff и откуда его вызывают? покажи цепочку до внешнего вызова».
• «если удалить withRetry, что сломается? проверь по вызовам, а не по имени».
• «почему здесь блокирующий вызов, а не очередь? посмотри историю изменений этого файла и объясни, как так вышло».

Отладка

• «стрим обрывается на длинных ответах. сначала воспроизведи это падающим тестом в stream/, потом устрани причину, а не глуши исключение».
• «test_pricing.py покраснел после последнего коммита. найди изменение, которое его сломало, и почини, не трогая сам тест».
• «вот трассировка ошибки [вставь]. найди место в коде, объясни условие, при котором это происходит, и предложи исправление. пока ничего не меняй».

Тесты

• «напиши падающий тест на баг из задачи #142: пользователь без прав видит чужой заказ. покажи, что он красный, потом сделай зелёным».
• «покрой orders.go тестами на отмену оплаченного заказа и повторную отмену; без моков, через тестовую транзакцию».
• «проверь, что тесты в test_auth.py проверяют поведение, а не реализацию. где тест сломается от безобидного рефакторинга, перепиши».

Рефакторинг

• «в pages/settings.tsx форма сделана с валидацией и разбита на секции. повтори эту структуру для страницы профиля, поведение существующих форм не меняй, тесты держи зелёными».
• «вынеси повторяющуюся пагинацию из трёх обработчиков в общий хелпер; поведение прежнее, тесты должны проходить».
• «пройди по диффу ветки и убери лишнее: интерфейсы с одной реализацией, обёртки без логики, комментарии, повторяющие код».

Производительность

Здесь важно назвать, чем меряем, иначе агент оптимизирует наугад.

• «make bench печатает время сборки. сейчас 94 секунды. ускорь до 60, меняй только конфигурацию сборки, после каждой правки прогоняй бенчмарк и покажи числа».
• «эндпоинт /v1/reports отвечает за 2.4 с на данных из fixtures/large.json. найди, где уходит время, покажи замеры до и после, поведение не меняй».
• «прогони цикл экспериментов: правь только src/parser.rs, метрика это вывод ./bench.sh, оставляй изменение, только если оно лучше базы больше чем на разброс, остальное откатывай».

Развёрнуто про такой цикл в разделе Autoresearch.

Внешние библиотеки

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

Интерфейс

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

Массовые правки

Сначала на двух файлах, потом на всех: так дешевле поймать неудачную формулировку.

• «в src/api/ двенадцать обработчиков возвращают ошибки по-разному. приведи к формату из handlers/orders.go. начни с двух файлов, покажи дифф, дальше продолжим».
• «собери список файлов, где ещё используется старый клиент логирования, и выведи его в todo.txt. пока ничего не меняй».

Ревью

• «свежим субагентом проверь дифф этой ветки против SPEC.md: все ли пункты реализованы, покрыты ли крайние случаи тестами, не затронут ли чужой код. только расхождения, без придирок к стилю».
• «пройди по моей последней правке и найди крайние случаи и гонки, которые я мог упустить; на каждый покажи строку и как воспроизвести».
• «посмотри дифф глазами человека, который будет это поддерживать через год: что окажется непонятным, где не хватает названия или пояснения про причину».

Git и PR

• «собери коммит из добавленного в индекс, сообщение по сути изменений; затем открой PR через gh и вставь в описание чеклист из SPEC.md».
• «покажи, чем эта ветка отличается от main, и напиши описание PR: что изменилось и почему».

Постановка задачи

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

Большие запросы

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

Разбор большой правки перед началом:

Контекст: сервис выставления счетов, вход в `internal/billing/`, деньги хранятся
в копейках целым числом, округление вниз. Тесты гоняются `make test`, линтер `make lint`.

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

Ограничения: новых зависимостей не добавлять, публичные интерфейсы
`OrderService` не менять, схему БД трогать можно только миграцией.

Порядок: сначала прочитай `internal/billing/` и покажи, где сейчас проходит
оплата и где ведётся история операций. Дальше предложи план и остановись,
я его проверю. Код пишем после того, как я подтвержу.

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

Прогон по спецификации в новой сессии:

Прочитай SPEC.md и реализуй раздел «Частичный возврат».

Правила: на каждый пункт критериев приёмки сначала падающий тест, потом код.
Файлы вне `internal/billing/` и `migrations/` не трогай. Если спецификация
чего-то не покрывает, не додумывай: остановись и спроси.

Готово это когда: `make test` и `make lint` зелёные, каждый пункт критериев
закрыт тестом, и ты показал вывод обеих команд.

В конце дай список: пункт спецификации, тест, который его проверяет.

Разбор инцидента с приложенными данными:

[вставь трассировку]
[вставь фрагмент лога за минуту до]

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

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

Пока ничего не меняй.

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

Чего лучше избегать

Формулировка	Что с ней не так
«сделай красиво»	Нет критерия, агент остановится на первом правдоподобном варианте
«изучи проект»	Прочитает сотни файлов и забьёт контекст
«почини тесты»	Может «починить» их правкой самих тестов
«оптимизируй код»	Без метрики оптимизация превращается во вкусовщину
«доделай остальное»	Объём не определён, дифф будет непредсказуемым