8 октября 2026 г.

Обновление кода — это обычно самая простая часть обновления API. Все, что происходит после этого, становится сложным. Какие эндпоинты изменились? Соответствует ли коллекция Postman текущему API? Все ли согласуется с контрактом? И нужно ли обновлять CI/CD-конвейер?

Если упустить что-то из этого, вы получите коллекцию, которая выглядит правильной, но таковой не является. Затем ее открывает другой разработчик, полагаясь на нее, и тратит время на попытки понять, почему ничего не работает.

Я хотел проверить, сможет ли агент справиться со всем этим рабочим процессом, используя плагин Claude Code Postman и Context Graph. Поэтому я прошел весь путь с Claude от начала до конца:

Я сделал все это с помощью простых текстовых запросов в терминале. Мне не пришлось просматривать эндпоинты один за другим, создавать отдельные тикеты для обновления коллекции или возвращаться позже, чтобы добавить тесты в CI. Claude выполнил этот рабочий процесс как одну связанную задачу.

Настройка плагина

Давайте настроим плагин. Это нужно сделать только один раз.

Сначала установите плагин:

Это установит плагин Postman из официального маркетплейса Claude Code и сделает его возможности доступными для Claude. Он еще не подключен к вашему репозиторию или рабочему пространству Postman. Вы просто устанавливаете инструменты.

Затем перейдите в репозиторий, с которым хотите работать, и выполните:

Это и есть фактический шаг настройки. Он выполняет несколько действий за вас:

Устанавливает Postman CLI, если он у вас еще не установлен
Открывает браузер, чтобы вы могли войти в Postman, или использует POSTMAN_API_KEY, если он у вас уже задан
Запрашивает, к какому рабочему пространству Postman вы хотите подключиться
Создает файл .postman/resources.yaml с идентификатором рабочего пространства, директорией коллекций и путем к спецификации API

Этот файл .postman/resources.yaml связывает все воедино. Любая другая возможность плагина, включая обнаружение, тестирование, мокирование и интеграцию с CI, проверяет его перед выполнением какой-либо работы.

Затем откройте Claude Code и найдите в списке возможностей «postman»:

Вот полный список из 13 возможностей и описание того, что делает каждая из них:

postman:api-engineer: Основная точка входа для работы с API: проектирование, реализация, мокирование, тестирование, мониторинг, документирование или развертывание API. Вы будете использовать ее чаще всего, и она передает задачу соответствующему специалисту, который лучше всего подходит для запроса.
postman:bootstrap: Находит Postman CLI, выполняет аутентификацию, когда это необходимо для задачи, и управляет файловой системой и привязкой рабочего пространства для репозитория. Это то, что запускается при выполнении postman init, и любая другая возможность зависит от того, была ли она уже выполнена.
postman:api-discovery: Обнаруживает и использует API из интернета или Postman. Находит и интегрирует публичные сторонние API с Orbit, находит сущности Postman с помощью поиска и использует Context Graph для исследования зависимостей, владения, поведения во время выполнения и влияния изменений на экосистему API.
postman:api-testing: Запускает тесты для API из командной строки: одиночный запрос, полная коллекция тестовых утверждений или сопоставление реального перехваченного трафика приложения с контрактом коллекции.
postman:api-mocking: Создает фиктивный бэкенд, который ведет себя как настоящий API, на основе коллекции или спецификации OpenAPI, работающий локально или опубликованный в облаке Postman для получения постоянного URL, а также поддерживает переопределение сценариев и кодов состояния во время запроса для тестирования путей с ошибками.
postman:ci-integration: Общие интеграции CI, которые можно добавить как независимые шлюзы проверки: запуск коллекции при каждом pull request, прерывание сборки при нарушении правил или отправка в облачное рабочее пространство после слияния с веткой main.
postman:api-monitoring: Создает, планирует и управляет мониторами Postman — периодическими проверками работающего API, включая разовые запуски, историю запусков для диагностики сбоев и собственные раннеры для API, находящихся за частной сетью.
postman:ai-readiness: Оценивает коллекцию или спецификацию OpenAPI на предмет того, насколько хорошо агент ИИ может обнаруживать, понимать, вызывать их и восстанавливаться после ошибок. Отсутствующие примеры, недокументированные ошибки и неоднозначные параметры снижают оценку.
postman:api-documentation: Генерирует удобную для агентов документацию API на основе коллекции или спецификации, готовую для передачи остальной команде.
postman:performance-testing: Проводит нагрузочное тестирование коллекции с помощью параллельных виртуальных пользователей, выбранного профиля нагрузки и пороговых значений для задержки или частоты ошибок, запускаемое локально или на облачных раннерах Postman.
postman:flows: Запускает, развертывает и отлаживает Postman Flows из командной строки, включая отслеживание неудачного запуска до конкретного блока, который вызвал ошибку.
postman:collection-schema-v3: Не является инструментом для прямого вызова. Это справочник, который используют другие возможности перед записью или редактированием файла коллекции вручную, или перед отладкой ошибки линтинга.
postman:postman-mcp-server: Также не является инструментом для прямого вызова. Фоновые знания о концепциях Postman и выборе инструментов MCP, которые загружаются автоматически, когда это требуется другой возможности.

Вы заметите, что ни один из запросов в этой статье не вызывает эти возможности по имени. Это сделано намеренно. Вы говорите Claude, что хотите сделать, а postman:api-engineer передает работу тому специалисту, который действительно подходит.

Запрос к Context Graph

Мое приложение сильно изменилось. Теперь во фронтенде были интеграции с Nylas для синхронизации календаря и Notion для заметок к встречам, а также новый процесс приглашения на встречу. В коллекции Postman ничего из этого не было.

Поэтому я спросил Claude:

Проверь мою коллекцию на соответствие Context Graph. Убедись, что коллекция отражает все новые и обновленные эндпоинты.

Проверь мою коллекцию на соответствие Context Graph. Убедись, что коллекция отражает все новые и обновленные эндпоинты.

Claude отправил запрос к возможности обнаружения, которая обратилась к Context Graph. Она обнаружила несколько проблем разного рода:

Nylas отображался как известный внешний сервис, но в графе еще не было данных об эндпоинтах для него. Notion вообще отсутствовал в графе.
Во фронтенде существовали три маршрута, для которых не было соответствующих запросов в коллекции: процесс приглашения на встречу, интеграция с Nylas и интеграция с Notion.
Запрос на отмену встречи существовал, но он устарел и больше не соответствовал обработчику маршрута.
Другие запросы, включая подтверждение встречи и синхронизацию встречи, уже соответствовали коду. Claude оставил их без изменений.

Это та работа, которая легко может занять целый день. Вы ищете во фронтенде каждый вызов fetch, сравниваете каждый из них с коллекцией и надеетесь, что заметите эндпоинт, который кто-то переименовал шесть недель назад.

Context Graph дал Claude гораздо лучшую отправную точку. Он смог сравнить содержимое коллекции с маршрутами и сервисами, уже подключенными в графе, а затем сосредоточиться на пробелах. В статье «Introducing the Context Graph API» объясняется, как строится эта карта.

Однако здесь есть важное различие. Граф не предоставил Claude набор фактов для прямого копирования в коллекцию. Он дал Claude список вероятных пробелов. Claude все равно открыл обработчики маршрутов и проверил каждый из них перед созданием или изменением каких-либо запросов.

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

Устранение пробелов и проверка коллекции

Как только у Claude появился список того, что отсутствовало или устарело, он спросил, хочу ли я, чтобы он исправил коллекцию. Я ответил «да», но также попросил его проверить работу на соответствие контракту API:

Да, сделай это и проверь всё на соответствие контракту API.

Да, сделай это и проверь всё на соответствие контракту API.

Добавление недостающих запросов приводит коллекцию в актуальное состояние, а проверка их на соответствие контракту гарантирует, что методы, параметры и тела запросов действительно соответствуют тому, что ожидает API. Claude проработал пробелы один за другим. Он добавил недостающий запрос на приглашение на встречу, обновил устаревший запрос на отмену встречи, добавил запросы для интеграции с Nylas и Notion, а также создал окружение (Environment) с переменными, необходимыми для этих интеграций.

Новый запрос на приглашение на встречу выглядел примерно так:

Как только всё оказалось в коллекции, Claude запустил проверку схемы:

Здесь есть небольшое, но важное различие. postman collection lint проверяет, соответствует ли коллекция схеме коллекции Postman v3. Другими словами, он гарантирует, что файл структурирован правильно и Postman может его понять.

Это не доказывает, что коллекция соответствует API.

Claude проверил это отдельно, сравнив каждый фронтенд-маршрут с коллекцией. Теперь каждый маршрут был сопоставлен с одним запросом с тем же методом, параметрами и структурой тела, что и у обработчика.

Итак, к этому моменту я знал две вещи: коллекция представляет собой валидный JSON для Postman, и она соответствует коду. Следующим шагом была проверка её на соответствие тому, что приложение отправляет на самом деле.

Добавление тестов, подтверждение их работы и внедрение в CI

Теперь, когда коллекция соответствовала коду и имела заглушку (mock) для тех частей, которые еще не были запущены, мне нужны были тесты, которые доказали бы это, а не просто описали:

Напиши тесты для всех новых эндпоинтов и добавь их все в CI/CD конвейер.

Напиши тесты для всех новых эндпоинтов и добавь их все в CI/CD конвейер.

Навык интеграции с CI взял запрос и применил навык создания заглушек там, где это было необходимо.

Сначала Claude добавил тестовые скрипты к каждому новому и обновленному запросу. Запрос на подключение Nylas начался с пары базовых проверок:

Он добавил такое же покрытие для запросов к встречам, Nylas и Notion. Затем он добавил утверждения (assertions) на уровне контракта, которые проверяют фактическую структуру ответа:

Перед запуском этих тестов в реальном окружении Claude сгенерировал заглушку из коллекции, используя навык api-mocking.

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

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

Как только тесты прошли проверку на заглушке, Claude добавил запуск коллекции в GitHub Actions, используя навык ci-integration:

Именно здесь рабочий процесс перестал быть чем-то, что я запускал один раз в своем терминале. postman collection run теперь запускает ту же коллекцию и тестовые скрипты при каждом соответствующем pull request.

Claude протестировал команду CI локально, прежде чем что-либо коммитить. Затем он закоммитил новые запросы, обновленный запрос на отмену встречи, окружение, тестовые скрипты и рабочий процесс GitHub Actions перед открытием pull request.

Финальный PR охватил все изменения, а не только фронтенд-код. Коллекция теперь включала запросы для Nylas, Notion и встреч. Все 12 запросов имели тестовые утверждения и сохраненные примеры. А задание CI было готово перехватить следующее изменение, которое привело бы к расхождению кода, коллекции и контракта.

К чему это вас приводит

Ни один из этих шагов не является новым. Вы уже могли вручную проверить коллекцию, создать заглушку API, написать тесты и обновить CI. Разница в том, что Claude справился со всем рабочим процессом по одному запросу, в правильном порядке, не гадая, чего не хватает.

Вот где важен Context Graph. Агент, читающий один репозиторий, может видеть только то, что находится в этом репозитории. Он не может знать, что фронтенд выпустил эндпоинт, который так и не попал в коллекцию, или что существующий запрос рассинхронизировался.

Плагин дает Claude инструменты для решения этих проблем. Context Graph подсказывает ему, где находятся проблемы. Без графа Claude мог бы проверить неполную коллекцию и получить чистый результат, потому что линтинг проверяет, является ли файл валидным, а не отражает ли он реальный API.

Попробуйте это с изменением, которое, как вы знаете, ваша коллекция пропустила: