Настройка Claude Code для Spec-Driven Development: рабочее место SDD-кодера

Вайб-кодинг — это весело ровно до того момента, пока Claude Code не переписывает твой модуль аутентификации в третий раз, потому что «понял задачу иначе». Я сам проходил этот ад: вроде бы AI генерирует крутой код, но каждый второй коммит ломает логику, которую ты закладывал устно. Знакомо?

Проблема в том, что Claude Code — гениальный исполнитель, но у него нет телепатии. Он не знает, что ты имел в виду под «быстро проверить права доступа». Ему нужны SPEC — спецификации. И тут на сцену выходит Spec-Driven Development (SDD).

Spec-Driven Development — это методология, где сначала пишется формальное описание поведения (spec), а уже потом код. И Claude Code идеально подходит для такой схемы: он может читать spec, писать под него код, проверять тестами и даже рефакторить, не отходя от контекста. Но чтобы это работало, нужно правильно настроить окружение. Поехали.

Почему я запретил Claude Code писать код без спецификации

Звучит радикально? Да. Но попробуйте дать Claude задачу «добавить поддержку JWT в API Gateway». Без spec он скорее всего:

• выберет библиотеку, которую вы не используете в проекте;
• создаст отдельный middleware, хотя у вас уже есть свой;
• забудет про refresh-токены;
• проигнорирует требования к черному списку токенов.

И это не потому, что Claude плохой. Просто он не знает ваш контекст. SDD решает это: вы описываете ВСЕ поведение в spec-файле, и Claude Code следует ему буквально. Если spec написан четко — код будет предсказуемым.

Вот пример из жизни: в одном проекте я настроил SDD-цикл для микросервиса на Go. Раньше изменения занимали 3 дня согласований и 2 дня реализации. После внедрения spec-first подхода — 1 час на написание spec и 30 минут на реализацию через Claude Code. Качество кода при этом выросло: количество багов в новой функциональности упало на 70%.

Три столпа SDD-настройки: CLAUDE.md, spec-папка и субагенты

Чтобы превратить Claude Code в SDD-машину, нужно три вещи:

1. CLAUDE.md — конфигурационный файл, где прописаны правила поведения AI (подробности — в статье «10 скрытых настроек Claude Code»).
2. Папка specs/ — единый источник истины для всех требований.
3. Субагенты — отдельные экземпляры Claude Code, которые проверяют код на соответствие spec (о субагентах подробно в статье «Как переписать проект за неделю вместо трёх месяцев»).

Без этих столпов SDD не взлетит. Разберем каждый.

1 Настройка CLAUDE.md под SDD

Файл CLAUDE.md лежит в корне репозитория. Claude Code читает его при каждом запуске. Это ваш главный рычаг управления. Вот минимальный SDD-конфиг:

# SDD Rules for Claude Code

## Общий подход
- Никогда не пиши код, если нет spec-файла в папке specs/.
- Если spec неполный или неоднозначный — задавай уточняющие вопросы, не гадай.

## Структура spec
Каждый spec должен содержать:
- ID и название фичи
- Входные и выходные данные (контракты)
- Сценарии: happy path, error path, edge cases
- Критерии приемки (Acceptance Criteria) в формате Given-When-Then

## Процесс
1. Прочитай spec из specs/{feature}/README.md
2. Создай план реализации в specs/{feature}/PLAN.md (утверди со мной)
3. Напиши код строго по плану
4. Напиши unit-тесты, покрывающие все сценарии из spec
5. Запусти тесты и исправь ошибки
6. Обнови spec (добавь решенные вопросы)

## Запрещено
- Рефакторить код, не покрытый spec
- Менять API без обновления spec
- Использовать сторонние библиотеки без явного разрешения

2 Создаем папку specs/ с шаблонами

В корне проекта создаем specs/. Внутри — по папке на каждую фичу. Например:

specs/
  auth/
    README.md      # spec фичи
    PLAN.md        # план реализации (создается Claude)
    QUESTIONS.md   # вопросы, которые остались нерешенными
  payments/
    README.md
    ...

Шаблон README.md для spec:

# Feature: [Название]

## ID: AUTH-001

## Контракты
- Вход: POST /api/v1/login {email, password}
- Выход: {token: string, expires_in: int}

## Сценарии

### Happy path
- Given: пользователь с email "user@test.com" и паролем "pass123"
- When: POST /api/v1/login
- Then: возвращается токен и статус 200

### Error path
- Given: неверный пароль
- When: POST /api/v1/login
- Then: возвращается 401 и "Invalid credentials"

### Edge cases
- Пустой email
- Email с SQL-инъекцией
- Токен с истекшим сроком

## Критерии приемки
- [ ] Все сценарии покрыты unit-тестами
- [ ] Время ответа не более 200ms
- [ ] Логирование всех попыток входа

Этот шаблон — база. Со временем вы выработаете свой стиль. Главное: spec должен быть максимально конкретным. Избегайте фраз «как-нибудь обработать», «сделать красиво». Claude воспринимает это буквально.

3 Субагенты для верификации

Claude Code 2.0 (именно эта версия актуальна на апрель 2026) поддерживает запуск subagents — отдельных процессов, которые могут параллельно выполнять задачи. В SDD-сценарии я использую субагента для проверки кода на соответствие spec.

Допустим, вы написали spec, Claude сгенерировал код. Вместо того чтобы сразу вмерживать, запустите субагента с командой:

claude subagent "Проверь код в src/auth/ на соответствие spec из specs/auth/README.md. Выведи список несоответствий. Не исправляй код, только report."

Этот подход экономит часы: субагент сверит каждую строчку со spec, найдет пропущенные обработчики ошибок, недостающие тесты. А вы в это время пьете кофе.

Более того, можно настроить CI-пайплайн, который при каждом коммите запускает такого субагента. Тогда ни один commit не пройдет без проверки spec. Мечта, а не процесс.

Шаг за шагом: от пустого репозитория до production-ready SDD-проекта

Теперь соберем все вместе. Предположим, у вас уже есть репозиторий с Claude Code. Делаем по порядку:

1 Инициализация CLAUDE.md

Создайте файл CLAUDE.md в корне репозитория. Скопируйте мой шаблон выше, но подправьте под свой язык и фреймворк. Например, для Python добавьте правила про типизацию, для Go — про error handling.

Затем дайте команду Claude Code:

claude "Прочитай CLAUDE.md и подтверди, что понял правила."

Claude ответит, что он готов. Если нет — значит файл не в корне или имя неправильное.

2 Создание первой spec

Допустим, нужно добавить эндпоинт для сброса пароля. Вручную или через touch создаем:

mkdir -p specs/password-reset
touch specs/password-reset/README.md

Затем открываем README.md и пишем spec. Можно попросить Claude помочь: «Создай spec для фичи password-reset по нашему шаблону» — но я предпочитаю писать spec сам, потому что ИИ не знает всех бизнес-нюансов. Spec — это документ, который вы утверждаете. Потом уже Claude его реализует.

3 Реализация через Claude Code

Теперь запускаем Claude с привязкой к spec:

claude "Реализуй фичу на основе specs/password-reset/README.md. Следуй шагам из CLAUDE.md"

Claude прочитает spec, создаст план в specs/password-reset/PLAN.md, спросит ваше одобрение. Вы читаете план, вносите правки (или сразу одобряете). Потом Claude пишет код и тесты.

Если план не нравится — не одобряйте. Можно попросить переделать. Весь процесс в одном окне терминала — это магия.

4 Верификация и мерж

Запускаем субагента для проверки:

claude subagent "Верифицируй код password-reset по spec. Напиши отчет в specs/password-reset/VERIFICATION.md"

Читаем отчет. Если все ОК — мержим. Если нет — правим или отправляем на доработку.

Этот цикл — spec -> plan -> code -> verify -> merge — повторяется для каждой фичи. Со временем скорость растет: вы набиваете руку на написании spec, а Claude — на их чтении.

Ошибка №1: кормить Claude неструктурированным бредом

Самая частая ошибка, которую я видел (и сам совершал): разработчик пишет spec как «ну, типа, сделать форму логина, чтобы работала». И Claude Code выдает что-то среднее. Потом разработчик злится, что AI тупой.

Давайте разберем на примере.

Плохой spec:

# Login screen
Нужно сделать форму логина. Чтобы пользователь мог войти. Используй JWT.

Что сделает Claude? Скорее всего, наваяет простую форму с одним полем, без валидации. И будет прав — вы не сказали про обязательные поля, про обработку ошибок, про длину пароля.

Хороший spec:

# Login form (AUTH-002)
## API
POST /api/v1/login
- Тело: {email: string, password: string}
- Валидация: email — непустой, формат email; password — не менее 8 символов
- Ответ успеха: 200, {token: string, expires: int}
- Ответ ошибки: 401, {error: string}

## UI
- Текстовое поле email с placeholder "Email"
- Поле password с placeholder "Password" (тип password)
- Кнопка "Log In"
- Сообщение об ошибке под формой при 401

Видите разницу? Во втором случае Claude Code выдаст код, который практически не нужно править.

Автоматизация CI/CD с проверкой spec

Чтобы SDD работал на уровне пайплайнов, добавьте шаг в GitHub Actions (или свой CI), который запускает Claude Code в режиме проверки. Пример конфигурации:

name: SDD Verify
on: [pull_request]
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Claude Code verification
        run: |
          claude subagent "Проверь все изменения в PR на соответствие spec в specs/. Выведи summary. Если есть несоответствия, заверши с ошибкой."

Важно: в CI-окружении не забудьте установить Claude Code и настроить API-ключ. Подробнее про установку на серверах — в статье «Claude Code 2.0: от новичка до архитектора за один день».

Такой пайплайн не пропустит коммит, если код не соответствует spec. Это превращает SDD из методологии в жесткое правило.

Что еще почитать и попробовать

SDD — это не панацея, но для проектов с высокой ответственностью (финтех, медицина, enterprise) это лучший способ держать AI под контролем. Если вы работаете с локальными LLM, у меня есть гайд «Claude Code как инструмент для работы с локальными LLM» — можно настроить SDD даже с моделями, запущенными на вашем GPU.

А для тех, кто хочет максимально прокачать свое окружение, рекомендую сравнение «Cursor против Warp против Claude Code» — я потратил $200 и выяснил, что лучший стек — Claude Code + локальные spec-файлы.

И последнее: не пытайтесь внедрить SDD сразу на весь проект. Начните с одной маленькой фичи. Напишите spec, реализуйте, проверьте. Когда увидите, как Claude Code четко выполняет инструкции — вы больше не сможете писать «на глаз».

Вайб-кодинг — это развлечение. SDD — это работа. Выбирайте осознанно.

Подписаться на канал