Сначала договоримся. Потом напишем код.

Что такое SDD

Specification-Driven Development — это разработка, управляемая спецификацией. До реализации команда письменно фиксирует, что должна делать функция, для кого она создаётся, какие у неё ограничения и как проверить результат.

Спецификация здесь — не огромный документ на сотни страниц. Для небольшой задачи достаточно одного Markdown-файла с требованиями, сценариями и критериями приёмки.

Как устроен процесс

1. Опишите проблему.
   Кто пользователь и какую задачу он хочет решить?
2. Зафиксируйте поведение.
   Опишите основной сценарий, ошибки и граничные случаи.
3. Добавьте критерии приёмки.
   Сформулируйте наблюдаемые условия готовности.
4. Согласуйте решение.
   Команда проверяет полноту, риски и противоречия до написания кода.
5. Реализуйте небольшими шагами.
   Код и тесты создаются по пунктам спецификации.
6. Сверьте результат.
   Если реализация изменила поведение, обновите спецификацию.

Простой пример: создание задачи

Допустим, в Java-приложение нужно добавить API для создания задачи. Фраза «сделать добавление задачи» слишком расплывчата. Превратим её в небольшую спецификацию.

# Создание задачи

Пользователь отправляет POST /api/tasks.

Вход:
- title — обязательная строка от 3 до 100 символов
- description — необязательная строка до 1000 символов

Поведение:
- новая задача получает статус TODO
- автором становится текущий пользователь

Результат:
- 201 и созданная задача — при успехе
- 400 — если title не прошёл проверку
- 401 — если пользователь не авторизован

Критерий готовности:
Given авторизованный пользователь
When он отправляет title "Изучить SDD"
Then API возвращает 201, статус задачи TODO

Реализация следует контракту

@PostMapping("/api/tasks")
public ResponseEntity<TaskResponse> create(
        @Valid @RequestBody CreateTaskRequest request,
        Principal principal) {
    TaskResponse task = taskService.create(request, principal.getName());
    return ResponseEntity.status(HttpStatus.CREATED).body(task);
}

Из спецификации сразу видно, какие проверки, статусы ответа и тесты нужны. Если позже появится ограничение «не больше 20 активных задач», сначала меняется спецификация, затем тесты и реализация.

SDD и разработка с AI

AI пишет код увереннее, когда получает точный контракт. Вместо запроса «добавь задачи» передайте ему спецификацию и ограничьте область изменений.

Реализуй specs/create-task.md.

Условия:
- используй существующие Controller, Service и Repository;
- не меняй схему авторизации;
- добавь unit-тесты для валидации;
- после реализации перечисли критерии приёмки
  и покажи, каким тестом проверен каждый из них.

Как внедрить SDD в существующий проект

1. Создайте каталог specs/.
   Храните спецификации рядом с кодом и версионируйте их в Git.
2. Начните с одной новой функции.
   Не пытайтесь сразу описать всю существующую систему.
3. Подготовьте короткий шаблон.
   Используйте разделы: цель, сценарии, требования, ограничения, критерии приёмки и «не входит в задачу».
4. Обсуждайте спецификацию в Pull Request.
   Для сложных задач полезно согласовать её до начала реализации.
5. Свяжите требования с тестами.
   Каждый критерий приёмки должен иметь автоматическую или понятную ручную проверку.
6. Считайте спецификацию частью продукта.
   Изменилось поведение — в том же PR обновляется документ.

Минимальная структура

my-project/
├── specs/
│   ├── template.md
│   └── create-task.md
├── src/
└── README.md

Чек-лист хорошей спецификации

• Понятно, какую проблему решает функция и для кого.
• Описан основной пользовательский сценарий.
• Указаны ошибки, ограничения и граничные случаи.
• Есть конкретные входные и выходные данные.
• Критерии приёмки можно однозначно проверить.
• Указано, что намеренно не входит в текущую задачу.
• В документе нет противоречащих друг другу требований.
• Спецификация достаточно короткая, чтобы её действительно читали.