Агент для кода по спецификации

Этот блок объясняет, как вести агента для кода по письменной спецификации, какие части процесса действительно его держат и где процесс тратит время впустую.

Инженер Northwind просит агента «добавить частичные возвраты в админку». Через час готов pull request на 1900 строк и 47 зелёных тестов, и всё это написал агент. Заодно код возвращает доставку при частичном возврате, чего финансисты никогда не разрешали. Тесты проходят, потому что написаны с тем же неверным пониманием.

Очень буквальный подрядчик

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

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

Спецификация — это наряд для агента. Термин пока расплывчатый. Автор практического обзора этих инструментов предлагает такое определение: структурированный документ или набор документов на естественном языке, который описывает поведение и направляет агента. Вот такой документ для Northwind:

# Partial refunds in the admin panel

Why: staff can only refund whole orders, so they issue
store credit by hand for damaged items.
Who: support staff with the refunds role.

Must
R1. Staff can refund from 1 cent up to the order's remaining
    refundable total.
R2. Shipping is refundable only with a full refund.
R3. Refunds of one order can never exceed what was paid,
    even when two are submitted at the same moment.

Must not
N1. No change to the customer-facing support agent.

Done when
A1. Given order 4417 paid 34900 with 10000 already refunded,
    a refund of 24901 returns 422 and calls no payment API.
A2. Given two simultaneous refunds of 20000 on that order,
    exactly one succeeds.

Цель и границы пишете вы. Что разрешают финансисты, знаете только вы. GitHub объясняет пользу так: расплывчатый промпт заставляет модель угадывать, возможно, тысячи невысказанных требований.

Must not задаёт край работы, и всё, что за ним, можно отклонить на ревью.

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

Кто что делает на каждом этапе

В деталях Spec Kit и Kiro различаются, но форма одна: агент пишет документ, а вы проверяете его до того, как появится следующий.

Spec Kit от GitHub выполняет /speckit-specify, /speckit-plan, /speckit-tasks и /speckit-implement (названия в синтаксисе GitHub Copilot по умолчанию) после конституции с постоянными правилами, которую пишут один раз на проект. В текущем README добавлен /speckit-converge, который повторяют вместе с implement, пока он не сообщит Converged, и сказано проверять каждый результат, прежде чем идти дальше. Kiro создаёт requirements.md, design.md и tasks.md. В обоих случаях в конце появляется список отдельных задач.

Спецификация не связывает агента

Спецификация — это ещё один текст для модели. В опытах из этого обзора (сентябрь 2025 года) агент принял заметки о существующих классах за новые требования и создал дубликаты, а другие инструкции исполнял чересчур усердно. Чек-листы Spec Kit внутри файлов спецификации тоже читает ИИ, поэтому ничто не гарантирует, что их соблюдут.

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

В статье о Reflexion на задачах MBPP Python с GPT-4 16,3% решений, прошедших все собственные тесты модели, всё равно оказались неверными. На HumanEval Python таких было 1,4%. Это небольшие функции 2023 года, так что считайте цифру доказательством, что риск настоящий, а не оценкой для вашего репозитория.

Anthropic описала похожий сбой у долгих агентов: без явной просьбы Claude, как правило, отмечал фичи готовыми после юнит-тестов или curl, хотя целиком фича не работала. В веб-приложении помогла просьба проверять через автоматизацию браузера, как это сделал бы пользователь. Требования их обвязка держала в JSON-файле, где агенту было велено менять только одно поле. Вот такая запись, переписанная для Northwind:

{
  "id": "A1",
  "description": "Refund above the remaining total returns 422",
  "steps": [
    "Open order 4417 with 10000 already refunded",
    "Submit a refund of 24901",
    "Check that no payment call was made"
  ],
  "passes": false
}

JSON в Anthropic выбрали потому, что модель реже переписывает его, чем Markdown. Судя по их описанию, правило при этом было инструкцией в промпте. Ваш CI может обеспечить его на деле: сравнить файл до и после, упасть, если изменилось что-то кроме passes, и принимать true только вместе с успешной командой.

Как читать то, что вернулось

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

Когда спецификация не нужна

В том же обзоре Kiro попросили исправить мелкий баг и получили 4 user story с 16 критериями приёмки. На фиче среднего размера со Spec Kit, которую автор обзора так и не закончила, она решила, что обычная работа с ИИ заняла бы не больше времени, и предпочла бы читать код, а не такой объём Markdown. С тех пор инструменты изменились: у Spec Kit появилось отдельное расширение для багов, у Kiro есть спецификации багов и Quick Spec. Но решать всё равно вам. Спецификация окупается на фиче с неясными краями, а багу в одну строку нужен падающий тест.

Сколько спецификация живёт — отдельный выбор. В обзоре названы три уровня: spec-first использует спецификацию для текущей задачи, spec-anchored хранит её для следующих изменений фичи, а spec-as-source делает её единственным файлом, который правят люди.

Хранимую спецификацию надо поддерживать, иначе она начинает врать. Model-driven development, более старый подход с генерацией кода из формальных моделей, так и не прижился в бизнес-приложениях из-за накладных расходов и ограничений. Автор обзора задаётся вопросом, не получит ли генерация кода только из спецификаций те же минусы и вдобавок недетерминизм модели, который она видела при повторной генерации кода из одной спецификации.

Вывод

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

Глубже