Сохраняйте прослеживаемость требований при изменении ПО

Опишите поведение, которое можно проверить

Фраза «Создайте современный экспорт клиентов» оставляет важные решения открытыми. Она не определяет пользователей, записи, поля или поведение при сбоях. Агенту придётся задать вопросы или принять допущения. Если допущения не записаны, проверить их позже трудно.

Рассмотрим вымышленное требование с чёткими границами: аутентифицированный руководитель может экспортировать активных клиентов только своей организации. Экспорт содержит идентификатор клиента и отображаемое имя. Контактные данные и архивные записи в него не входят. Пользователь без роли руководителя не получает экспорт.

Ещё предстоит определить формат, объём, время ответа и обработку сбоев. Явно отмечайте неизвестное. Полезная спецификация показывает неопределённость, а не скрывает её за уверенными формулировками.

Отделяйте требования от решений по реализации

Пользователю нужен разрешённый набор записей в удобном формате. Запрос к базе данных, библиотека и структура endpoint относятся к реализации. Свяжите их с требованием, но не считайте каждый текущий выбор постоянной потребностью бизнеса.

Зафиксируйте существенное решение вместе с контекстом, альтернативами и обоснованием. Например, синхронный экспорт может подходить для небольших объёмов. При большем объёме может понадобиться фоновая задача и отдельная проверка права на скачивание.

По возможности сохраняйте требование неизменным, а изменённое решение записывайте как новую версию. Это помогает проверяющим отличить другой способ реализации от нового обещания пользователям.

Создайте короткую цепочку подтверждений

Используйте идентификаторы, понятные при review. В этом примере EXPORT-01 может обозначать границу организации. Это пример обозначения, а не обязательная система нумерации.

Цепочка должна вести к реальным подтверждениям. Идентификатор требования в названии теста ещё не доказывает, что тест проверяет это требование. Изучите проверяемое условие и код production, который выполняется в тесте.

SSDF от NIST описывает роль требований и проверок в безопасной разработке. Используйте прослеживаемость, чтобы эти действия можно было проверить, а не ради самой документации. Прочитать документ.

Оцените влияние изменённого допущения

Предположим, бизнесу теперь нужны архивные клиенты. Это изменение затрагивает не только флаг в запросе. Проверьте правила хранения, авторизацию, ожидаемый объём, пояснения для пользователей и смысл существующих отчётов.

Отметьте затронутые документы и проверки для пересмотра. Сохраните прежнее решение, чтобы специалист по эксплуатации мог объяснить поведение старого релиза. Не переписывайте историю без пояснений так, будто нынешнее решение было единственно возможным.

Агент может помочь найти ссылки и предложить обновления. Ответственные владельцы должны разрешить противоречия между требованиями и принять изменённое поведение. Список совпавших файлов — отправная точка, а не полная оценка влияния.

Ведите записи так, чтобы ими было удобно пользоваться

Записывайте решения, которые влияют на реализацию, проверку и эксплуатацию. Не повторяйте одно требование во множестве несвязанных документов. Лучше ссылайтесь на один источник, который поддерживается в актуальном состоянии.

Прежде чем принять изменение, проверьте, может ли рецензент проследить его назначение до реальных подтверждений. До начала эксплуатации проверьте, может ли владелец сервиса найти нужное ограничение и решение по восстановлению. Эти вопросы помогают оценить практическую пользу прослеживаемости.