Разработка, основанная на спецификациях, с ИИ-агентами-кодерами: практическое руководство
Разработка на основе спецификаций с использованием ИИ-агентов для кодирования: четырехэтапный процесс работы, файлы AGENTS.md и SPEC.md, роли многих агентов, уровни зрелости и способы выявления отклонений.
Источники: Spec-Driven Development with AI Coding Agents: The Definitive Guide
Инструменты вроде Claude Code, GitHub Copilot, Cursor и Windsurf теперь могут генерировать, реструктурировать и тестировать код гораздо быстрее, чем это сможет сделать любой человек. Однако скорость без точности часто превращается в недостаток. Многие команды, использующие эти инструменты, работают в цикле: задают запросы, получают результаты, исправляют ошибки и снова задают запросы, причем этот цикл ухудшается по мере роста кодовой базы. Обычно причина не в самой модели — дело в том, что у никого нет четкого способа указать агенту, чего именно требуется.
Разработка на основе спецификаций (SDD) — один из решений. Она рассматривает структурированную спецификацию как основной продукт процесса разработки: документ, на основе которого формируется, проверяется и контролируется код.
Концептуальные основы
Почему подход vibe coding терпит неудачу
«Кодирование на основе атмосферы» означает описание желаемого результата в разговорной форме и направление вывода с помощью неформальных уточняющих вопросов. Этот метод хорошо подходит для изолированных задач, быстрых прототипов и экспериментов, проводимых в рамках одной сессии. Однако он плохо справляется с масштабированием, и причина этого заслуживает понимания.
Ухудшение контекста
Каждая сессия происходит внутри окна контекста — ограниченного объема информации, над которой агент может размышлять за один раз. В процессе кодирования на основе атмосферы состояние проекта существует только в истории чата. По мере удлинения разговора ранние архитектурные решения, ограничения по безопасности и выбор библиотек выходят за рамки внимания агента. Затем агент заменяет их на правдоподобные альтернативы, часто не указывая на это. Это и есть ухудшение контекста.
Типичным симптомом является отклонение при реализации: постепенное расхождение между тем, что агент считает своей работой, и тем, что изначально требовало бизнеса. Код проходит тесты, работает самостоятельно и выглядит корректно, однако нарушает ранее установленные структурные или бизнес-правила. В корпоративных системах именно такие дефекты сложнее всего диагностировать и дороже всего исправлять.
Основная идея
SDD основан на одном архитектурном принципе: спецификация является основным документом, а реализация выводится из неё. Это гораздо больше, чем просто корректировка рабочего процесса. Этот подход переворачивает традиционную модель с ног на голову, при которой сначала создаётся код, а документация следует за ним.
В этом подходе спецификация является машинночитаемой, находится под контролем версий, постоянно обновляется и может выполняться. Она служит договором между намерениями человека и действиями агента, при этом агент действует в рамках установленных условий, а не делает предположения. Точный договор обеспечивает предсказуемый результат, тогда как неоднозначный приводит к различиям. Короче говоря, вы не можете контролировать то, что создаст агент, пока не определите точно, что вы хотите получить.
Шесть элементов машинночитаемой спецификации
Спецификация, предназначенная для агента, должна избавляться от неоднозначности естественного языка. Шесть элементов, обычно считаемых необходимыми для того, чтобы предотвратить нежелательные предположения со стороны агента, следующие:
- Результаты — цели, которых должно быть достигнуто в ходе работы.
- Область применения — включая то, что прямо не упоминается.
Рабочий процесс SDD
Четыре фазы с участием человека
Рабочий процесс состоит из четырех последовательных фаз, и в каждой из них есть момент, когда необходимо вмешательство человека. Эти человеческие контрольные точки не являются бюрократией. Они предотвращают усугубление ошибок дальше по процессу, а попытка пропустить одну из них ради «более быстрого продвижения» обычно приводит к обратному эффекту.
Этап 1: определение деталей. Разработчик излагает общую цель на высоком уровне, после чего либо агент, либо сам разработчик превращает её в структурированное функциональное описание: сценарии использования, бизнес-результаты, критерии приемки и четкие границы объема работ. Задача специалиста здесь — архитектурный аудит, выявление возможных ошибок, упущений и неправильных интерпретаций в полученном результате до начала любого планирования. Откладывайте этап 2 до тех пор, пока на этапе 1 не будет полной ясности: расплывчатое описание редко приводит к расплывчатой реализации, но чаще к реализации, которая кажется правильной, но на самом деле ошибочна.
Этап 2: планирование. После утверждения спецификации специалист разрабатывает технический план, в котором описываются решения по архитектуре, модели данных, контракты API и выбранные технологии. В план также включаются организационные ограничения, такие как «хранить данные в PostgreSQL» или «каждый конечный пункт API требует аутентификации JWT». Проверка человеком на этом этапе позволяет выявить архитектурные ошибки до того, как они будут внесены в тысячи строк кода.
Этап 3: разбиение задач. Утвержденный план разделяется на небольшие задачи, каждая из которых может быть протестирована независимо. Степень детализации, вероятно, является наименее оцениваемым фактором в SDD. Задача должна быть реализуемой и проверяемой за один запуск агента; если для ее выполнения агенту приходится одновременно учитывать более трех разных аспектов, она слишком крупная. Хорошо структурированный список также служит основой для разработки с тестированием на каждом этапе, поскольку у каждой задачи существуют четкие критерии успеха еще до начала работы, а проект получает частые точки проверки.
Этап 4: реализация и проверка. Агент пишет код пошагово, создавая четкие результаты, которые можно проверить и связать с конкретным требованием. На этом этапе применяется подход с использованием верификатора: один агент генерирует код, а второй агент или автоматизированный набор тестов проверяет его согласно критериям приемки.
Обновление спецификации в обоих направлениях
Одной из самых важных практик, которая часто нарушается, является двунаправленное обновление. Предположим, что на этапе 4 агент принимает решение, не описанное в спецификации, например, выбирает библиотеку по причинам производительности или решает крайний случай неочевидным способом. Это решение следует немедленно записать обратно в спецификацию.
Если этого не происходит, накапливается «долг по спецификации»: задокументированные намерения и фактическое поведение уходят друг от друга. Такое отклонение превращает динамичную спецификацию в устаревший документ, которому никто не доверяет и который в конечном итоге никто не читает; он становится бесполезным именно тогда, когда он нужен в большей степени всего — во время последующих изменений с использованием ИИ. Правило простое: когда реализация отклоняется от спецификации, необходимо обновить спецификацию сразу, а не в следующем спринте. «Долг по спецификации» растет быстрее, чем технический долг, поскольку он портит основу для работы всех последующих версий.
Артефакты персистентности и устав проекта
Почему агентам нужен устав
У агента для программирования нет памяти между сессиями. Каждая новая сессия начинается только с того, что вы вводите в его контекст. Поскольку отсутствует механизм сохранения данных, каждая сессия является чистым листом, не имеющим никакого представления о ваших стандартах безопасности, правилах номенклатуры, запрещённых библиотеках или архитектурных решениях.
«Устав проекта» — это набор постоянных файлов, решающих эту проблему. Это структурированные файлы, сохраняемые в репозитории рядом с исходным кодом, которые дают агенту необходимые знания, позволяя ему работать как член команды, обладающий информацией, а не как посторонний.
Основные файлы
AGENTS.md или CLAUDE.md — руководство по эксплуатации. Это самый важный документ: README для агента, который читают в начале каждой сессии, чтобы понять, как работает конкретный проект. Он должен быть написан с учётом возможности обработки компьютером, а не с учётом читаемости для человека. Эффективный файл содержит три вида информации:
- Подробности работы, которые агент не может определить самостоятельно: точные команды сборки с флагами, способ запуска тестов, настройки инструмента проверки кода и названия переменных окружения.
- Правила нумерации и структуры: для чего предназначен каждый каталог, как называются файлы и как организованы модули.
.env и не меняйте логику аутентификации без предварительного рассмотрения.SPEC.md — живое описание спецификаций. Это авторитетное описание того, что должен делать система. Это не исторический отчет. Он отражает текущее желаемое поведение, включая все решения, принятые в процессе реализации. Если код отклоняется от SPEC.md, файл обновляется, а при изменении требований сначала редактируется SPEC.md, а затем следует реализация.
PLAN.md — документ архитектуры. В нем записываются архитектурные решения, технологические выборы и ограничения всей системы. Он отвечает на вопрос «почему всё построено именно так?», предоставляя обоснования, которые помогают последующим агентам и инженерам не отменять тщательно продуманные решения.
Файлы конфигурации для конкретных инструментов. У каждого инструмента есть свои правила формирования файлов с правилами. Следует упомянуть формат .mdc от Cursor, поскольку он сочетает Markdown с YAML-метаданными для привязки правил к шаблонам имён файлов. Таким образом, правила бэкенда, такие как требования к аутентификации и схемы доступа к базе данных, применяются только тогда, когда агент работает с файлами бэкенда, что позволяет исключить нерелевантную информацию из его рабочей памяти во время работы с фронтендом.
Оркестрация множества агентов
Почему одного агента недостаточно
Один агент, отвечающий за весь кодовый базис предприятия, сталкивается с серьезным ограничением — окном контекста. Крупная система с 100 000 и более файлами, несколькими сервисами, сложными потоками данных и полным набором тестов не может вместиться в контекст одного агента. Агенту приходится выбирать, что включить, и эти выборы создают «слепые зоны».
Идея оркестрации с использованием нескольких агентов заключается в имитации работы сильной команды людей с четко определенными ролями, организованной передачей задач и единой спецификацией, которую все считают истиной.
Три роли
Координатор. Этот агент выполняет функции менеджера проекта и архитектора. Он имеет полную картину ситуации, то есть знает полные спецификации, список задач и архитектурные ограничения. Он разделяет спецификации на подспецификации, передает их исполнителям, отслеживает конфликты между параллельными рабочими потоками и следит за тем, чтобы выполнение одной задачи не негативно сказалось на всей архитектуре.
Исполнитель. Исполнители — это специалисты. Каждый из них получает подспецификацию, охватывающую одну задачу или небольшую группу связанных задач, и работает в изолированной рабочей деревушке Git, чтобы не возникало конфликтов на уровне файлов с другими исполнителями, работающими параллельно. Он ничего не знает о работе вне своего задания и не несет за нее ответственности. Такая изоляция не является ограничением — именно она делает результат работы детерминированным, поддающимся тестированию и проверке.
Проверщик. У проверщика противоположная цель: в то время как реализатор стремится завершить задачу, проверщик пытается выявить моменты, когда результат не соответствует спецификации. Такая схема взаимодействия заимствована из формальной верификации и исследований в области безопасности и является одним из самых эффективных механизмов контроля качества, предлагаемых SDD. Проверщик тестирует результаты на соответствие критериям приемки и ищет функциональные недостатки, нарушения правил безопасности, превышение ограничений по производительности и отклонения от спецификации. Обнаружив несоответствие, он не вносит исправления в код, а сообщает координатору структурированный отчет с описанием проблемы и указанием конкретного требования, которое было нарушено.
Для производственных систем такой адверсарий-проверщик не должен быть факультативным. Агент, который пишет и проверяет собственный код, почти всегда будет считать свою работу приемлемой, а ценность проверщика заключается в его независимости от исполнителя и противостоянии ему.
Параллельная обработка с рабочими деревьями
Одной из самых ценных особенностей многопроцессных SDD является параллелизм: несколько исполнителей одновременно работают над разными функциями или сервисами, каждый в своем собственном рабочем дереве. Для крупных проектов с небольшим количеством зависимостей между задачами время выполнения может значительно сократиться.
Git-рабочие деревья позволяют это реализовать. У каждого агента есть отдельная рабочая директория, привязанная к тому же репозиторию, что позволяет избегать конфликтов файлов, в то время как координатор отслеживает прогресс всех рабочих потоков с одного места. После одобрения проверщиком координатор сливает готовые рабочие деревья, сохраняя основную ветку в чистоте.
Диаграммы как код
Почему диаграммы должны присутствовать в спецификации
Архитектурные диаграммы традиционно создавались уже после написания кода в качестве его документации. В подходе SDD они формируются на раннем этапе, являясь частью спецификации и плана, ещё до начала любой реализации.
Причина заключается в диагностике. Требование к агенту сгенерировать корректную диаграмму Mermaid на основе спецификации заставляет его явно анализировать потоки данных, зависимости между сервисами и переходы состояний перед написанием кода. Некачественная или несогласованная диаграмма на этом этапе — надёжный признак неоднозначности или структурных ошибок в спецификации, и устранение таких проблем в диаграмме стоит гораздо дешевле, чем в уже развернутом коде.
Форматы
Форматы на основе текста, в частности Mermaid и D2, превосходят двоичные изображения для этой цели. Их можно версионировать и сравнивать изменения, а агенты могут читать их напрямую. Их также можно обновлять по мере развития спецификаций, что позволяет документацию структуры и реализацию держать в соответствии.
Три уровня зрелости
Эксперты выделили три уровня SDD. Это не лестница, по которой каждая команда должна подниматься в определенном порядке. Это разные профили компромиссов для разных ситуаций, и понимание того, какой из них подходит вашей ситуации, важно еще до начала внедрения.
Уровень 1: сначала спецификация. Для каждой задачи составляется подробная спецификация. После завершения реализации и её проверки спецификация считается временной: её можно сохранить для справки, но дальнейшее обслуживание не требуется. Этот подход подходит для изолированных функций, одноразовых миграций и экспериментов, когда поддержка по уровню 2 не оправдана. Сторонники этого подхода утверждают, что он позволяет сохранить примерно 60% ценности SDD при значительно меньших затратах, что делает его разумной отправной точкой для новичков. Используйте его для ограниченной новой функции с чёткими критериями принятия, без зависимостей между сервисами, при этом сроки реализации измеряются днями.
Уровень 2, основанный на спецификации (рекомендуемый стандарт). Спецификация является равноправным партнером кода на протяжении всего срока существования проекта, и оба элемента поддерживаются. Когда меняются требования, сначала изменяется спецификация, а когда реализация отклоняется, спецификация немедленно обновляется, чтобы зафиксировать реальное поведение и обоснование изменений. Это может показаться двойной работой по поддержке, но на практике это снижает общие затраты: это предотвращает ухудшение качества в ходе различных этапов работы, позволяет новым участникам команды (людям и ИИ) эффективно интегрироваться и делает последующие изменения с использованием ИИ гораздо надежнее. Это базовый подход для производственных систем, командных проектов и всего, что предполагает постоянное развитие.
Уровень 3, спецификация как исходный код (экспериментальный). Спецификация является единственным основным документом. Код рассматривается как скомпилированный результат, генерируемый по требованию и никогда не редактируемый вручную. Это теоретический конечный этап подхода SDD, при котором инженеры занимаются поддержкой спецификаций, а ИИ — реализацией. У этого подхода есть нерешенная проблема — детерминизм. Одинаковые спецификации могут приводить к синтаксически различному, но функционально эквивалентному коду при каждой запуске, что значительно затрудняет сравнение версий, отладку и проверку. Считайте его экспериментальным решением. Он может подойти для проектов с нуля с высоко полными спецификациями, строгим управлением с помощью ИИ и терпимостью к незрелым инструментам, однако на 2026 год он не рекомендуется для критически важных производственных систем.
Руководства по ролям
Инженеры и архитекторы
Основной навык инженера смещается в сторону инжиниринга контекста. Правильное формирование синтаксиса — задача, которую агенты выполняют с машинной скоростью, поэтому ценность инженера заключается в определении точного архитектурного контекста, отборе информации, доступной для агента, и проверке того, чтобы его результаты соответствовали структурным целям системы. Это включает в себя создание качественных файлов AGENTS.md и SPEC.md, установление правил управления библиотеками (чёткий список разрешённых и запрещённых зависимостей), формулировку требований к безопасности и соответствию стандартам в формате, понятном машинам, а также структурирование задач так, чтобы различные аспекты оставались разделёнными.
Рекомендуемая процедура для инженеров:
- Перед разработкой любой функции с использованием ИИ создайте или обновите файл SPEC.md, чтобы в нём были указаны шесть элементов, описанных ранее.
- Проверьте файл AGENTS.md и убедитесь, что команды сборки, шаблоны тестирования, правила нумерации и иерархия степени серьёзности по-прежнему соответствуют действительности.
Блок ограничений — это удобный шаблон, который можно включить в любую спецификацию. В нём перечисляются технологический стек (все необходимые технологии), запрещённые библиотеки (с указанием названий), требования к безопасности (способы аутентификации пользователей, ожидаемый уровень шифрования, правила обработки данных), ограничения по производительности (целевая задержка и пропускная способность), требования к тестированию (порог покрытия и типы необходимых тестов), а также архитектурные паттерны (те, которые обязательны, и те, которых следует избегать).
Технические менеджеры продукта
От документов требований к продукту до описаний поведения системы. В классическом документе требований к продукту предполагается, что его будут читать инженеры-люди, обсуждать его и реализовывать, опираясь на собственный усмотрение. В подходе SDD результаты работы TPM должны представлять собой описание поведения системы: машинночитаемый отчет о том, как продукт должен реагировать на конкретные потребности пользователей, с указанием точных требований к выполнению действий агентом.
Разница касается не только стиля изложения. В документе требований к продукту может быть сказано «улучшить процесс оформления заказа». Описание поведения системы же должно указывать, что делает текущий процесс оформления заказа, какие проблемы у пользователей он вызывает, какие изменения в поведении считаются улучшениями, как оценивается успех, какие крайние случаи необходимо учитывать и что система ни в коем случае не должна делать.
Цикл прототипирования. Технология SDD позволяет TPM сократить обычный процесс передачи проекта от дизайнера к инженерам. Вместо ожидания макетов от дизайнера и их последующей реализации инженером TPM может создавать интерактивные прототипы непосредственно на основе описания поведения и оценивать рабочую функциональность, а не статические экраны. Если прототип не соответствует замыслу, спецификация обновляется, и система генерирует новую реализацию, так что цикл обратной связи основан на спецификации, а не на коде. Это устраняет несколько этапов передачи информации (PRD, затем передача проекта дизайнеру, затем инженерам), на которых часто теряется первоначальная цель.
Генеральные директора по технологиям и руководители инженерных отделов
Управление. Для технического директора в организации, ориентированной на агентов, приоритетом является система управления, позволяющая искусственному интеллекту ускорять процесс реализации без ущерба для качества, безопасности или соответствия стандартам. SDD обеспечивает слой контроля, но только при наличии организационной дисциплины. На крупном масштабе важны три механизма:
- Контроль версий спецификаций. Файлы SPEC.md, PLAN.md и AGENTS.md хранятся в том же репозитории, что и код, и проходят ту же процедуру проверки и утверждения.
- Хроники аудита. Каждая изменение, сделанное с помощью искусственного интеллекта, должно быть связано с конкретным требованием спецификации, что является обязательным в регулируемых отраслях.
- Участие людей на каждом этапе перехода. Ничто не может автономно перейти от этапа определения требований к этапу планирования и далее к реализации без утверждения на каждом шагу.
Технические директора также должны оценивать инструменты программирования на основе ИИ с учётом этой модели, проверяя, насколько хорошо каждый из них поддерживает постоянные файлы правил, процедуры проверки, возможности отслеживания и рабочие процессы с участием нескольких агентов.
Оценка результата. Организации, внедряющие SDD, часто отмечают, что в течение первых двух–четырёх недель разработка кажется более медленной, поскольку инженеры тратят время на составление спецификаций вместо того, чтобы сразу приступать к кодированию. Это наблюдение верно, но его интерпретация вводит в заблуждение. Работа над спецификациями — это не новая дополнительная нагрузка. Раньше такая работа выполнялась неформально, непоследовательно и после реализации, когда она стоила больше всего. Показатели, отражающие реальную отдачу, находятся на более поздних этапах:
- время от сформулирования требований до готового к использованию кода, то есть кода, прошедшего проверку, ревью и развертывание, а не просто написанного,
- Процент переработки — доля готовых функций, которые необходимо пересоздать из-за неправильного понимания требований,
- Время восстановления контекста — время, необходимое разработчику или агенту, чтобы снова стать продуктивным при работе с кодом, в котором не было изменений в течение 30 дней, и
- Уровень ускользания дефектов — доля дефектов, обнаруженных во время проверки спецификации, по сравнению с моментом их обнаружения после развертывания.
По сообщениям, команды, применяющие зрелые практики SDD, видят снижение объема переработки на 40–60%, а время восстановления контекста значительно сокращается, поскольку спецификация предоставляет необходимую информацию, без которой на поиск решений уходили бы часы работы над кодом. Эти цифры основаны на отчетах практиков, а не на контролируемых исследованиях, поэтому измеряйте свои собственные показатели в качестве базы.
Смещение целей
Что это такое
Отклонение намерений — это постепенное расхождение между первоначальными требованиями бизнеса и поведением кода в производственной среде. Это явление не является новым для работы с помощью ИИ и относится к одной из старейших проблем инженерии программного обеспечения, однако агенты для программирования усугубляют ситуацию. Они оптимизируют код с учетом вероятности его корректной работы и прохождения тестов, а не с учетом соответствия бизнес-требованиям. Если попросить их разработать систему обработки платежей, они напишут код, проходящий все тесты и охватывающий все указанные случаи. Если спецификация неполная или устаревшая, агент заполняет пробелы статистически вероятными значениями по умолчанию из своих данных обучения. Такой подход подходит для универсальных систем, но может привести к катастрофическим последствиям для конкретных бизнес-правил. Самое опасное отклонение — это то, которое замечается лишь тогда, когда оно стоит клиента денег, приводит к аудиту соответствия или инциденту в производстве, поскольку агенты очень хорошо умеют создавать код, который на первый взгляд кажется корректным, но на самом деле имеет скрытые ошибки.
Механизмы защиты
- Живое описание спецификации. Первый механизм защиты — это спецификация, которая обновляется в реальном времени по мере принятия решений. Любое отклонение от SPEC.md, каким бы незначительным или обоснованным оно ни было, немедленно фиксируется, так что файл всегда отражает текущее поведение, а не первоначальные намерения.
- Проверка с учётом атак. Модель проверки одновременно служит для обнаружения отклонений. Сравнение результата выполнения задачи со спецификацией позволяет выявить отклонения на самом раннем этапе, до того как они накопятся за несколько циклов реализации.
- Отслеживание степени покрытия спецификации. Более сложные решения включают отслеживание доли требований, для которых существуют автоматизированные, проверяемые тесты. Требование без теста может оставаться незамеченным, а стремление к полному покрытию представляет собой подход тест-ориентированного разработчества на уровне требований.
Минимальный вариант AGENTS.md
Готовый к использованию AGENTS.md может быть коротким. Как минимум он должен содержать описание проекта в одном абзаце, точные команды для сборки, тестирования и проверки кода, правила именования и структуры каталогов, списки «всегда», «сначала спросите» и «никогда», ссылки на SPEC.md и PLAN.md, а также правила управления библиотекой. Адаптируйте каждую часть под свою технологическую стек и требования организации.
Что это дает вам
Разработка на основе спецификаций — это не временная мода или незначительное улучшение существующих практик. Она меняет суть инженерной работы. С помощью кодирующих агентов узким местом в процессе создания продукта больше не является скорость формирования синтаксиса, а точность определения целей. Спецификация — это продукт, код — его реализация, и при создании программ с использованием агентов спецификация является самым важным результатом работы инженера.
Связанные материалы
- Практические заметки: я запускаю ИИ-агента для программирования локально, и его производительность почти в два раза выше — Подробное руководство по практическим заметкам: я запускаю ИИ-агента для программирования локально, и его производительность почти в два раза выше: контракты, проверки и блоки кода для команд, использующих эту модель.
- Инженерия на основе агентов в пяти слоях: от спецификаций и параллельных агентов до правил и надзора — Карпати описал смену подхода от традиционного программирования. Рассмотрены пять слоев инженерии на основе агентов: спецификации, оркестрация, кодифицированные правила, человеческий контроль и возможности мониторинга, а также план на неделю.