Руководство SENAR: Инженерия требований для AI-нативной разработки

Почему требования важнее при работе с AI

В традиционной разработке расплывчатое требование приводит к диалогу: «Вы имели в виду X или Y?» Разработчик спрашивает, уточняет и реализует правильно.

С AI расплывчатое требование приводит к уверенной, правдоподобной реализации — но не того, что нужно. AI не задаёт уточняющих вопросов — он молча выбирает интерпретацию. Код компилируется, проходит тесты, которые AI сам написал (и которые проверяют неправильное поведение), и выглядит корректным при ревью.

Принцип каскада: Дефект в требовании — самый дорогой дефект. Он порождает код, который выглядит правильно, но решает не ту задачу; тесты, которые выглядят правильно, но проверяют не то поведение; документацию, которая выглядит правильно, но описывает не ту систему. Каждый последующий артефакт наследует исходный дефект.

Вот почему первая ценность SENAR — «Контекст важнее кода», и требования — это важнейший контекст.

Три уровня

SENAR определяет три уровня требований. Не все нужны для каждой задачи — глубина зависит от сложности и размера команды.

BR — Бизнес-требование

Что: Потребность уровня заинтересованных сторон, выраженная в бизнес-терминах. Кто пишет: Стейкхолдер, Product Owner или Контекстный архитектор. Где хранится: Цель инкремента, цель эпика или выделенная запись BR в базе знаний.

Примеры:

• «Пользователи должны иметь возможность сбросить пароль без обращения в поддержку»
• «Система должна обрабатывать заказы в течение 30 секунд при пиковой нагрузке»
• «API должен поддерживать OAuth 2.0 для интеграций с третьими сторонами»

Свойства: Хороший BR:

• Бизнес-ориентирован (без деталей реализации)
• Проверяем (можно определить, удовлетворяет ли система требованию)
• Независим (достижим без предварительного решения другого BR, либо зависимость явно указана)

SR — Системное требование

Что: Требование уровня системы, выведенное из BR. Описывает, что система должна делать, а не как. Кто пишет: Контекстный архитектор (Командная+) или Супервайзер (Базовая) (Core). Где хранится: Цель истории или выделенная запись SR, связанная с родительским BR.

Примеры (выведены из BR «сброс пароля»):

• «POST /auth/reset-password отправляет ссылку для сброса на email пользователя»
• «Ссылка для сброса действительна 1 час»
• «Пользователь может установить новый пароль по действительному токену сброса»
• «Система логирует все попытки сброса пароля для аудита безопасности»

Свойства: Хороший SR:

• Достаточно конкретен для декомпозиции на задачи
• Прослеживается до родительского BR
• Тестируем на уровне системы (интеграционный или E2E-тест)

TR — Требование к задаче

Что: Требование уровня реализации. Напрямую соответствует цели задачи и критериям приёмки. Кто пишет: Супервайзер. Где хранится: Поля цели задачи + критериев приёмки.

Пример (выведен из SR «POST /auth/reset-password»):

• Цель: Реализовать эндпоинт POST /auth/reset-password
• Критерии приёмки:
  1. Возвращает 200 и отправляет email для существующего пользователя
  2. Возвращает 200 для несуществующего пользователя (без утечки информации)
  3. Возвращает 422, если поле email отсутствует
  4. Токен сброса криптографически случаен, 32 байта
  5. Токен хранится в БД в хешированном виде (не открытым текстом)
  6. Ограничение частоты: 3 запроса на email в час

Свойства: Хороший TR (= хорошие критерии приёмки):

• Независимо проверяем (каждый критерий можно протестировать отдельно)
• Содержит хотя бы один негативный сценарий (случай ошибки)
• Описывает поведение, а не реализацию («возвращает 422», а не «используй Pydantic-валидатор»)

Тестовая модель (TM) — мост верификации

Тестовая модель — НЕ четвёртый уровень требований. Это артефакт верификации, выведенный из требований к задаче.

BR → SR → TR → [TM] → Код + Тесты
                 ↑ требование    ↑ артефакт верификации

Что содержит тестовая модель:

• Тестовые случаи для каждого критерия приёмки (что тестировать)
• Тестовые данные (граничные значения, ошибочные входные данные)
• Ожидаемые результаты (как выглядит «пройдено»)
• Метод верификации (автоматический юнит-тест, интеграционный тест, ручная демонстрация, замер)

В AI-нативной разработке AI обычно генерирует тесты вместе с кодом. Опасность: AI выдаёт тесты, которые проходят, но на самом деле не проверяют заявленные критерии приёмки. Тестовая модель — это проверка Супервайзером того, что сгенерированные тесты соответствуют требованиям, а не просто набирают покрытие.

Почему не уровень требований? Тестовые случаи описывают как верифицировать, а не что система должна делать. Это следует ISO/IEC 29119 (тестирование ПО), который отделяет проектирование тестов от требований. Превращение TM в уровень требований заставило бы пользователей Базовой (Core) управлять 4 уровнями — накладные расходы, убивающие внедрение.

Свойства качества требований

Проверяемость на практике

Плохо: «Система должна быть быстрой» — быстрой по чьим стандартам? Хорошо: «Время ответа API < 200 мс на p95 при 100 одновременных пользователях»

Плохо: «Обработка ошибок должна быть надёжной» — что значит «надёжной»? Хорошо: «Все API-эндпоинты возвращают структурированные ответы об ошибках с HTTP-статусом, кодом ошибки и понятным человеку сообщением»

Плохо: «Интерфейс должен быть удобным для пользователя» — неизмеримо. Хорошо: «Новый пользователь может завершить процесс регистрации менее чем за 2 минуты без посторонней помощи»

Шаблоны критериев приёмки для типовых задач

REST API эндпоинт

1. Возвращает ожидаемый статус-код и тело для валидного ввода
2. Возвращает 401/403 для неавторизованного/запрещённого доступа
3. Возвращает 422 с описательной ошибкой для невалидного ввода
4. Возвращает 404 для несуществующего ресурса
5. Ответ соответствует задокументированной схеме
6. Ограничение частоты применено согласно конфигурации

Миграция базы данных

1. Миграция идемпотентна (безопасно повторяемая)
2. Откатная миграция существует и работает
3. Нет потери данных при миграции
4. Миграция завершается за приемлемое время для объёма продакшен-данных
5. Индексы созданы для новых паттернов запросов

UI-компонент

1. Корректно отображается в целевом диапазоне viewport (320–1920px)
2. Доступен: навигация с клавиатуры, совместимость со скринридером (WCAG AA)
3. Обрабатывает состояния загрузки, пустоты и ошибки
4. Адаптирован к теме/тёмному режиму, если применимо

Интеграция / внешний API

1. Корректно обрабатывает успешный ответ
2. Обрабатывает таймаут (настраиваемый, по умолчанию 5 с)
3. Обрабатывает ответ с ошибкой со структурированным описанием
4. Политика повторных попыток для транзиентных ошибок
5. Учётные данные не зашиты в код (env/config)

Инфраструктура / DevOps

1. Изменение конфигурации обратимо
2. Эндпоинт проверки здоровья обновлён, если применимо
3. Мониторинг/алертинг покрывает изменение
4. Документация обновлена (runbook, архитектурная диаграмма)

Антипаттерны

Вакуум спецификации

Проблема: У задачи есть цель, но нет критериев приёмки. AI производит нечто, что «выглядит правильно», но никто не может это проверить. Решение: Каждая задача ОБЯЗАТЕЛЬНО имеет критерии приёмки (QG-0). Нет критериев — нет старта.

Избыточная спецификация

Проблема: 20 критериев приёмки для тривиальной задачи. Накладные расходы превышают ценность. Решение: Соотносить глубину критериев со сложностью задачи. Тривиальная: 2–3 критерия. Сложная: 5–8 критериев. Если нужно 15+, задачу следует разделить.

Копирование критериев

Проблема: Одни и те же критерии копируются между задачами без адаптации. «Возвращает 200» повсюду, хотя некоторые эндпоинты должны возвращать 201 или 204. Решение: Использовать шаблоны как отправную точку, затем адаптировать. Шаблоны экономят время; слепое копирование создаёт баги.

Непрослеживаемые требования

Проблема: Задачи существуют без связи с причиной их существования. При смене приоритетов никто не знает, какие задачи можно отбросить. Решение: Каждая задача связана с историей или BR (правило 9.10). Если не можешь объяснить, зачем задача существует, — вероятно, она не нужна.

Двусмысленные критерии

Проблема: «Система должна правильно обрабатывать граничные случаи.» Какие граничные случаи? Что значит «правильно»? Решение: Назвать конкретные граничные случаи. «Система возвращает 409 при дублировании email. Система возвращает 413 при превышении файлом 10 МБ. Система возвращает 429 при превышении лимита запросов.»

Масштабирование по конфигурации

Требования-как-код (Корпоративная)

На Корпоративном уровне требования управляются с той же дисциплиной, что и код: версионируются, рецензируются, проверяются CI.

Что это значит

requirements/
  BR-001-oauth.md          # Бизнес-требование
  SR-001-google-oauth.md   # Системное требование (связано с BR-001)
  SR-002-token-refresh.md  # Системное требование (связано с BR-001)

Каждый файл требования содержит:

• Уникальный ID и заголовок
• Уровень (BR/SR)
• Ссылку на родителя (SR → BR)
• Статус (черновик/утверждено/верифицировано/устарело)
• Историю версий (git log)
• Ссылки на дочерние элементы (BR → список SR, SR → список слагов задач)

Требования к задачам (TR) остаются в трекере задач как цель + критерии приёмки — им не нужны отдельные файлы, потому что они И ЕСТЬ задача.

Проверки CI для требований

Библиотека требований и повторное использование

Проверенные требования (статус: верифицировано, успешно использованы в N проектах) становятся записями библиотеки:

library/
  patterns/
    rest-api-endpoint.md    # Шаблон: критерии для любого REST-эндпоинта
    db-migration.md         # Шаблон: критерии для любой миграции
    auth-integration.md     # Шаблон: критерии для потоков авторизации

Новый проект импортирует паттерн из библиотеки, параметризирует его и получает проверенные критерии приёмки, протестированные на нескольких реализациях. Это напрямую улучшает First-Pass Success Rate — AI получает проверенный боем контекст вместо черновых требований.

Когда внедрять

Требования-как-код добавляют накладные расходы. Они окупаются, когда:

• 10+ пар Супервайзер+AI разделяют требования между проектами
• Регуляторные требования предполагают аудиторский след (ISO 9001, ASPICE, медицинские устройства)
• Кросс-проектное повторное использование требований — стратегическая цель
• Требования меняются часто и нужен анализ влияния

Для SENAR Core и большинства Командных конфигураций требований в трекере задач и базе знаний достаточно.