> For the complete documentation index, see [llms.txt](https://vladislaveremeev.gitbook.io/qa_bible/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://vladislaveremeev.gitbook.io/qa_bible/ai-v-testirovanii/spec-driven-ai-development.md).

# Spec-Driven AI Development

**Spec-Driven AI Development** — методология, при которой команда вкладывает максимальные усилия в создание детальной спецификации (требования, acceptance criteria, примеры поведения, граничные условия), а затем использует её как входные данные для AI-генерации кода и тестов.

В отличие от Vibe Coding, где промпт пишется наспех, Spec-Driven подход рассматривает спецификацию как инженерный артефакт: она версионируется, ревьюится и является единственным источником правды для AI.

***

## Ключевая идея

```
Детальная спецификация → AI генерирует код и тесты → QA верифицирует соответствие
```

Качество выходных данных AI напрямую определяется качеством входных данных. **«Мусор на входе — мусор на выходе»** — это правило особенно жёстко работает с AI: если спецификация неполная или двусмысленная, AI уверенно реализует что-то своё.

{% hint style="info" %}
Spec-Driven AI Development — это эволюция BDD (Behavior-Driven Development): Gherkin-сценарии становятся не только документацией и автотестами, но и промптами для генерации реализации.
{% endhint %}

***

## Процесс

### 1. Совместное написание спецификации

Аналитик, разработчик и QA работают над спецификацией вместе. Роли:

| Роль        | Вклад в спецификацию                                 |
| ----------- | ---------------------------------------------------- |
| Аналитик    | Бизнес-требования, use cases, приоритеты             |
| Разработчик | Технические ограничения, интерфейсы, зависимости     |
| QA          | Acceptance criteria, edge cases, негативные сценарии |

QA является ключевым участником на этом этапе — именно QA-мышление добавляет в спецификацию то, что AI не реализует без явного указания.

### 2. Структура спецификации для AI

Хорошая спецификация для AI-генерации включает:

```markdown
## Функция: [название]

### Описание
[что делает, зачем нужна]

### Входные данные
- param1: тип, допустимые значения, ограничения
- param2: тип, обязательный/опциональный

### Поведение
- При X → возвращает Y
- При Z → бросает ошибку типа N с сообщением M

### Граничные условия
- Пустая строка → [поведение]
- Максимальная длина (256 символов) → [поведение]
- Специальные символы → [поведение]

### Примеры (Given/When/Then)
Given: пользователь не авторизован
When: запрашивает защищённый ресурс
Then: получает 401 Unauthorized с телом {"error": "unauthorized"}

### Что НЕ входит в scope
- [явное ограничение]
```

### 3. Генерация кода и тестов

AI получает спецификацию и генерирует:

* Реализацию функции/компонента/сервиса
* Юнит-тесты, покрывающие описанные сценарии
* При необходимости — интеграционные тесты

### 4. Верификация

QA проверяет соответствие результата спецификации, а не только то, что код «работает». Главный вопрос: **реализовано ли именно то, что написано в спецификации?**

***

## Требования к спецификации

### Признаки хорошей спецификации для AI

* **Полнота**: описаны все пути выполнения — happy path, edge cases, ошибки
* **Конкретность**: числа вместо «много», «большой», «быстрый»
* **Однозначность**: каждое утверждение имеет только одну интерпретацию
* **Примеры**: конкретные входы и ожидаемые выходы
* **Явные исключения**: что явно НЕ входит в scope

### Типичные проблемы спецификаций

| Проблема                       | Пример                     | Последствие                                    |
| ------------------------------ | -------------------------- | ---------------------------------------------- |
| Неопределённость               | «валидировать данные»      | AI выберет произвольную логику валидации       |
| Отсутствие ошибочных сценариев | Описан только happy path   | AI не реализует обработку ошибок               |
| Отсутствие граничных значений  | «принимает строки»         | AI не обработает пустую строку и null          |
| Противоречия                   | Два требования конфликтуют | AI выберет одно из них, молча игнорируя другое |
| Имплицитные предположения      | «как обычно»               | AI не знает «как обычно» в контексте команды   |

{% hint style="danger" %}
Неточное требование в спецификации приводит к неверному коду и неверному тесту одновременно. В результате автотесты проходят, а баг остаётся — AI построил согласованную, но неправильную систему.
{% endhint %}

***

## Связь с BDD

Spec-Driven AI Development органично сочетается с BDD-практиками:

```gherkin
Feature: Авторизация пользователя

  Scenario: Успешный вход с корректными данными
    Given пользователь с email "user@example.com" существует в системе
    And его пароль "SecurePass123"
    When он отправляет POST /auth/login с корректными данными
    Then он получает 200 OK
    And тело ответа содержит "access_token"

  Scenario: Вход с неверным паролем
    Given пользователь с email "user@example.com" существует в системе
    When он отправляет POST /auth/login с неверным паролем
    Then он получает 401 Unauthorized
    And тело ответа содержит {"error": "invalid_credentials"}

  Scenario: Вход с несуществующим email
    When он отправляет POST /auth/login с email "unknown@example.com"
    Then он получает 401 Unauthorized
```

Такой Gherkin-файл:

1. Служит документацией для команды
2. Генерирует степ-дефиниции для Cucumber/pytest-bdd
3. Используется как промпт для AI-генерации реализации
4. Является acceptance criteria для QA

***

## Роль QA в Spec-Driven AI Development

Это методология, где QA получает максимальное влияние на качество ещё до написания кода.

### До генерации (самый важный этап)

* Участие в написании acceptance criteria
* Добавление негативных сценариев и граничных условий
* Ревью спецификации на тестируемость: можно ли автоматически проверить каждое требование?
* Формулировка примеров в формате Given/When/Then

### Во время генерации

* Помощь в построении промптов: передавать AI нужный контекст (структуру БД, используемые паттерны, соглашения команды)
* Верификация качества промптов перед отправкой

### После генерации

* Проверка соответствия сгенерированного кода спецификации (не просто «работает», а «делает то, что написано»)
* Ревью AI-сгенерированных тестов: покрывают ли они все сценарии из спецификации?
* Добавление исследовательских тестов за пределами спецификации

***

## Сравнение с другими методологиями

| Параметр                          | Spec-Driven              | Vibe Coding    | AI-Augmented |
| --------------------------------- | ------------------------ | -------------- | ------------ |
| Входные требования к спецификации | Максимальные             | Минимальные    | Стандартные  |
| Скорость генерации                | Средняя                  | Максимальная   | Высокая      |
| Качество без QA                   | Высокое                  | Низкое         | Среднее      |
| Роль QA                           | Сдвинута влево, критична | Критична после | Традиционная |
| Технический долг                  | Низкий                   | Высокий        | Умеренный    |
| Предсказуемость результата        | Высокая                  | Низкая         | Высокая      |

***

## Инструменты поддержки

| Категория                    | Инструменты                                |
| ---------------------------- | ------------------------------------------ |
| Управление требованиями      | Confluence, Notion, Linear                 |
| BDD-фреймворки               | Cucumber, SpecFlow, Behave, pytest-bdd     |
| AI-генерация по спецификации | Claude, GPT-4, Gemini (через API или Chat) |
| Версионирование спецификаций | Git (Markdown/Gherkin в репозитории)       |
| Генерация тестов             | Claude Code, Copilot, Cursor               |

***

## Практические советы

### Для QA

1. **Требуйте полные спецификации** — «доработаем в процессе» ломает весь смысл подхода
2. **Добавляйте негативные сценарии** в каждое требование — разработчики и AI склонны их пропускать
3. **Используйте числа** — «максимум 100 символов», «не более 3 попыток», «таймаут 30 секунд»
4. **Описывайте ошибки подробно** — HTTP-статус, формат тела ответа, сообщение пользователю
5. **Проверяйте AI-тесты против спецификации** — убедитесь, что тест проверяет именно то, что написано в требовании

{% hint style="info" %}
Заведите шаблон спецификации для вашей команды. Единый формат снижает когнитивную нагрузку и позволяет AI получать структурированный вход с первого раза.
{% endhint %}

***

## Источники

* [BDD in Action — John Ferguson Smart](https://www.manning.com/books/bdd-in-action-second-edition) — основы BDD, применимые к Spec-Driven AI Dev
* [Gherkin Reference](https://cucumber.io/docs/gherkin/reference/) — синтаксис Gherkin для написания спецификаций
* [ISTQB — Foundation Level Syllabus](https://www.istqb.org/) — стандарты работы с требованиями