Зачем это нужно
Specification - это не один файл, куда нужно сложить все знания о продукте. В реальном проекте есть разные уровни: от видения продукта до конкретной задачи агента и теста.
Если эти уровни смешаны, появляются две проблемы:
- агент получает слишком много нерелевантного контекста;
- важные решения теряются в chat history, issue comments или длинных prompt'ах.
Иерархия спецификаций помогает держать source of truth в репозитории и выбирать только тот контекст, который нужен для текущего agent run.
Основная идея
У разных документов разные вопросы.
Vision
↓
PRD
↓
System Requirements
↓
Architecture
↓
Feature Specification
↓
Implementation Plan
↓
Tasks
↓
Tests
Агенту не нужно загружать все эти документы постоянно. Но они должны существовать как source of truth, чтобы:
- человек и agent ссылались на одни решения;
- требования не жили только в чате;
- можно было обновлять знания проекта после задач;
- future agents не переизобретали уже принятые решения.
Ключевые термины
| Уровень | Отвечает на вопрос |
|---|---|
| Vision | Зачем существует продукт и для кого он создается? |
| PRD | Какие product capabilities и outcomes нужны? |
| System Requirements | Какие системные требования и ограничения обязательны? |
| Architecture | Как система устроена и какие решения приняты? |
| Feature Specification | Как должна вести себя конкретная фича? |
| Implementation Plan | Как мы собираемся реализовать фичу технически? |
| Tasks | Какие маленькие проверяемые изменения нужно выполнить? |
| Tests | Как автоматически или вручную доказать корректность? |
| Source of Truth | Место, где хранится актуальное утвержденное знание проекта. |
Схема уровней
Feedback после реализации может обновить specification, architecture или system requirements. Например, если во время password reset обнаружили новое стабильное security rule, его нужно записать в соответствующий документ, а не оставлять в transcript.
Что хранится на каждом уровне
Vision
Vision задает направление продукта.
Пример:
Мы создаем SaaS Task Manager для небольших команд,
который помогает прозрачно управлять задачами,
проектами и ответственностью.
Agent редко нуждается в Vision для маленькой coding task. Но Vision важна при product decisions и prioritization.
PRD
PRD описывает product capabilities и ожидаемые outcomes.
Пример:
Пользователь может восстановить доступ к аккаунту,
если забыл пароль.
PRD шире feature spec. Он может включать мотивацию, personas, success metrics и high-level scope.
System Requirements
System Requirements фиксируют требования, которые действуют на систему в целом.
Примеры:
Все user-facing timestamps отображаются в timezone пользователя.
Все security-sensitive actions пишутся в audit log.
API errors используют единый формат error.code/message.
Такие требования могут влиять на многие feature specs.
Architecture
Architecture описывает устройство системы и constraints.
Пример:
HTTP controllers не обращаются к database напрямую.
Business logic находится в services.
Persistence logic находится в repositories.
Это не feature behavior, а ограничение пространства решений.
Feature Specification
Feature Specification описывает поведение конкретной фичи.
Пример:
Password reset token действует 15 минут,
может быть использован один раз,
и при успешном reset старые sessions инвалидируются.
Именно этот уровень мы детально оформим в следующем уроке.
Implementation Plan
Implementation Plan описывает технический путь реализации.
Пример:
1. Добавить ResetToken model.
2. Добавить ResetTokenRepository.
3. Добавить PasswordResetService.
4. Добавить endpoints.
5. Добавить tests.
Plan не должен подменять specification. Он отвечает на "как", а не "что".
Tasks
Tasks - это маленькие единицы работы для агента.
Пример:
TASK AUTH-003:
Добавить repository method для создания reset token.
Allowed scope:
src/auth/reset-token.repository.ts
tests/auth/reset-token.repository.test.ts
Tests
Tests доказывают, что реализация соответствует acceptance criteria.
Пример:
expired token -> 400 TOKEN_EXPIRED
consumed token -> 400 TOKEN_USED
valid token -> password changed
Как выбирать контекст для agent run
Не нужно каждый раз давать агенту всю иерархию. Контекст зависит от задачи.
| Задача | Дать агенту |
|---|---|
| Принять product decision | Vision, PRD, relevant feature spec, open questions |
| Написать feature spec | PRD, system requirements, glossary, related specs |
| Написать design | Feature spec, architecture docs, relevant ADR |
| Выполнить task | Current task, feature spec sections, design section, relevant code |
| Написать test | Acceptance criteria, test conventions, relevant existing tests |
| Сделать review | Specification, diff, architecture constraints, test evidence |
Хороший context engineering начинается с понимания, где лежит нужное знание.
Почему chat history не source of truth
Chat удобен для работы, но плох как единственное место хранения решений.
Проблемы chat history:
- трудно найти актуальное решение;
- неясно, какие assumptions были утверждены;
- future agents могут не увидеть старый разговор;
- сложно review'ить изменения требований;
- нельзя надежно связать решение с тестом или ADR.
Правило курса:
Если решение важно для будущей разработки,
оно должно попасть в файл source of truth.
Примеры:
| Решение | Где хранить |
|---|---|
| Token TTL = 15 minutes | specs/password-reset/spec.md |
| Используем server-side refresh tokens | docs/architecture/adr/ADR-...md |
| Controllers не ходят в database | docs/architecture/architecture.md и project rules |
| Endpoint должен возвращать 202 для unknown email | feature spec.md |
| Regression test для consumed token | tests |
Пример распределения product idea
Идея:
Добавить восстановление пароля.
Распределение:
| Уровень | Содержимое |
|---|---|
| Vision | Пользователь не должен терять доступ к рабочему пространству из-за забытого пароля. |
| PRD | Добавить self-service password recovery. |
| System Requirements | Security-sensitive actions пишутся в audit log. |
| Architecture | Auth logic живет в auth service, email отправляется через existing email service. |
| Feature Spec | Token одноразовый, TTL 15 минут, unknown email не раскрывается. |
| Implementation Plan | Model/repository/service/API/UI/tests. |
| Tasks | T1 migration, T2 service, T3 endpoint, T4 tests. |
| Tests | expired token, consumed token, unknown email, happy path. |
Это не значит, что нужно писать огромный документ для каждой мелкой задачи. Но для важной фичи уровень должен быть явным.
Replanning между features
SDD - это не одноразовый ритуал перед первой реализацией. После каждой feature проект немного меняется: появляются новые ограничения, edge cases, reusable patterns, тесты и иногда новые архитектурные решения.
Если не обновлять source of truth после реализации, следующая feature будет проектироваться на старой картине мира. Агент будет читать формально правильные документы, но они уже не будут отражать реальный код и принятые решения.
После завершения feature нужно сделать короткий replanning step:
Feature done
↓
Что изменилось в behavior?
↓
Что изменилось в architecture или constraints?
↓
Какие lessons должны стать rules, ADR, tests или skills?
↓
Какие upcoming features нужно перепланировать?
Пример: команда реализовала password reset и во время review решила, что все security-sensitive действия должны писать audit log. Это уже не частность password reset. Такое правило должно подняться выше:
| Наблюдение после feature | Куда перенести |
|---|---|
| Reset token должен быть одноразовым | Feature spec password reset |
| Все security-sensitive actions пишут audit log | System requirements |
| Audit log реализуется через отдельный service | Architecture / ADR |
| Для auth changes всегда нужны negative tests | Project rules или testing skill |
| Повторяется процедура "добавить secure endpoint" | Skill |
Replanning особенно важен в AI development, потому что agent часто хорошо выполняет локальную задачу, но не всегда сам понимает, что новое знание должно подняться на уровень выше. Это обязанность engineering workflow: превратить локальное решение в устойчивый артефакт проекта.
Минимальный prompt для replanning:
Проанализируй завершенную feature и diff.
Не меняй код.
Определи:
1. какие specs нужно обновить;
2. нужен ли ADR;
3. появились ли новые project rules;
4. появились ли reusable skills;
5. какие tests стоит добавить в regression suite;
6. какие upcoming tasks стали неактуальны.
Верни список proposed documentation updates.
Практика: разложить идею по уровням
Возьмите product idea:
Пользователь может приглашать участников в команду.
Заполните таблицу:
Vision:
PRD:
System Requirements:
Architecture:
Feature Specification:
Implementation Plan:
Tasks:
Tests:
Не пишите полный документ. Для каждого уровня достаточно 2-4 пунктов.
Итоговый артефакт:
labs/02-spec-hierarchy/team-invites-hierarchy.md
Типичные ошибки
Ошибка 1. Делать один гигантский документ
Если в одном файле лежат Vision, implementation plan, task list, logs и random notes, агенту трудно выбрать актуальный контекст.
Ошибка 2. Давать агенту все документы всегда
Большой контекст не гарантирует качество. Часто он добавляет шум. Для task нужен релевантный subset.
Ошибка 3. Хранить architecture decision в feature spec
Feature spec может ссылаться на ADR, но фундаментальные architecture decisions должны жить отдельно.
Ошибка 4. Писать tasks до specification
Tasks без specification превращаются в список догадок о реализации.
Ошибка 5. Не обновлять source of truth после решения
Если clarification resolved, решение нужно перенести в spec. Иначе следующий агент снова задаст тот же вопрос или выберет другой вариант.
Критерии готовности
После урока студент должен уметь:
- назвать уровни specification hierarchy;
- объяснить, какой вопрос закрывает каждый уровень;
- выбрать нужный context для agent run;
- объяснить, почему chat history не является source of truth;
- распределить product idea по уровням документации.
Краткое резюме
Specification-Driven Development использует не один документ, а систему source of truth:
Vision -> PRD -> Requirements -> Architecture -> Feature Spec -> Plan -> Tasks -> Tests
Эта иерархия помогает держать product intent, behavior, architecture constraints и implementation work на своих местах.
Агенту не нужно видеть все документы всегда. Но нужный уровень должен существовать и быть доступен, когда он влияет на задачу.
Вопросы для самопроверки
- Чем Vision отличается от Feature Specification?
- Где нужно хранить architecture decision?
- Почему chat history не подходит как source of truth?
- Какие документы нужны агенту для выполнения маленькой implementation task?
- Что происходит, если tasks написать до specification?
Что дальше
Теперь мы знаем, где живет feature specification в общей иерархии. В следующем уроке мы разберем конкретный шаблон spec.md, который можно использовать для фичи уровня Password Reset.