Один источник может выглядеть однозначным, пока не спросишь, какое решение он должен поддержать.
В синтетическом учебном кейсе Acme Pay официальная документация v2.1 — базовый источник по API. Рядом есть старая wiki и код прототипа на v1, а ещё письмо поддержки с операционным уточнением. Смысл карты источников в том, чтобы не сложить всё это в одно «самое вероятное» правило.
Самый наглядный пример — срок жизни токена. В документации фигурирует 24 часа, в письме поддержки — 4 часа. Это не повод выбрать меньшее число «на всякий случай» и не доказательство, что письмо автоматически обновило контракт. Оба утверждения нужно сохранить рядом, указать их статус и передать вопрос владельцу источника — службе поддержки Acme Pay или роли, которая отвечает за контракт. Пока подтверждения нет, вопрос остаётся открытым.
Так же бывает и с рабочими требованиями. Один и тот же абзац можно прочитать как описание поведения, как обязательное ограничение или как пример. Если не записать владельца, дату и границу применимости, агент легко соберёт цельный вывод из разных интерпретаций.
Я проверяю такие места в три шага.
1. Что именно утверждает источник? Нужна короткая формулировка, а не пересказ всего документа. 2. На какой вопрос источник имеет право отвечать? Документация задаёт контракт, письмо может уточнить операционную деталь, а устная договорённость о сроках не становится принятой только потому, что её кто-то произнёс. 3. Какой вопрос остаётся открытым после прочтения? Его нужно передать названному владельцу и сохранить до решения.
В Acme Pay остаются и другие пробелы: не описано поведение при недоступности провайдера, а требования к логированию и хранению данных не покрыты источниками. Это не приглашение заполнить пропуски «хорошей практикой». Это список вопросов, которые меняют архитектуру и должны получить решение до реализации.
Смысл карты источников не в том, чтобы выбрать самый уверенный вариант. Она сохраняет конфликт до тех пор, пока человек с нужным правом не примет решение. Только после этого агенту можно передавать задачу, в которой уже видны версия правила, граница действия и критерий приёмки.
