Гайд: организация и развитие требований
Целостные требования описывают, как должен работать продукт: для кого, в каких условиях, с какими результатами и ограничениями. Они дают людям и агентам общую основу для реализации, проверки и оценки последствий изменений.
Отсутствие целостных требований не блокирует внедрение. Начать можно с кодовой базы, трекера и знаний команды. Однако без накопления согласованных правил агент будет снова восстанавливать контекст, задавать одинаковые вопросы и рисковать воспроизводить старые ошибки. Наполнение требований — постоянная работа параллельно PoC и Пилоту, с выделенными участниками и временем.
1. Что берём за основу
Основа — подготовленный для ПОС комплект требований, его руководство и правила источников и связей. Сохраняем два уровня:
| Уровень | На какой вопрос отвечает | Что содержит |
|---|---|---|
| Верхнеуровневое требование (HLR) | Зачем и какой результат нужен пользователю или бизнесу? | Потребность, пользователи, границы возможности, основные сценарии, ожидаемый результат и критерии приёмки |
| Спецификация (REQ) | Как именно продукт обязан вести себя? | Конкретные проверяемые правила, условия, данные, исключения, права, контракты и ограничения |
Группировка по предметным областям помогает навигации и не создаёт дополнительных уровней требований. Архитектура объясняет, как устроено решение; обязательные технические ограничения связываются со спецификацией. Сценарии приёмки, тесты и результаты прогонов показывают, как проверяются правила и что проверено фактически.
Названия HLR/REQ, Markdown, отдельный репозиторий, OpenSpec и инструменты комплекта ПОС не обязательны. Нужны понятные источники, правила изменения, проверяемое содержание и связи. Принятая спецификация описывает целевое поведение; сама по себе она не доказывает, что оно уже реализовано.
2. Если материалы уже ведутся
Не создавайте параллельный комплект только ради внедрения. Аналитик вместе с командой и ИИ-инженером сопровождения:
- Находит действующие источники: базу знаний, спецификации, модели, контракты, макеты, тест-кейсы и решения в задачах.
- Договаривается, какой источник определяет каждое правило и где находится его актуальная версия. Если источники расходятся, заводит вопрос с владельцем решения.
- Проверяет доступ агента: агент должен находить, читать и сопоставлять связанные материалы. Способ внесения правок может быть прямым или через предложение человеку.
- Фиксирует правила ведения и оценивает полноту в области Пилота.
- Включает пробелы и устаревшие разделы в общий план развития артефактов.
Существующая структура может полностью сохраняться. В реестре артефактов достаточно ссылки и краткого сопоставления: где описаны потребности, правила поведения, проверки и изменения. Экспорт или поисковый индекс для агента — производная копия с известной версией и порядком обновления; исправления вносятся в основной источник.
3. Если есть только код и трекер
Агент предлагает начальную карту возможностей по коду, задачам, UI, тестам и обсуждениям. Для каждой восстановленной записи указывает источник и то, что ещё нужно выяснить. Аналитик и назначенные владельцы проверяют предложения по частям, начиная с выбранного потока Пилота.
Наблюдаемое поведение не становится требованием автоматически. Код может содержать дефект, задача — устаревшее решение, а тест — неверное ожидание. Различайте:
- Наблюдение: что продукт делает на указанной версии, со ссылкой на основание.
- Черновик требования: предложение, которое нужно проверить с командой.
- Согласованное правило: ожидаемое поведение, подтверждённое уполномоченным участником.
- Открытый вопрос или допущение: что пока неизвестно, кого спрашиваем и на какие работы это влияет.
Не требуется сначала описывать весь продукт. Создайте карту, подробно разберите ближайшие задачи и наиболее рискованные зависимости, затем расширяйте описание. Исторические задачи остаются источниками и историей изменений; актуальное правило должно находиться без повторного чтения всей переписки. Если команда поддерживает актуальные правила непосредственно в трекере, он может оставаться основным источником.
4. Предлагаемая структура
Для нового комплекта можно использовать такую сокращённую структуру по примеру ПОС. Маленькому проекту достаточно нескольких документов; пустые каталоги создавать не нужно.
| Логическое место | Содержание |
|---|---|
| Карта продукта и глоссарий | Цели, границы, пользователи, предметные области, термины и ссылки на материалы |
| Требования по областям | HLR: возможности и ожидаемые результаты; общие гарантии описываются один раз |
| Спецификации по областям | REQ: правила поведения, исключения и критерии; ссылки на общие модели, права и контракты |
| Предметные модели и контракты | Состояния, таблицы решений, данные, API и события; один актуальный источник каждого определения |
| Архитектура | Принятые решения, зависимости, ограничения и связь с требованиями |
| Приёмка | Сценарии, конкретные проверки, тестовые данные и ожидаемые результаты |
| Вопросы, допущения и решения | Неопределённости, владельцы, сроки, влияние на задачи, принятые ответы и их основания |
| Изменения и влияние | Предлагаемое изменение, затронутые правила и проверки, история принятия |
| Доказательства проверок | Ссылки на результаты с версиями продукта, требований, тестов и данных |
Материалы и изображения хранятся рядом с областью либо по ссылке на управляемый источник. Для приложения указываются назначение, источник/версия и роль: иллюстрация, основание или нормативная часть. Существенные правила должны быть доступны текстом. Один и тот же нормативный текст не копируется в несколько мест.
Начальная карточка HLR: ID, название, цель, пользователи, границы, основные сценарии, ожидаемый результат, критерии приёмки, источник, владелец, статус, связанные REQ.
Начальная карточка REQ: ID, родительский HLR, условия, правило и наблюдаемый результат, существенные исключения, связанные модели/контракты, источник решения, владелец, статус, проверки. Поля можно объединять; важен смысл. Пример показывает обе карточки и связь с тестами.
5. Правила ведения
Команда выбирает удобную форму и фиксирует следующие договорённости:
| Правило | Что определить |
|---|---|
| Источники | Где актуальные требования, спецификации, модели и контракты; как платформе их находит |
| Идентификация | Устойчивые ID или постоянные ссылки; перенос документа не разрушает связи |
| Статусы | Например: черновик, согласовано, выведено из действия; кто и как подтверждает смысл |
| Версии | Какая редакция действует, какие изменения только предложены, где история |
| Ответственность | Кто готовит, кто отвечает за продуктовый выбор и кто проверяет затронутую часть |
| Изменения | Когда обновляются основной текст, проверки и связанные документы; как устраняются противоречия |
| Неопределённость | Где вопросы и допущения, кто отвечает, срок и какие именно задачи зависят от ответа |
| Связи | Потребность → правило → проверка → тест/ручная процедура → результат; задача и MR ссылаются на затронутые правила |
Согласование — обычное содержательное ревью команды; отдельная формальная процедура не требуется. Изменение агентом поля «согласовано» не заменяет решения человека. Статусы требования, реализации и результата проверки хранятся раздельно.
Для конкретной задачи до зависимой реализации должны быть определены существенные условия и ожидаемый результат. Если нужен временный рабочий вариант, уполномоченный участник явно выбирает его, фиксирует риск, срок пересмотра и оставшиеся ограничения. Отсутствие ответа не означает согласия. Независимые задачи продолжаются.
6. Как оценить полноту
Полнота всегда относится к явно указанной области и дате, например «изменения обработки обращений в Пилоте». Процент «требования ко всему продукту заполнены» нельзя получать из числа написанных документов.
Сначала команда составляет карту возможностей и сценариев, включая существенные зависимости. На Подготовке допустима предварительная карта по доступным источникам; неизвестные области отмечаются отдельно. Для каждого сценария проверяется применимость аспектов:
| Аспект | Что ищем в материалах |
|---|---|
| Цель и границы | Пользователь, потребность, ожидаемый результат, что не входит |
| Основной сценарий | Условия начала, действия, результат и побочные эффекты |
| Данные и правила | Обязательность, ограничения, вычисления, состояния и переходы |
| Роли и права | Кто может действовать, какие объекты видит и изменяет |
| Исключения | Ошибки, пустые и граничные значения, частичный успех, восстановление |
| Интеграции и конкуренция | Контракты, недоступность, повторы, дубли, одновременные изменения |
| Время | Таймеры, сроки, календарь, часовые пояса, крайние моменты |
| Интерфейс | Существенные состояния, действия, сообщения и ограничения |
| Качество и изменения | Применимые ограничения по безопасности, нагрузке, совместимости, миграции и эксплуатации |
| Приёмка | Наблюдаемые критерии, сценарии, данные и независимые ожидаемые результаты |
Это список вопросов для проверки применимости. Новые задачи реализации нефункциональных требований не добавляются в Пилот автоматически; действующие ограничения продукта всё равно учитываются.
В форме оценки одна строка — сценарий и применимый аспект. Состояния: не описано / частично / описано и подтверждено. Устаревшее, противоречивое или ещё не проверенное описание не считается подтверждённым. Для «неприменимо» нужны причина и имя подтвердившего.
Можно считать:
Полнота согласованного описания = число применимых позиций «описано и подтверждено» / число всех применимых позиций в зафиксированной карте × 100%.
Рядом показываются числитель, знаменатель, версия карты, неизвестные области и существенные пробелы. При расширении карты изменение знаменателя отражается отдельно: снижение процента не обязательно означает ухудшение. Сценарии и аспекты выбираются до оценки; дробить готовые описания ради процента нельзя. Если карта ещё не обследована, показатель называется предварительным.
Отдельно оцениваются:
- Проверяемость: у скольких согласованных правил определены содержательные проверки с ожидаемым результатом.
- Автоматизация: какие из выбранных проверок имеют поддерживаемые автотесты.
- Фактическая проверка: что запускалось, на какой версии и с каким результатом.
Связь с тест-кейсом сама по себе не доказывает полноту правила, наличие автотеста — успешный прогон, а успешный прогон — правильность ожидания. Не объединяйте эти показатели в один процент. Числовые цели задаются по рискам проекта, универсального проходного процента нет.
7. Как наполнять параллельно внедрению
Сначала выделить сведения, необходимые выбранной первой задаче: их уточняют до зависимой работы, при блокировке онбординга — до его начала. Только остальные пробелы входят в параллельное развитие. Получение контекста и разбор вопросов описаны в порядке Подготовки.
| Когда | Что делаем |
|---|---|
| Подготовка | Находим источники, выбираем правила ведения, составляем предварительную карту и оценку полноты; назначаем владельцев и работы по пробелам |
| PoC, неделя 1 — онбординг | При адаптации каталог исходных материалов подключаем источники требований, фиксируем ответы по развилкам и ожидаемое поведение задачи минимального прохода; проверяем, что агент использует материалы |
| PoC, неделя 2 — простые задачи | Сохраняем найденные правила, исключения и ответы; связываем их с проверками, проверяем удобство выбранного формата |
| PoC, недели 3–4 — целевые задачи | Уточняем карту целевого потока, существенные зависимости и план дополнения на Пилот |
| Пилот, каждую неделю | Пополняем описание по выполненным и ближайшим задачам; отдельно закрываем приоритетные исторические пробелы; фиксируем изменение полноты, оставшиеся вопросы и следующий план |
Используются два способа наполнения: по ходу продуктовых изменений и отдельными работами по восстановлению важных областей. Приоритет получают ближайшие задачи, повторяющиеся вопросы, дефекты из-за неоднозначности и правила с широким влиянием. Агент готовит материалы; люди проверяют смысл и принимают решения в рамках своих полномочий.
У каждой работы есть область, конкретный результат, исполнитель, проверяющий и срок. «Описать весь продукт когда-нибудь» не является планом. Работы попадают в недельный журнал. Затраты учитываются по общим правилам: внутри задачи либо как отдельные затраты внедрения, без двойного учёта.
При изменении продукта агент находит затронутые HLR/REQ, модели, контракты и проверки, предлагает согласованные изменения вместе с реализацией. После ревью обновляется действующее описание; история остаётся доступной. Дефект из-за пропущенного правила становится поводом дополнить и описание, и проверки.
8. Кто отвечает
| Функция | Обязательство |
|---|---|
| Владелец продукта или назначенный предметный эксперт | Подтверждает ожидаемое поведение, решает противоречия и приоритеты |
| Аналитик или участник, выполняющий эту функцию | Ведёт карту и оценку полноты, проверяет предложения агента, поддерживает требования и связи |
| Архитектор и разработчик | Проверяют технические ограничения, влияние на зависимости и контракты, сообщают о расхождениях кода и описания |
| Тестировщик | Проверяет наблюдаемость критериев, сценарии и данные; связывает правила с тест-кейсами и тестами |
| ИИ-инженеры | Обеспечивают работу агента с источниками, подготовку черновиков и обновлений; анализируют повторные пробелы контекста |
| РП внедрения и РП клиента | Включают работы в план, обеспечивают время участников и отслеживают выполнение |
Продуктовую работу организует команда продукта, инженерное сопровождение — ИИ-инженер. В начале внедрения основные инженерные работы ведёт ИИ-инженер сопровождения; они передаются клиенту постепенно. Предметные решения в обеих фазах остаются у назначенных участников клиента. Должности можно совмещать; у каждого результата должен быть конкретный человек.
Полнота требований помогает объяснять эффект внедрения и планировать улучшения. Она не добавляет третьего условия завершения Пилота к основаниям, описанным в процессе внедрения.