Маленькая задача для меня оказалась большой задачей для AI

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

Например:

Просто добавь ещё один статус заказа.

Слово «просто» здесь особенно опасное. Потому что для меня эта задача действительно может выглядеть простой.

Я уже знаю проект. Знаю, где лежит enum. Помню, как устроены переходы между статусами. Примерно представляю, нужна ли миграция. Знаю, где этот статус показывается пользователю. Помню, какие отчёты используют состояние заказа. И примерно понимаю, какие тесты могут сломаться.

В голове задача выглядит почти так:

добавить значение
    ↓
поправить пару условий
    ↓
обновить тесты
    ↓
готово

А потом я отдаю её AI. И внезапно оказывается, что задача совсем не маленькая.

«Просто добавь статус»

Представим достаточно обычную систему заказов. Есть несколько состояний:

new
processing
paid
shipped
completed
cancelled

Теперь появляется новое:

awaiting_confirmation

Если смотреть только на enum, изменение действительно смешное. Добавить одну строку. Но статус почти никогда не существует сам по себе. Он участвует в поведении системы.

И поэтому настоящий список вопросов начинает выглядеть примерно так:

где объявлены статусы
    ↓
как они сохраняются
    ↓
нужна ли миграция
    ↓
какие переходы допустимы
    ↓
где работает validation
    ↓
какие действия доступны в этом состоянии
    ↓
какие фильтры используют статусы
    ↓
какие отчёты их группируют
    ↓
что видит сотрудник
    ↓
что видит клиент
    ↓
какие события отправляются
    ↓
какие фоновые процессы зависят от состояния
    ↓
какие тесты предполагают старый набор статусов

И вот задача из одной строки неожиданно превращается в исследование половины feature. Для меня большая часть этого списка уже существует в памяти. Для AI — нет.

Я долго не замечал, сколько знаю о проекте

Наверное, это один из самых интересных эффектов работы с coding agents. Они довольно быстро показывают, как много информации опытный разработчик использует неосознанно.

Когда я вижу задачу «добавить новый статус заказа», я не проговариваю себе: «Так, сначала необходимо определить расположение enumeration, после чего изучить state transitions...» Я просто знаю, куда идти.

Открываю нужный файл. Потом ещё один. Проверяю знакомый listener. Вспоминаю, что экспорт заказов тоже использует статусы. Проверяю его.

Это происходит настолько естественно, что кажется частью самой задачи. Но на самом деле это накопленный контекст. И когда рядом появляется AI без этого контекста, разница становится очень заметной.

Одна строка кода может опираться на годы знаний

Допустим, я добавляю:

case AwaitingConfirmation = 'awaiting_confirmation';

Формально изменение занимает одну строку. Но почему я уверен, что этого недостаточно? Потому что знаю историю проекта.

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

WHERE status IN ('paid', 'shipped', 'completed')

Где-нибудь в глубине проекта. Я об этом помню. Поэтому после изменения статуса сразу иду проверять отчёты.

AI этой истории не знает. Для него enum может выглядеть единым источником истины. И это вполне логичное предположение. Просто в реальном legacy-проекте логичное предположение далеко не всегда оказывается правильным.

Иногда AI выполняет задачу слишком буквально

Я прошу:

Добавь новый статус заказа awaiting_confirmation.

AI находит enum. Добавляет значение. Ищет несколько очевидных match. Поправляет тест. Запускает проверки. Всё зелёное. Задача вроде выполнена.

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

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

Заказ обрабатывается.

А ещё один cron считает все заказы старше трёх дней в processing зависшими. Теперь часть заказов покидает processing раньше, и метрика начинает врать.

И постепенно становится понятно: AI не сделал плохую работу. Я просто дал ему маленькое предложение вместо большой задачи.

Для меня название задачи и её контекст почти слились

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

Но это существует только у меня в голове. В постановке задачи этих слов нет.

Это очень важный момент. Иногда мы говорим, что AI «не понял очевидное». Но очевидным оно было только для нас.

Разработчику внутри проекта может быть очевидно, что изменение поля требует обновить индекс Elasticsearch. Или что после изменения API нужно поправить мобильное приложение. Или что этот enum ещё используется в BI. Или что старый клиент присылает значение в другом формате.

Для человека с многолетним опытом проекта эти связи становятся практически рефлексами. AI должен сначала их найти.

Поэтому я начал осторожнее относиться к слову «маленькая»

Раньше размер задачи я довольно сильно связывал с объёмом будущего изменения. Если предполагается изменить два файла — маленькая. Если двадцать — большая.

С AI эта модель оказалась не очень полезной. Можно изменить двадцать файлов механически. Например, переименовать метод во всём проекте. Для агента такая задача может быть относительно простой. Он найдёт usages. Изменит. Запустит тесты.

А можно изменить одну строку в бизнес-логике. Но чтобы понять, какую именно строку можно безопасно изменить, нужно разобраться в нескольких модулях и понять историю системы. И это гораздо более сложная задача.

Получается странно:

много кода ≠ большая задача

мало кода ≠ маленькая задача

Размер diff и размер инженерной задачи — разные вещи.

Я бы сегодня измерял размер задачи количеством неизвестного

Например, есть задача:

Переименовать getCustomer() в customer() во всём проекте.

Изменений может быть много. Но неизвестного мало. Мы знаем: что искать; что заменить; как проверить результат.

А теперь другая:

После некоторых отмен заказ нельзя возвращать в продажу.

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

То есть кода может оказаться пять строк. А задача огромная.

Здесь особенно хорошо видно значение research phase

Именно поэтому я всё чаще не начинаю такие задачи с «реализуй». Сначала полезнее сказать:

Найди все места, где используется статус заказа.

Но даже этого может быть недостаточно. Потому что прямого использования статуса может не быть. Например, какой-то отчёт работает не со статусом, а с датой завершения. Другой модуль слушает событие перехода состояния. Третий получает данные через API.

Поэтому вопрос постепенно становится шире:

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

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

Иногда полезнее спросить AI, что я забыл

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

Какие побочные эффекты этой задачи мы могли не учесть?

Или:

Какие места проекта могут не ссылаться на enum напрямую, но зависеть от набора состояний заказа?

Или:

Представь, что новый статус уже добавлен. Где существующее поведение системы может стать неправильным?

Мне нравится такая постановка, потому что она меняет роль AI. Он перестаёт только выполнять список моих инструкций. Он начинает искать дыры в самом списке.

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

Документация внезапно становится намного важнее

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

AI просто очень быстро подсвечивает эту проблему. Например, если правило «статус awaiting_confirmation нельзя показывать клиенту напрямую» существует только как устная договорённость, модель его не обнаружит.

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

И постепенно начинаешь смотреть на документацию немного иначе. Не только как на текст для людей. А как на часть контекста проекта.

Хорошая архитектура тоже становится способом передачи контекста

То же самое происходит с кодом. Если все переходы состояний действительно собраны в одном месте, AI проще разобраться. Если права описаны централизованно — проще. Если enum действительно используется везде вместо строк — проще. Если бизнес-правила оформлены отдельными объектами, а не размазаны по controllers, templates и SQL — проще.

То есть старые разговоры про хорошую архитектуру получают ещё одно измерение. Хорошо структурированный проект легче понимать не только человеку. Его легче исследовать агенту.

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

Но нельзя просто выгрузить AI весь проект

На первый взгляд решение очевидное. Если AI не хватает контекста — дадим ему больше контекста. Пусть прочитает всё.

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

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

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

И здесь снова помогает опыт разработчика. Можно дать направление:

Посмотри state machine, события заказа, фильтры административного интерфейса и отчёты.

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

Я начал замечать собственные невидимые допущения

Наверное, это самый полезный побочный эффект. Когда AI делает что-то не так, первая реакция очень простая:

Ну это же очевидно.

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

Например:

Конечно, cancelled заказ не попадает в статистику продаж.

Почему конечно? Где это зафиксировано? И должен ли новый статус попадать туда?

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

«Маленькая задача» часто означает «знакомая задача»

Мне кажется, именно эту разницу я раньше недооценивал. Есть объективная сложность задачи. А есть моя субъективная сложность. Они могут сильно различаться.

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

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

Теперь я стараюсь формулировать не только изменение, но и область поиска

Вместо:

Добавь новый статус заказа.

я бы сейчас скорее написал:

Нужно добавить новое промежуточное состояние заказа awaiting_confirmation.

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

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

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

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

Задача стала намного длиннее. Но не потому, что я решил писать более красивые prompts. Просто теперь текст немного лучше отражает её настоящий размер.

И это меняет моё понимание сложности работы с AI

Когда coding agent ошибается в кажущейся простой задаче, легко сделать вывод: он пока недостаточно умный. Иногда это действительно так. Но иногда причина гораздо прозаичнее.

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

Получается примерно так:

для меня:
задача + несколько лет знаний о проекте
    =
очевидное решение

для AI:
задача + несколько предложений
    =
много неизвестного

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

Размер задачи измеряется не строками кода

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

Сколько в ней скрытых бизнес-правил? Насколько широко поведение размазано по проекту? Есть ли единый источник истины? Можно ли обнаружить нужные ограничения из кода? Есть ли тесты, которые описывают поведение? Насколько многое существует только в голове команды?

Иногда задача на сто строк оказывается почти механической. А изменение одной строки требует понимания половины продукта.

Поэтому моё сегодняшнее определение выглядит примерно так:

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

И чем больше я работаю с AI, тем сильнее мне кажется, что это правило относится не только к AI-разработке. Просто AI сделал его гораздо заметнее.