Зачем это нужно
User story полезна: она связывает пользователя, его цель и ожидаемую ценность. Но для coding agent этого недостаточно. Фраза "как пользователь я хочу сбросить пароль" не говорит, сколько живет token, что делать с неизвестным email, как защищаться от abuse и какие проверки должны пройти.
Если остановиться на user story, агенту придется самому додумывать product behavior. Иногда он угадает. Иногда создаст security gap, сломает API contract или реализует поведение, которое команда не хотела.
Этот урок показывает, как превратить user story в цепочку:
Goal -> Use Case -> Requirement -> Acceptance Criteria -> Test
Основная идея
User story отвечает на вопрос:
Кто хочет какую возможность и зачем?
Specification отвечает на более строгий вопрос:
Как именно система должна вести себя в наблюдаемых сценариях?
User story:
Как пользователь я хочу сбросить пароль,
чтобы восстановить доступ к аккаунту.
Это хорошая отправная точка. Но для реализации нужно определить:
- какие шаги проходит пользователь;
- какие данные вводит;
- какие ошибки возможны;
- какие ограничения безопасности обязательны;
- какие состояния изменяются;
- какие acceptance criteria доказывают готовность.
User story без дальнейшей детализации - это invitation to clarify, а не task для реализации.
Ключевые термины
| Термин | Значение |
|---|---|
| User Story | Краткое описание потребности пользователя и ценности. |
| Goal | Цель пользователя или бизнеса. |
| Use Case | Конкретный сценарий взаимодействия с системой. |
| Requirement | Проверяемое требование к поведению или ограничению. |
| Acceptance Criterion | Условие, по которому requirement считается выполненным. |
| Test Idea | Идея автоматической или ручной проверки acceptance criterion. |
| Hidden Requirement | Требование, которое подразумевается, но не написано явно. |
| Product Decision | Решение о поведении продукта, которое должен утвердить человек или команда. |
Цепочка детализации
Хорошая AI-разработка не перескакивает из user story сразу в code. Она проходит несколько уровней.
Каждый уровень снижает неопределенность.
| Уровень | Вопрос |
|---|---|
| Goal | Зачем это нужно пользователю или бизнесу? |
| Use Case | Какие сценарии должны работать? |
| Requirement | Что система обязана делать или запрещать? |
| Acceptance Criteria | Как понять, что requirement выполнен? |
| Test Idea | Как это проверить внешней системой? |
Пример: Password Reset
Начальная user story:
Как пользователь я хочу сбросить пароль,
чтобы восстановить доступ к аккаунту.
Скрытые вопросы:
- Сколько действует reset token?
- Одноразовый ли token?
- Что делать, если email не существует?
- Нужно ли показывать одинаковый ответ для существующего и неизвестного email?
- Какой rate limit на запрос reset?
- Можно ли запросить несколько reset tokens подряд?
- Какие требования к новому паролю?
- Нужно ли инвалидировать старые sessions?
- Нужно ли писать audit log?
- Нужно ли отправлять email сразу или через очередь?
- Что происходит, если email service недоступен?
Каждый вопрос либо становится requirement, либо open question.
От story к requirements
Пример детализации:
| Goal | Use Case | Requirement | Acceptance Criterion | Test Idea |
|---|---|---|---|---|
| Восстановить доступ | Запросить reset link | REQ-001: пользователь может запросить reset по email |
AC-001: POST /password-reset/request возвращает 202 для валидного email |
Integration test |
| Не раскрывать аккаунты | Запрос для неизвестного email | REQ-002: API не раскрывает, существует ли email |
AC-002: неизвестный email тоже возвращает 202 |
Integration test |
| Предотвратить reuse | Использовать token повторно | REQ-003: token одноразовый |
AC-003: второй запрос с тем же token возвращает TOKEN_USED |
Unit/integration test |
| Ограничить окно риска | Использовать старый token | REQ-004: token истекает через 15 минут |
AC-004: token старше 15 минут возвращает TOKEN_EXPIRED |
Unit test with time control |
| Защитить от abuse | Частые запросы reset | REQ-005: endpoint имеет rate limit |
AC-005: после N запросов API возвращает 429 |
Integration/security test |
Такая таблица еще не является полным spec.md, но она уже превращает story в проверяемое поведение.
Какие решения должен принять человек
Агент может предложить варианты. Но некоторые решения являются product/security decisions и не должны приниматься молча.
Примеры:
| Вопрос | Почему это human/product decision |
|---|---|
| Показывать ли одинаковый ответ для неизвестного email? | Влияет на безопасность и UX. |
| Сколько живет token? | Баланс безопасности и удобства. |
| Инвалидировать ли старые sessions? | Влияет на безопасность и пользовательский опыт. |
| Нужен ли audit log? | Влияет на compliance и расследование инцидентов. |
| Какой rate limit выбрать? | Влияет на abuse protection и legitimate users. |
Правильное поведение агента:
Я нашел несколько неопределенных product/security решений.
Нужно утвердить их до реализации.
Неправильное поведение:
Я выбрал 1 час TTL, потому что это обычно нормально.
Иногда default действительно разумный. Но он должен быть явным assumption или decision, а не скрытой догадкой.
Hidden requirements
Hidden requirements особенно опасны, потому что они проявляются поздно: на review, security audit, incident или после жалобы пользователя.
Для password reset типичные hidden requirements:
Security:
- token одноразовый;
- token хранится безопасно;
- unknown email не раскрывается;
- есть rate limit.
Reliability:
- email failure не создает inconsistent state;
- повторный запрос ведет себя предсказуемо.
UX:
- пользователь получает понятное сообщение;
- expired token ведет на экран повторного запроса.
Audit:
- важные действия записываются.
Задача specification - сделать hidden requirements видимыми до кода.
Практика: расширить user story
Возьмите story:
Как пользователь я хочу сбросить пароль,
чтобы восстановить доступ к аккаунту.
Сделайте три шага.
Шаг 1. Выпишите вопросы
Минимум 10 вопросов по behavior, security, UX, data и failure cases.
Шаг 2. Разделите вопросы
Отметьте каждый вопрос как:
Decision needed
Requirement candidate
Edge case
Out of scope
Шаг 3. Соберите таблицу
Заполните таблицу:
Goal | Use Case | Requirement | Acceptance Criterion | Test Idea
Итоговый артефакт:
labs/02-password-reset/story-expansion.md
Типичные ошибки
Ошибка 1. Считать user story готовым заданием для coding agent
User story описывает намерение, но не содержит достаточно поведения для реализации.
Ошибка 2. Писать acceptance criteria слишком общо
Плохо:
Пользователь может сбросить пароль.
Лучше:
Given token истек
When пользователь отправляет новый пароль
Then API возвращает 400 TOKEN_EXPIRED
And пароль не меняется
Ошибка 3. Не отделять open questions от decisions
Если вопрос не решен, он должен оставаться open question. Нельзя незаметно превращать его в assumption.
Ошибка 4. Игнорировать failure cases
Happy path почти всегда проще. Надежность продукта часто определяется тем, как система ведет себя в ошибках.
Ошибка 5. Делегировать product decisions агенту
Агент может помочь найти вопросы и предложить варианты. Ответственность за product behavior остается у человека или команды.
Критерии готовности
После урока студент должен уметь:
- объяснить, зачем нужны user stories и почему их недостаточно;
- построить цепочку
Goal -> Use Case -> Requirement -> Acceptance Criteria -> Test; - найти hidden requirements в простой story;
- отделить open questions от accepted decisions;
- сформулировать минимум 5 requirements для password reset story.
Краткое резюме
User story - хороший способ начать разговор о ценности. Но coding agent нужен не только intent, а проверяемое поведение.
Чтобы перейти от story к реализации, нужно извлечь:
- use cases;
- hidden requirements;
- edge cases;
- product/security decisions;
- acceptance criteria;
- test ideas.
Только после этого story становится пригодной основой для specification и будущих agent tasks.
Вопросы для самопроверки
- Почему user story не является достаточным input для coding agent?
- Какие hidden requirements есть в password reset?
- Чем open question отличается от accepted decision?
- Почему unknown email behavior является security/product decision?
- Как acceptance criterion связан с test idea?
Что дальше
В следующем уроке мы поднимемся на уровень выше и разберем иерархию спецификаций: Vision, PRD, System Requirements, Architecture, Feature Specification, Tasks и Tests. Это поможет понять, где должна жить каждая часть знания о проекте.