Spec-Driven Development: как GitHub Spec Kit меняет разработку с ИИ-агентами

Тот момент, когда ИИ-агенты превращают ваш код в свалку

Вы даете агенту простую задачу: "Добавь авторизацию в API". Через час получаете три разных реализации JWT, два варианта сессий, четыре способа хранения токенов и пять конфигурационных файлов, которые конфликтуют друг с другом. Знакомо? Это не ошибка агента. Это ваша ошибка.

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

GitHub Spec Kit: контракт вместо просьбы

Spec Kit — это набор спецификаций в формате YAML, которые живут прямо в вашем репозитории. Файлы с расширением .spec.yml. Они описывают не то, ЧТО должно быть сделано, а КАК это должно быть сделано.

Разница фундаментальна. Просьба "добавь логгирование" превращается в контракт:

logging:
  format: json
  level: INFO
  output: stdout
  timestamp_format: ISO8601
  context_fields: [user_id, request_id, session_id]
  excluded_paths: [/health, /metrics]
  buffer_size: 1000
  flush_interval: 30s

Агент больше не гадает. Он выполняет контракт. Точка.

Шесть этапов, которые меняют всё

Spec-Driven Development работает по простой, но жестоко эффективной схеме. Пропустите один этап — получите проблемы. Выполните все шесть — получите предсказуемый результат.

1 Архитектурные принципы

Создайте файл architecture.spec.yml в корне проекта. Здесь вы описываете правила игры. Не технические детали, а философию.

architecture:
  style: microservices
  communication: message_broker
  database_per_service: true
  api_gateway: required
  service_discovery: dynamic
  
  constraints:
    max_service_size: 1000 LOC
    max_dependencies: 15
    testing_coverage: 80%
    
  patterns:
    - circuit_breaker
    - retry_with_backoff
    - bulkhead
    
  anti_patterns:
    - god_object
    - spaghetti_code
    - tight_coupling

Это не документ для чтения. Это файл для исполнения. Агент проверяет каждый генерируемый код на соответствие этим принципам. Нарушил? Переделывай.

2 Спецификации компонентов

Каждый компонент системы получает свой .spec.yml файл. API эндпоинты, базы данных, очереди сообщений, кэши.

# api/users.spec.yml
endpoints:
  - path: /users
    method: GET
    auth: required
    permissions: [admin, manager]
    pagination: true
    filters: [status, created_after]
    sort: [created_at, name]
    
  - path: /users/{id}
    method: PUT
    validation:
      required: [name, email]
      rules:
        email: email_format
        name: min_length=2, max_length=100
    
error_responses:
  - code: 400
    format: {error: string, details: object}
  - code: 404
    format: {error: string, resource: string}

3 Генерация кода по спецификации

Теперь вы даете агенту не задачу, а ссылку на спецификацию. Вместо "создай эндпоинт для пользователей" пишете:

# Инструкция для ИИ-агента
Используй спецификацию из api/users.spec.yml
Сгенерируй код для всех endpoint'ов
Соблюдай архитектурные принципы из architecture.spec.yml
Добавь тесты с покрытием 80%

Агент становится исполнителем, а не архитектором. И это хорошо. Потому что архитектор — это вы.

4 Валидация против дрейфа

Самый опасный момент в работе с ИИ-агентами — дрейф кода. Сегодня агент генерирует код в одном стиле, завтра — в другом. Через неделю у вас микс из пяти разных подходов.

Spec Kit решает это через автоматическую валидацию. GitHub Action проверяет каждый PR:

name: Validate Spec Compliance
on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate against specs
        uses: github/spec-kit-validate@v1
        with:
          spec_paths: '**/*.spec.yml'

Код не соответствует спецификации? PR не мержится. Жестко? Да. Эффективно? Еще бы.

5 Эволюция спецификаций

Спецификации — не догма. Они живут и меняются. Но меняются осознанно, а не случайно.

Когда вам нужно изменить подход к логгированию во всем проекте, вы:

1. Меняете logging.spec.yml
2. Запускаете скрипт обновления кода
3. Агенты перегенерируют код по новой спецификации
4. Валидация проверяет, что всё ок

Консистентность сохраняется. Даже при масштабных изменениях.

6 Документация как побочный эффект

Спецификации — это уже документация. Только живая. Она всегда актуальна, потому что код не скомпилируется, если не соответствует spec.

Генерируйте API документацию, диаграммы последовательностей, диаграммы компонентов — всё из тех же .spec.yml файлов.

Как НЕ надо использовать Spec Kit (ошибки, которые сломают ваш процесс)

Реальный пример: от хаоса к порядку за 3 дня

Команда из 5 разработчиков + 3 ИИ-агента. Проект: SaaS платформа с 30 микросервисами. Проблема: каждый агент генерировал код по-своему. Результат: 4 разных подхода к ошибкам, 3 стиля логгирования, 5 вариантов конфигурации.

День 1: Создали architecture.spec.yml с базовыми принципами. Не идеально, но достаточно, чтобы остановить хаос.

День 2: Добавили спецификации для API (формат ошибок, пагинация, валидация). Агенты начали генерировать консистентный код.

День 3: Настроили валидацию в CI/CD. Теперь код, не соответствующий spec, даже не доходил до ревью.

Результат? Время на ревью снизилось на 70%. Качество кода выросло. Разработчики перестали тратить время на выравнивание стилей.

Интеграция с существующими практиками

Spec-Driven Development не заменяет ваши текущие процессы. Он встраивается в них.

Уже используете AGENTS.md? Отлично. Spec Kit дополняет его. AGENTS.md говорит "как работать с проектом", а .spec.yml говорит "какой код создавать".

Есть Context7 MCP для работы с документацией? Подключите спецификации как источник контекста. Теперь агент видит не только документацию, но и стандарты кодирования.

Работаете с Kaggle по AI-агентам? Spec Kit — это следующий уровень. После того как вы научились строить агентов, научитесь управлять их выводом.

Начало работы: минимальный жизнеспособный Spec Kit

Не пытайтесь описать всю систему сразу. Начните с самого больного места.

1. Выберите компонент, который агенты чаще всего ломают (у многих это error handling)
2. Создайте errors.spec.yml с форматом ошибок, кодами, структурой
3. Обновите инструкции агентам: "Все ошибки должны соответствовать errors.spec.yml"
4. Настройте простую валидацию (можно даже скриптом на Python)
5. Замерьте результаты через неделю

Через месяц у вас будет 5-10 спецификаций, которые покрывают 80% проблем. Остальные 20% можно решать ad-hoc.

Спецификации для разных типов агентов

Не все агенты одинаковы. И не все спецификации должны быть одинаковыми.

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

Что дальше? Spec-Driven Development 2.0

Текущая реализация Spec Kit — только начало. Вот что будет дальше (и вы можете начать это делать уже сейчас):

• Динамические спецификации: spec, которые меняются в зависимости от контекста. Для high-load сервисов — одни правила, для админки — другие
• Спецификации через естественный язык: вы описываете требования на русском, система генерирует .spec.yml
• Обратная связь в реальном времени: агент предлагает улучшения спецификаций на основе генерации кода
• Спецификации для инфраструктуры: то же самое, но для Terraform, Docker, Kubernetes (представляете, агенты, которые не ломают prod?)

Самый важный сдвиг: от управления кодом к управлению спецификациями. Код становится производным. Меняете спецификацию — меняется весь связанный код. Автоматически.

Spec-Driven Development — это не про контроль. Это про ясность. Когда агент знает правила игры, он играет лучше. Когда вы знаете, что агент следует правилам, вы доверяете ему больше. И тратите меньше времени на исправление того, что можно было сделать правильно с первого раза.

Попробуйте. Начните с одной спецификации. Самой болезненной. Увидите разницу через неделю. А через месяц будете удивляться, как раньше жили без этого.