системный анализ · 6 минут
Документация API, Wiki и письмо поддержки расходятся: что решить до разработки
В интеграционных проектах проблема часто начинается не с плохого кода. Она начинается с нескольких документов, каждый из которых выглядит достаточно убедительно.
Ниже — синтетический пример, не клиентский результат.
Четыре источника, одна интеграция
Команда переводит интеграцию с платёжным провайдером Acme Pay с API v1 на v2.1. В папке лежат четыре материала:
| Источник | Что в нём полезно | Ограничение |
|---|---|---|
| Официальная документация v2.1 | текущий контракт API | требует проверки владельца контракта |
| Wiki «Интеграция v1» | история старой реализации | описывает прошлую версию |
| Репозиторий прототипа | реальные решения в коде | прототип не равен действующему контракту |
| Письмо поддержки | уточнение ограничения | не заменяет официальный контракт |
В документации и Wiki расходятся детали авторизации и идентификатора клиента. Репозиторий повторяет старую реализацию. Письмо поддержки уточняет срок жизни токена и лимит частоты запросов, но не становится из-за этого новой спецификацией.
Если просто передать все четыре файла агенту, он соберёт связный ответ. В нём могут одновременно оказаться несовместимые детали авторизации, старый адрес API и ограничение из письма. Текст будет выглядеть профессионально, пока разработчик не попробует выполнить его.
Сначала карта источников, затем решение
До постановки задачи я фиксирую для каждого источника пять полей: идентификатор, дату, владельца, статус и область действия.
Это не превращает самую свежую запись в истину автоматически. Дата помогает увидеть устаревший материал, владелец — найти право на решение, статус — отличить действующий контракт от архива, область действия — не перенести ограничение одного потока на всю систему.
После такой инвентаризации появляется очередь решений:
- какой способ авторизации действует в v2.1;
- какой адрес API должен использоваться;
- где хранится токен и как проверяется его срок жизни;
- какие ограничения запросов должны попасть в сценарий;
- кто принимает результат, если источники не удаётся согласовать.
Пока эти вопросы открыты, агент может подготовить варианты, но не должен выбирать «самую гладкую» версию.
Связь решения с проверкой
Каждое принятое решение должно вести к проверяемому сценарию. Если владелец подтверждает новую схему авторизации, меняются не только конфигурация и один тест.
Затрагиваются получение токена, обработка истечения срока, повтор запроса, журналирование и секреты в окружении. Старый тест может остаться зелёным, потому что он проверяет прежний путь.
Поэтому я связываю три объекта:
источник → решение → проверка.
Изменился источник — проверяю, какие решения на нём основаны. Изменилось решение — отмечаю зависимые сценарии и тесты. Только после этого повторяю приёмку.
Удобный минимальный журнал выглядит так:
| Источник | Решение | Проверка | Состояние |
|---|---|---|---|
| S01 + S04 | Какой срок жизни токена действует: 24 часа или 4 часа? | Истечение, повторная авторизация и отказ | UNKNOWN до ответа поддержки |
| S01 против S03 | Реализовать проверку подписи вебхука по S01 | Неверная подпись отклоняется | Решение ясно; реализация и проверка не подтверждены |
| S01 | Параметры retry policy не заданы | Проверка отказа и повторов | UNKNOWN до уточнения G01 |
Такой журнал не маскирует пробелы. Он показывает, какое решение ещё нельзя превращать в обязательный тест и кто должен закрыть вопрос.
Что делать агенту, а что оставить человеку
Агент полезен для инвентаризации: он может найти цитаты, сравнить версии, построить список зависимостей и показать противоречия. Он может подготовить несколько вариантов тестов.
Но он не должен сам объявлять источник авторитетным, закрывать конфликт или принимать риск за владельца продукта. Это граница между исполнением и решением.
Практический минимальный протокол выглядит так:
- собрать карту источников;
- выписать противоречия отдельными пунктами;
- назначить владельца каждого решения;
- зафиксировать область действия и дату решения;
- связать решение с изменёнными сценариями и проверками;
- пометить старое свидетельство устаревшим;
- повторить проверку и получить человеческую приёмку.
В синтетическом примере это важнее, чем скорость генерации спецификации. Связный документ не устраняет конфликт источников. Он только делает конфликт менее заметным.
Пока решение не принято, честный результат агента должен содержать открытый вопрос, а не выдуманную определённость.