От промптов к спекам с AI-агентами

Анатомия рабочей спеки

В прошлом подмодуле мы разобрались, почему промпт не масштабируется на проект, и завели CLAUDE.md как постоянный контекст для агента. Теперь следующий слой: как написать спеку конкретной фичи, по которой агент сможет работать, а не заполнять пробелы угадками.

Почему «короткое описание» не работает

Большинство первых спек страдают одним из двух дефектов.

Слишком коротко. «Добавь авторизацию через JWT» — это одна строчка, не спека. Всё, что не написано явно, агент придумает сам. На третьем запросе вы обнаружите, что у вас появился cookie-session, о котором вы не просили.

Всё перемешано. В одном абзаце — что должна делать фича, как хранить токены, какой флоу ошибок, что рисует UI. Такую спеку сложно согласовать с продактом и сложно менять — технические и продуктовые решения переплетены.

Рабочая спека — не длинный документ. Это структурированный.

Шесть блоков рабочей спеки

Цель — одна-две строки: что делаем и для кого. Агент читает это первым и получает контекст для всей задачи.

*Пример:* пользователь может войти в приложение с email и паролем и получить JWT-токен для авторизации последующих запросов.

Не-цели — явный список того, что выходит за рамки этой фичи. Один из самых ценных блоков: защищает от разрастания скоупа прямо во время реализации.

*Пример:* не входит — OAuth, сброс пароля, 2FA, «запомнить меня».

Требования — список «что»: поведение системы с точки зрения пользователя, без деталей реализации.

• При успешном входе возвращается токен сроком 7 дней.
• При неверном пароле — 401 и сообщение «Invalid credentials».
• После 5 ошибок подряд — блокировка на 15 минут.

Дизайн — технические решения: эндпоинты, структуры данных, алгоритм. Заполняется разработчиком, иногда вместе с агентом.

• POST /auth/login принимает {email, password}, возвращает {token, expiresAt}.
• Токен — JWT HS256, payload: {userId, email, exp}.
• Счётчик ошибок: колонки failed_attempts и lock_until в таблице users.

Граничные случаи — самый часто пропускаемый блок. Агент не спросит про edge case, если вы его не написали.

• User@Example.com и user@example.com — один пользователь или разные?
• Верный пароль введён во время блокировки — что происходит?
• Просроченный токен возвращает 401 или 403?

Критерии готовности — чеклист, по которому однозначно видно «сделано». Эти же пункты используются при приёмке (об этом — в пятом подмодуле).

• [ ] POST /auth/login возвращает токен при верных данных.
• [ ] Неверный пароль → 401, правильное сообщение.
• [ ] Блокировка после 5 ошибок — покрыта тестом.
• [ ] Email регистронезависим — есть тест.

«Что» и «Как»: зачем разделять

Блоки «Требования» и «Дизайн» легко перепутать, но их разделение даёт конкретную практическую выгоду.

Если вы работаете с продактом, он видит раздел «Требования» и проверяет поведение без необходимости понимать JWT или структуру базы. Разработчик работает с «Дизайном» и предлагает технические решения, не трогая продуктовые условия. Когда они смешаны, правка в одной части ломает понимание другой.

С агентом та же история. Если требование и реализация записаны в одном предложении — «хранить сессии в Redis» — агент трактует Redis как обязательный выбор в любом контексте. Разделите «что» и «как» — и сможете менять одно, не переписывая другое.

<!-- ❌ смешано: реализация вписана в требование -->
## Требования
- Хранить сессии в Redis с TTL 7 дней.

<!-- ✅ разделено -->
## Требования
- Сессия остаётся активной 7 дней после входа.

## Дизайн
- Хранить сессии в Redis, ключ `session:{userId}`, TTL 604 800 с.

Простой тест: «Если реализация изменится, этот пункт всё равно останется верным?» Да — требование. Нет — дизайн.

Шаблон для копирования

Сохраните в specs/_template.md и используйте для каждой новой фичи:

# [Название фичи]

## Цель
[Что и для кого — одна-две строки]

## Не-цели
- [Явные исключения скоупа]

## Требования
- [ ] [Поведение с точки зрения пользователя / системы]

## Дизайн
[Эндпоинты, структуры данных, алгоритмы]

## Граничные случаи
- [Edge case]

## Критерии готовности
- [ ] [Проверяемый пункт]

Каждая фича — отдельный файл: specs/auth-login.md, specs/user-profile.md. Имена в kebab-case, совпадают с названием задачи.

Конституция и спека фичи: два разных инструмента

CLAUDE.md — про весь проект: стек, соглашения, неизменные принципы. Меняется редко, агент читает его при каждом запуске автоматически.

Спека фичи — про один конкретный скоуп. Вы кладёте её в контекст явно, когда начинаете работу над фичей. Оба файла работают в паре: конституция задаёт правила, спека — цель.

Если в процессе написания спеки вы понимаете, что правило относится ко всему проекту — например, «все эндпоинты требуют авторизации, кроме /auth/*» — это место в CLAUDE.md, не в спеке фичи.

Задание

Возьмите одну фичу из своего pet-проекта — небольшую: один эндпоинт, одна форма. Заполните шаблон выше. Правило: не тратьте на это больше 30 минут. Пропуски — нормально; в следующем подмодуле вы прогоните спеку через агента, и он сам найдёт дыры.