Зачем это нужно
Даже аккуратно заполненный spec.md почти всегда содержит неопределенности. Некоторые требования могут конфликтовать, edge cases могут быть пропущены, термины могут быть не определены, а часть product decisions может быть спрятана в assumptions.
Если сразу перейти к design или code, агент начнет закрывать пробелы самостоятельно. Иногда это удобно, но для управляемой разработки опасно: важные решения принимаются неявно и потом растворяются в diff.
Clarification Phase - это отдельный gate между черновиком specification и реализацией. Его цель - превратить "примерно понятно" в approved spec.
Основная идея
Clarification Phase выглядит так:
Draft spec
↓
Clarification review
↓
Questions
↓
Human decisions
↓
Approved spec
↓
Design / Plan / Tasks / Code
Агент на этом этапе не пишет код. Его работа:
- найти ambiguity;
- найти conflicts;
- найти missing edge cases;
- обнаружить implicit assumptions;
- указать undefined terminology;
- предложить варианты, если это помогает человеку принять решение.
Но финальное product/security/architecture решение утверждает человек или команда.
Ключевые термины
| Термин | Значение |
|---|---|
| Draft Spec | Черновик specification, еще не готовый для реализации. |
| Approved Spec | Specification после уточнений и утверждения ключевых решений. |
| Ambiguity | Формулировка, которую можно понять несколькими способами. |
| Conflict | Противоречие между требованиями, constraints или acceptance criteria. |
| Missing Edge Case | Важный пограничный сценарий, которого нет в spec. |
| Implicit Assumption | Предположение, которое влияет на реализацию, но не записано явно. |
| Undefined Term | Термин без точного значения в контексте продукта. |
| Clarification Question | Вопрос, ответ на который нужен до design/code. |
| Decision Log | Краткая фиксация принятых решений. |
Схема процесса
Главное: вопросы должны возвращаться в spec. Если ответ остался только в чате, future agent может его потерять.
Что именно должен искать агент
Ambiguities
Ambiguity - это фраза, которую можно реализовать по-разному.
Пример:
Token должен быть короткоживущим.
Вопрос:
Какой точный TTL: 10 минут, 15 минут, 1 час?
Conflicting requirements
Conflict возникает, когда два требования не могут быть одновременно выполнены.
Пример:
REQ-002:
Не раскрывать, существует ли email.
AC-004:
Для неизвестного email возвращать 404 USER_NOT_FOUND.
Вопрос:
Какое поведение приоритетнее: security requirement против account enumeration или явная ошибка для unknown email?
Missing edge cases
Spec может описывать happy path, но не ошибки.
Пример:
Пользователь устанавливает новый пароль по token.
Пропущенные cases:
- token expired;
- token already consumed;
- token malformed;
- password too weak;
- user disabled;
- repeated request.
Implicit assumptions
Implicit assumption - это решение, которое агенту придется принять, если его не записать.
Пример:
После reset пользователь может войти с новым паролем.
Скрытый вопрос:
Что происходит со старыми active sessions?
Undefined terminology
Термины должны быть понятны одинаково человеку и агенту.
Пример:
Admin может сбросить пароль пользователя.
Вопросы:
- Кто считается Admin?
- Это workspace admin или system admin?
- Нужен ли audit log?
- Может ли admin сбросить пароль другого admin?
Формат clarification output
Хороший результат clarification phase должен быть структурированным.
Пример:
# Clarification Questions: Password Reset
## Blockers
Q1. Какой точный TTL reset token?
Why it matters:
Влияет на security behavior, tests и error handling.
Options:
- 15 minutes
- 30 minutes
- 1 hour
Recommendation:
15 minutes для снижения окна риска.
## Non-blocking questions
Q2. Нужно ли отправлять notification после успешной смены пароля?
## Detected conflicts
C1. REQ-002 требует не раскрывать unknown email,
но AC-004 ожидает 404 USER_NOT_FOUND.
## Assumptions not safe to make
A1. Инвалидировать ли старые sessions после reset.
Важно разделять blockers и non-blocking questions. Не каждый вопрос должен останавливать весь процесс, но каждый важный вопрос должен быть видимым.
Как обновлять spec после ответов
Плохо:
Human: Пусть token живет 15 минут.
Agent: Ок, понял.
Лучше:
REQ-003:
Reset token expires 15 minutes after creation.
AC-003:
Given token старше 15 минут
When пользователь отправляет новый пароль
Then API возвращает HTTP 400
And error.code = "TOKEN_EXPIRED"
And password не меняется
И добавить в decision log:
## Decisions
DEC-001:
Reset token TTL = 15 minutes.
Reason: reduce account takeover risk while preserving common UX expectations.
Решение должно стать частью source of truth.
Пример плохого spec и вопросов
Черновик:
# Feature: Password Reset
## Desired behavior
Пользователь может запросить reset link и установить новый пароль.
Token короткоживущий и безопасный.
## Acceptance criteria
- Reset работает для существующего пользователя.
- Неизвестный email показывает ошибку.
- Старый token нельзя использовать.
Clarification questions:
Q1. Какой точный TTL означает "короткоживущий"?
Q2. Что значит "безопасный" для token storage: hashed token, signed token, server-side token?
Q3. Должен ли unknown email показывать ошибку, если это раскрывает наличие аккаунта?
Q4. Что значит "старый token": expired или consumed?
Q5. Что происходит со старыми sessions после успешной смены пароля?
Q6. Какой password policy применяется к новому паролю?
Q7. Нужен ли rate limit для request endpoint?
Q8. Нужен ли audit log?
После ответов эти вопросы должны превратиться в requirements, constraints, security requirements или out of scope.
Роль агента в Clarification Phase
На этом этапе агент полезен как внимательный reviewer specification.
Он может:
- найти неполные требования;
- сравнить acceptance criteria с edge cases;
- предложить security-sensitive questions;
- указать conflicts;
- предложить варианты с trade-offs.
Он не должен:
- молча выбирать product behavior;
- начинать design до approved spec;
- писать code "пока вопросы решаются";
- прятать assumptions внутри implementation;
- удалять open questions без решения.
Практика: clarification review
Возьмите черновик specs/password-reset/spec.md из урока 2.4.
Попросите агента выполнить только clarification review:
Прочитай specs/password-reset/spec.md.
Не предлагай implementation plan и не пиши код.
Найди ambiguity, conflicts, missing edge cases,
implicit assumptions и undefined terminology.
Сгруппируй вопросы на blockers и non-blocking.
Для каждого blocker объясни, почему он влияет на реализацию или tests.
Итоговый артефакт:
specs/password-reset/clarifications.md
Затем ответьте на вопросы и обновите spec.md.
Definition of Done:
[ ] Все blocker questions имеют ответы
[ ] Ответы перенесены в spec.md
[ ] Open questions оставлены только для non-blocking items
[ ] Product/security decisions явно записаны
[ ] Agent не переходил к design/code
Типичные ошибки
Ошибка 1. Считать clarification лишней задержкой
Clarification кажется медленной только до первого большого rewrite. Один уточняющий вопрос до кода часто экономит часы исправлений после.
Ошибка 2. Разрешать агенту самому закрывать blockers
Агент может предложить разумный default, но это должно быть явно утверждено.
Ошибка 3. Не переносить ответы в spec
Если ответ остался в чате, он не стал source of truth.
Ошибка 4. Смешивать clarification и design
Clarification отвечает "что должно быть решено". Design отвечает "как мы это реализуем". Не надо смешивать эти этапы.
Ошибка 5. Не различать blockers и non-blocking вопросы
Некоторые вопросы действительно блокируют реализацию. Другие можно оставить out of scope или future improvement. Важно явно их разделить.
Критерии готовности
После урока студент должен уметь:
- объяснить назначение Clarification Phase;
- найти ambiguity, conflict, missing edge case, implicit assumption и undefined terminology;
- сформулировать clarification questions для агента;
- отделить blockers от non-blocking questions;
- перенести accepted decisions обратно в
spec.md; - объяснить, почему без approved spec агент не должен переходить к design/code.
Краткое резюме
Clarification Phase - это safety gate между draft spec и реализацией.
Ее задача:
Draft spec
↓
Find uncertainty
↓
Ask questions
↓
Record decisions
↓
Approved spec
Для AI Agent Development это критично: агент должен помогать выявлять неопределенность, но не должен скрыто принимать важные product, security и architecture decisions.
Вопросы для самопроверки
- Чем ambiguity отличается от open question?
- Почему конфликт между unknown email behavior и security requirement нужно решить до code?
- Какие questions для password reset являются blockers?
- Почему accepted decisions нужно переносить в
spec.md? - Чем Clarification Phase отличается от implementation planning?
Что дальше
Модуль II завершает первый слой Specification-Driven Development: теперь у нас есть способ превратить user story в approved feature spec. В следующем модуле мы перейдем к Architecture Driven Development и разберем, как architecture constraints ограничивают пространство решений агента.