Spec-Driven Development и ИИ-агенты: как внедрить единый процесс в десятилетний монолит

Spec-Driven Development и ИИ-агенты: как внедрить единый процесс в десятилетний монолит

Масштабное внедрение ИИ-инструментов в продуктовые команды неизбежно проходит через кризис роста. Простой доступ к чатам и LLM на первой ступени (L1) порождает хаос: контекст задачи размывается, код генерируется с непредсказуемыми галлюцинациями, а в компании возникают два противоречащих друг другу источника истины — документация в Confluence и реальный код в репозитории.

Опыт компании Webpractik (команда из 150 инженеров) показывает, что выход из этого хаоса заключается в переходе на фреймворк Spec-Driven Development (SDD), где спецификация в Git становится единственным источником истины для аналитиков, разработчиков, QA и ИИ-агентов.

Шкала автономности L1–L4 и концепция Dark Factory

Инженерная зрелость команд в эпоху ИИ оценивается по шкале автономности агентов:

• L1 (Интерактивный чат): Ручной проброс требований и фрагментов кода через веб-интерфейсы чатов. AI не взаимодействует с артефактами напрямую.
• L2 (Локальные агенты): Использование CLI-инструментов (Claude Code, Codex, OpenCode) непосредственно в репозитории на ноутбуке инженера (концепция «экзоскелета»).
• L3 (Автономные облачные агенты): Выполнение задач автономными агентами в облаке вне зависимости от ноутбука инженера, позволяющее снизить бас-фактор и формировать эффективные компактные команды (Tiny Teams).
• L4 (Темная фабрика / Dark Factory): Концепция сквозного производства ПО, заимствованная из японской промышленности, где ручная работа полностью вытеснена автоматическими конвейерами и проверками.

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

Выбор OpenSpec для монолитов с историей

Из существующих SDD-фреймворков (OpenSpec, SpecKit, BMAT, GSD) наиболее практичным для крупных продуктов является OpenSpec. Его главное преимущество — поддержка двух состояний контекста из коробки:

1. spec/: текущее зафиксированное состояние системы в формате As-Is.
2. changes/: отдельная папка конкретного инкремента изменений.

Для десятилетних монолитов без документации (Brownfield-проектов) это идеальное решение: нет необходимости писать документацию на весь проект сразу. База знаний spec/ наполняется итеративно по мере выполнения задач.

Структура артефактов и командный цикл OpenSpec

Каждый новый инкремент в папке changes/ содержит строго детерминированный набор артефактов, генерируемых агентами:

• proposal.md: описания намерений и бизнес-целей задачи (Intent).
• design.md: архитектурное решение (ADR) с описанием затронутых компонентов.
• tasks.md: атомарный чек-лист выполнения, позволяющий прерывать и возобновлять сессии агента без потери прогресса.
• Спецификации с критериями приемки в формате Gherkin.

Процесс управления описывается тремя базовыми командами:

# 1. Проектирование инкремента из требований и кода
openspec propose "Название фичи"

# 2. Имплементация кода агентом по чек-листу
openspec apply

# 3. Слияние проверенного инкремента в основной корпус spec/
openspec archive

Дополнительный режим explore задействуется перед генерацией для интерактивного брейншторма и прожарки архитектурной идеи.

Сквозной процесс через роли (3 Amigos) и Shift-Left QA

Главный антипаттерн SDD — внедрение фреймворка исключительно среди разработчиков. Когда спецификация создается разработчиком обособленно, возникает дублирование: аналитик пишет требования в Confluence, а разработчик создает свой вариант спек. Настоящий эффект достигается при объединении трех ролей (3 Amigos):

• Аналитик: с помощью локального агента исследует код монолита, формирует первичный proposal и проверяет спецификации.
• Разработчик: ревьюит архитектуру design.md, запускает генерацию кода командой apply и верифицирует изменения.
• Инженер QA: выполняет сдвиг качества влево (Shift-Left Quality Gate), проверяя критерии приемки до начала написания кода.

Написание end-to-end тестов передается агенту, который создает автотесты на базе критериев Gherkin, а инженер QA выступает в роли валидатора. В результате отпадает необходимость в ведении требований в Confluence — проект живет в едином Git-репозитории.

Формирование тест-плана и трассировка требований

Для предотвращения разрастания тяжелых end-to-end тестов в OpenSpec добавляется дополнительный генерируемый артефакт — тест-план. Используя спецификации инкремента, ИИ-агент распределяет проверки по всей пирамиде тестирования (юнит-тесты, компонентные тесты на фронтенде, интеграционные API-тесты и узкий слой e2e-сценариев).

Каждая проверка трассируется до конкретного критерия приемки Gherkin, утвержденного инженером QA. Это исключает галлюцинации агента при написании тестов под собственный код и обеспечивает высокую скорость выполнения тестовых прогонов в CI/CD.

Переходный период и концепция Full-Cycle инженеров

Тренды рынка указывают на стремление к созданию кросс-функциональных компактных команд (Tiny Teams) и внедрению роли Full-Cycle инженера, закрывающего весь цикл от аналитики до эксплуатации. Однако в условиях десятилетних монолитов моментальный переход приводит к просадке качества: бэкендер без опыта работы с React не может эффективно валидировать сложные UI-состояния, а фронтендер — проектировать индексы СУБД.

Решением выступает гибридный переходный период: в tasks.md задачи явно разделяются по стекам. Бэкенд-инженер и фронтенд-инженер запускают свои команды (apply back, apply front) и валидируют только свою область экспертизы в рамках единого пайплайна.

Работа с аналитиками и отучение от Confluence

Перевод системных аналитиков на работу с Git-репозиторием достигается через решение их ежедневных болей. Команда Webpractik оснастила аналитиков локальными ИИ-агентами (Claude Code, OpenCode). Аналитики получили возможность задавать вопросы непосредственно коду монолита: «какая структура таблиц используется», «какие методы API вызываются», «где определены бизнес-правила».

Для взаимодействия с внешними стейкхолдерами и клиентами, требующими документацию в Confluence по условиям контрактов, применяется специальный скилл: ИИ-агент автоматически транслирует утвержденные Git-спецификации spec/ в форматированные страницы Confluence через API, сохраняя единый источник истины в коде.

Мета-репозитории для работы с мульти-репозиториями

Если продукт состоит из нескольких монолитов (бэкенд и фронтенд) и микросервисов, создается единый мета-репозиторий. Он клонирует нужные проекты через make, хранит общий harness и спецификации OpenSpec, позволяя ИИ-агентам выполнять сквозные проверки через все слои приложения без разрыва контекста.