Source map: карта источников проекта

Привычный путь такой: аналитик получает задачу и садится читать источники подряд. Через день у него в голове усреднённая версия, в которой противоречия слиплись и стали невидимыми. Ощущение понимания есть, проверяемого понимания нет.

Двадцать минут инвентаризации до чтения дают три вещи.

• Дыры видны до анализа. Если требования по безопасности существуют только в письме заказчика, это риск, а не требование.
• Каждое требование получает адрес. Через месяц на вопрос «почему это поле обязательное» ответ занимает пятнадцать секунд по ссылке вместо вечера поисков.
• Расхождения перестают быть сюрпризом. Если документация говорит одно, а вики другое, это не повод выбрать удобное. Это открытый вопрос, который нужно закрыть до старта разработки.

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

Пять колонок:

1. Номер источника. S01, S02 и дальше. На эти идентификаторы аналитик потом ссылается в System Context Pack и Review Findings.
2. Что это и какого типа. Документация вендора, внутренняя вики, код, переписка, устная договорённость.
3. Владелец. Кто отвечает за содержание и к кому идти с вопросом. Отдельно важно, работает ли этот человек в компании.
4. Дата обновления и статус. Актуален, устарел, требует подтверждения.
5. Связи и расхождения. С чем этот источник спорит и что он уточняет.

Первые четыре колонки аналитик заполняет механически, за пять минут. Основное время уходит на последнюю, и она же приносит основную пользу.

Заполнять её приходится не по одному источнику, а парами. Напротив строки S01 появляется запись вида «спорит с S02 по времени жизни токена». Такую строку невозможно написать, читая документы по очереди: она возникает только когда два источника стоят рядом.

Отдельный класс находок — утверждение, которое существует ровно в одном источнике, причём неформальном. Формально расхождения нет, спорить не с чем. Опереться на такую цифру в архитектуре всё равно нельзя.

Учебный кейс: компания переводит платёжную интеграцию с API v1 на v2.1, до старта разработки две недели. Провайдер вымышленный, набор источников типовой.

Колонка расхождений на этом наборе дала шесть открытых вопросов. Три показательных:

• S01 против S04. Документация говорит, что токен авторизации живёт сутки. В переписке с поддержкой указано четыре часа. Разница определяет, как устроено обновление сессии, и всплыла бы на нагрузочном тестировании.
• S01 против S02. Поле customer_id в актуальной версии обязательное всегда, в старой вики только для регулярных платежей. Вики описывает версию, которой больше нет, но команда помнит именно её.
• S04 в одиночку. Ограничение в 100 запросов в минуту упомянуто только в письме поддержки. Письмо не контракт, значит цифра может измениться.

Кроме расхождений карта показала четыре темы, не покрытые ни одним источником: поведение при недоступности провайдера, обработка возвратных платежей, требования регуляторики к логированию и параметры повторной отправки вебхуков. Ни одна не выглядит срочной в первый день. Все четыре обычно всплывают на приёмке, когда менять архитектуру дороже всего.

Составление карты заняло 25 минут, из них 15 на колонку расхождений. Последовательное чтение тех же пяти источников заняло бы день, и три расхождения из пяти остались бы незамеченными.

Полная последовательность метода: source map → System Context Pack → Review Findings → Task Pack.

Source map отвечает на вопрос, чему можно доверять. System Context Pack собирает из источников связную картину системы, где каждое утверждение подкреплено цитатой. Review Findings вытаскивают расхождения, пробелы и риски на поверхность. Task Pack превращает всё это в постановку с открытыми вопросами и критериями готовности.

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

Выписывать только официальные документы. Устная договорённость с продактом тоже источник, и часто самый хрупкий.

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

Закрывать расхождение выбором. Если два документа спорят, брать тот, что нравится, значит переносить проблему на приёмку.

Начинать разработку с открытыми вопросами в карте. Список открытых вопросов существует, чтобы его закрыть до старта, а не чтобы приложить к постановке.