Как задать вашему ИИ-агенту для программирования чёткое «определение готовности»

Когда живой коллега берёт в работу расплывчатую задачу, он заполняет пробелы здравым смыслом и задаёт вопросы. ИИ-агент для программирования не делает ни того, ни другого. Он читает ваш запрос, пишет код, запускает те проверки, что может, и объявляет функцию готовой — часто без единого уточняющего вопроса. Как сказано в одном руководстве, когда вы отдаёте агенту размытые требования, «запас неопределённости не поглощается — он воплощается в код».

Именно поэтому ваше определение готовности (definition of done) — это то, что даёт наибольший рычаг из всего, что вы можете написать. В этом руководстве рассказывается, как составить его так, чтобы агент действительно мог по нему действовать.

Критерии приёмки против определения готовности

Две связанные идеи, которые стоит различать:

• Критерии приёмки (acceptance criteria) специфичны для конкретной функции: что именно должна делать эта конкретная работа, чтобы считаться корректной.
• Определение готовности (definition of done) действует на уровне всего проекта: барьеры качества, которые должно пройти каждое изменение перед выпуском — тесты, ревью, документация, отсутствие закоммиченных секретов.

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

Делайте критерии проверяемыми, а не декларативными

Проверка хорошего критерия: смог бы скрипт — или сам агент — определить, выполнен ли он? «Форма входа должна ощущаться быстрой» — непроверяемо. Перепишите это во что-то с чёткой границей:

• Отправка корректных учётных данных перенаправляет на /dashboard в течение 500 мс
• Отправка неверного пароля показывает встроенную ошибку и не уводит со страницы
• Отправка пустого поля блокируется на стороне клиента до любого сетевого запроса
• Неудачные попытки входа ограничены 5 попытками в минуту на один IP

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

Конкретный пример

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

Расплывчато:

Добавь пользователям способ сбросить пароль.

С определением готовности:

Добавь процесс сброса пароля. Готово означает:

• Эндпоинт POST /auth/reset-request принимает email и всегда возвращает 200 (никогда не раскрывать, существует ли email)
• Подписанный одноразовый токен со сроком действия 1 час отправляется по почте через существующий мейлер в src/lib/mail.ts
• POST /auth/reset-confirm проверяет токен, применяет текущую политику паролей и аннулирует токен после использования
• Тесты покрывают: успешный сброс, истёкший токен, повторно использованный токен, неизвестный email
• Никаких новых зависимостей без предварительного согласования

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

Встройте «готовность» в цикл агента

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

Поэтому не просто описывайте готовность — дайте агенту способ её проверить:

• Укажите ему команду для тестов (npm test, pytest) и скажите, что функция не готова, пока они не пройдут.
• Для того, что трудно проверить кодом — читаемость, следование существующему шаблону, — используйте проход LLM в роли судьи (LLM-as-a-judge): второй запрос, который оценивает результат по вашей планке качества. Anthropic и другие нашли этот подход эффективным для субъективных проверок.
• Держите безопасность и правило «никакого кода-заглушки/мока» в общепроектном определении готовности, чтобы оно применялось к каждому изменению, а не только к тем, о которых вы вспомнили упомянуть.

Поместите его туда, где агент его увидит

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

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