Как разбить задачу по коду для ИИ-агента
Агенту трудно безопасно выполнить просьбу перепиши модуль или добавь личный кабинет, потому что в ней смешаны решения по данным, API, интерфейсу и миграции. Декомпозиция делает каждую часть наблюдаемой: у нее есть вход, граница, проверка и понятный результат.
Что учесть до начала работы
План агента не заменяет проверку архитектуры владельцем проекта.
Не объединяйте миграцию данных, смену API и интерфейсную переработку в один неконтролируемый шаг.
Что подготовить
Что делать
Сформулируйте наблюдаемый результат
Опишите поведение пользователя или системы после изменения. Не начинайте со способа реализации, если он еще не принят как ограничение.
Результат: Задачу можно проверить по поведению, а не по количеству написанного кода.Зафиксируйте границы
Перечислите модули, интерфейсы и данные, которые входят в задачу, а также соседние части, которые менять нельзя. Отдельно укажите требования совместимости.
Результат: Агент не расширяет задачу скрытым рефакторингом.Найдите зависимости
Проверьте схемы данных, публичные API, внешние сервисы, флаги функций и порядок развертывания. Для каждого неизвестного запишите вопрос до начала правок.
Результат: Блокирующие решения обнаружены до изменения файлов.Разделите по проверяемым слоям
Выделите подготовку типов или схемы, внутреннюю логику, API, интерфейс, тесты и документацию. Один шаг должен давать небольшой связный diff и не оставлять проект заведомо сломанным.
Результат: Каждый этап можно просмотреть, проверить и отменить отдельно.Добавьте критерии приемки
Для каждого шага задайте ожидаемое поведение, тест или команду проверки. Для ошибок и пограничных случаев укажите отдельные примеры.
Результат: Завершение определяется проверкой, а не сообщением агента.Определите порядок и точки остановки
Расположите шаги по зависимостям. После изменения схемы, публичного API, прав доступа или инфраструктуры поставьте обязательную ручную проверку до продолжения.
Результат: План содержит понятные моменты для решения человека.Промпт для декомпозиции без написания кода
Разбей задачу ниже на небольшие проверяемые этапы. На этом шаге не изменяй файлы и не пиши код. Не придумывай устройство репозитория. Сначала перечисли сведения, которые нужно подтвердить. Текущее поведение: [описание]. Нужный результат: [один результат]. Входит в задачу: [границы]. Не входит и не должно меняться: [список]. Совместимость: [API, данные, версии]. Команды проверки: [команды]. Известные риски: [список]. Для каждого этапа верни: цель, предполагаемые файлы только если они подтверждены, зависимости, минимальный результат, тест или команда проверки, риск и условие остановки. Отдельно отметь изменения схемы данных, публичного API, прав доступа и инфраструктуры. В конце предложи порядок выполнения и точки ручного согласования.
Проверка плана задачи
Что чаще всего портит результат
Делить только по файлам
Разбивайте по законченному поведению и проверке, даже если шаг касается нескольких файлов.
Оставлять тесты на самый конец
Привяжите тест или команду проверки к каждому этапу.
Начинать с неизвестной архитектуры
Сначала выделите исследовательский шаг без изменений и подтвердите точки входа.
Короткие ответы
Сколько файлов должно быть в одном шаге?
Фиксированного числа нет. Важнее, чтобы diff решал одну проверяемую часть и не смешивал независимые изменения.
Нужно ли отдельно планировать рефакторинг?
Да, если он действительно нужен. Не прячьте широкий рефакторинг внутри функции с другим пользовательским результатом.
Декомпозиция кодовой задачи на проверяемые изменения
Хорошая партия для агента имеет один результат, ограниченный набор файлов и явный тест. Сначала отделите диагностику от реализации, затем опишите зависимости и точки остановки. Каждый шаг должен оставлять репозиторий в проверяемом состоянии и не требовать догадок о внешних данных.
До начала заведите контрольную таблицу: идентификатор материала, версия входа, владелец, обязательный результат, доказательство, статус и дата. Для каждой ручной правки записывайте причину, а промежуточные файлы называйте так, чтобы нельзя было перепутать черновик и принятую версию. Правило остановки тоже задается заранее: критичная ошибка в факте, правах, данных, формате или воспроизводимости возвращает работу на соответствующий этап. После приемки попросите коллегу повторить одну ключевую проверку только по переданному комплекту. Если ему нужна история личного чата или устное пояснение автора, передача еще не завершена. Такой журнал нужен не ради формальности: он показывает реальную стоимость исправлений, не дает потерять ограничение при следующем обновлении и помогает расследовать расхождение без повторения всей работы.
Контрольный сценарий от входа до приемки
Разделить материал на контрольные единицы
Подготовьте описание проблемы, ожидаемое поведение, воспроизводящий пример, архитектурный контекст, затронутые интерфейсы, ограничения совместимости, тестовые команды, риски данных и критерий приемки и разбейте материал на небольшие элементы, которые можно подтвердить отдельно. Для каждого элемента задайте идентификатор, источник, владельца и ожидаемый статус. Это не дает одной ошибке потеряться внутри общего вывода.
Обработать без скрытых исправлений
Выполните воспроизведение дефекта, построение минимальной карты зависимостей, выделение независимых шагов, назначение проверки каждому шагу, реализацию от основания к потребителю и фиксацию обнаруженных отклонений, сохраняя исходный порядок и обозначения. Если данных недостаточно, оставьте пустое поле или вопрос. Не исправляйте автоматически числа, имена, ссылки и формулировки, даже когда замена кажется очевидной.
Сверить рискованные элементы
Проверьте соответствие исходному намерению, границы изменений, обратную совместимость, миграции, обработку ошибок, тесты негативных случаев, типы, производительность, безопасность и отсутствие случайных форматных правок. Начинайте с элементов, влияющих на деньги, права, сроки, публикацию или возможность воспроизвести результат. Случайная выборка допустима только для низкорисковых повторяющихся элементов.
Передать вместе с картой контроля
Итогом служит план шагов, воспроизводящий тест, изменения по небольшим логическим группам, результаты команд, список допущений, риски отката и краткую инструкцию приемки. Приложите карту проверок, версии исходников и список исключений. Коллега должен повторить ключевую сверку без устных пояснений автора.
Граница применимости
Некоторые ошибки нельзя надежно разделить из-за общей миграции или внешней системы. Тогда граница проходит по безопасной точке восстановления, а не по числу файлов. Агент не должен сам расширять полномочия на публикацию или данные.
Критерии, которые нужно записать до начала
Что передать следующему участнику
Исполнитель получает контекст, порядок, точные команды и критерии по шагам. Ревьюер видит связь каждого изменения с тестом, открытые риски и действия, которые сознательно не выполнялись.
Ошибка, из-за которой результат выглядит надежнее, чем есть
Задачу делят по папкам, хотя рабочий результат проходит через несколько слоев, или дают шаг исправить backend без контракта и теста. Возникают формально завершенные части, которые не складываются в функцию. Делите по наблюдаемому поведению.
Коротко
Хорошая декомпозиция превращает большую просьбу в цепочку обратимых решений. У каждого шага есть цель, граница и проверка, а изменения высокого риска не проходят без человека.