# 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/) — стандарты работы с требованиями


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://vladislaveremeev.gitbook.io/qa_bible/ai-v-testirovanii/spec-driven-ai-development.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.