22 октября 2026 г.

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

Код, как правило, не самая сложная часть.

Гораздо сложнее ответить на два вопроса до того, как агент начнет писать код:

Какой внешний API действительно справится с задачей?
На что внутри нашей собственной системы повлияет эта интеграция?

Эти вопросы требуют двух совершенно разных типов контекста.

Первый существует за пределами компании. Он рассредоточен по публичной документации API, спецификациям, примерам, руководствам по аутентификации и ограничениям конкретных провайдеров. Второй существует внутри компании. Он распределен по репозиториям, Postman Collections, схемам, срезам времени выполнения, потребителям событий, развертываниям, телеметрии и зонам ответственности команд.

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

Именно здесь Orbit и Postman Context Graph дополняют друг друга.

Orbit помогает агенту найти и понять публичный API, который следует вызывать. Context Graph помогает ему понять частную систему, частью которой скоро станет этот вызов. Плагин Postman Claude Code наделяет агента навыками превращения этого контекста в реальные изменения: обновить коллекцию, проверить контракт, протестировать рабочий процесс и перенести эти тесты в CI.

Проблема шире, чем просто обнаружение API

Предположим, я работаю над myhealthcare.dev, медицинским приложением, которое управляет пациентами, приемами, лекарствами и расписанием.

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

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

Сначала агенту нужно найти внешний API, поддерживающий данный рабочий процесс. Поиска «calendar API» недостаточно. Нам нужно знать, умеет ли API проверять доступность, создавать событие, приглашать участников и правильно связывать эти шаги. Нам также нужны точные поля запроса, требования к аутентификации, структура ответов и ограничения конкретного провайдера.

Затем агенту необходимо понять наше приложение. Какой сервис отвечает за запись на прием? Вызывает ли он другой сервис синхронно или публикует событие appointment.booked? Кто потребляет это событие? Какая спецификация API и коллекция Postman описывают текущий поток? Какие тесты и задачи CI потребуется изменить? Может ли новая проверка календаря добавить задержку для маршрута, используемого другим сервисом, которого у нас нет локально?

Поиск подходящего API не отвечает ни на один из этих внутренних вопросов. Чтение локального репозитория тоже не отвечает на все из них.

В этом и заключается разрыв.

Orbit берет на себя публичную сторону

Orbit by Postman ищет общедоступные API, включая Postman API Network. Вместо того чтобы заставлять агента угадывать провайдера или идти от обратного на основе названий продуктов, я могу описать нужный мне результат простым языком:

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

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

Orbit возвращает кандидатов-эндпоинтов и оценивает, насколько каждый из них подходит для задачи. Как только я выбираю эндпоинты, этап интеграции выдает техническое задание с деталями, необходимыми агенту для их реализации: базовые URL-адреса, обязательные параметры, структуру ответов, аутентификацию, порядок выполнения, зависимости между вызовами и распространенные подводные камни.

Сама по себе система Orbit не требует аутентификации. Ее инструменты поиска и интеграции не требуют ключа API, поскольку работают с общедоступной информацией об API. Это не значит, что сторонние API, которые она рекомендует, работают без аутентификации. Если выбранный провайдер календаря требует OAuth или ключ API, техническое задание подскажет агенту, чего ожидает этот провайдер.

Это различие имеет принципиальное значение. Orbit устраняет барьер аутентификации при обнаружении, а не для самого интегрируемого API.

Context Graph берет на себя внутреннюю сторону

Postman Context Graph начинает движение с противоположного направления. Он сопоставляет API, сервисы, схемы, потребителей, развертывания, владельцев, телеметрию и связи во время выполнения внутри моей организации.

В отличие от Orbit, Context Graph требует аутентификации. Запрос выполняется к частному графу моей команды, поэтому агент должен пройти аутентификацию через Postman, прежде чем задавать вопросы. Именно это мне и нужно для такой информации, как внутренние связи сервисов, владение, развертывания и поведение в продакшене.

Прежде чем изменять процесс приема, агент может задать вопрос:

Что зависит от POST /api/appointments и события appointment.booked? Включите вызывающие стороны во время выполнения, потребителей событий, коллекции, спецификации, развертывания и владельцев.

Что зависит от POST /api/appointments и события appointment.booked? Включите вызывающие стороны во время выполнения, потребителей событий, коллекции, спецификации, развертывания и владельцев.

Граф дает агенту карту окружающей системы, включая связи, которые могут находиться за пределами текущей рабочей копии (checkout). Агент все равно должен проверять все, что возможно, по исходному коду. Граф — это карта, которая указывает, где искать, а не повод перестать проверять код.

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

Что они делают вместе

Проще всего думать об этих двух продуктах следующим образом:

Orbit дает агенту внешние возможности. Context Graph дает ему внутренний контекст. Плагин объединяет оба компонента в рабочий процесс разработки.

Здесь нет автоматической передачи данных, при которой Orbit молча вызывает Context Graph. Это отдельные инструменты с раздельными областями видимости. Полезность заключается в том, что один и тот же агент может вызывать оба инструмента за одну сессию и анализировать их результаты в совокупности.

Демонстрация Claude Code

Вот как я бы продемонстрировал это с помощью плагина Postman Claude Code.

1. Настройка репозитория

Установите плагин, пройдите аутентификацию в Postman для доступа к закрытому Context Graph и инициализируйте репозиторий:

Orbit не требует входа в систему. Context Graph — требует.

postman init предоставляет агенту специфичный для репозитория контекст Postman, который ему необходим, включая места расположения спецификаций API и коллекций. На данный момент я не просил Claude изменять никакой код.

2. Сначала запросите радиус поражения текущих изменений

Мой первый промпт намеренно касается текущей системы:

Мы собираемся добавить проверку конфликтов с внешним календарем и создание событий в процесс записи на прием. Перед тем как что-либо менять, используйте навык обнаружения API Postman и Контекстный граф (Context Graph), чтобы узнать, от чего в настоящее время зависят POST /api/appointments и appointment.booked. Включите в список вызывающие элементы времени выполнения, потребителей событий, спецификации API, коллекции Postman, развертывания и владельцев. Рассматривайте результаты построения графа как подсказки и проверяйте все, что доступно в этом чекауте.

Мы собираемся добавить проверку конфликтов с внешним календарем и создание событий в процесс записи на прием. Перед тем как что-либо менять, используйте навык обнаружения API Postman и Контекстный граф (Context Graph), чтобы узнать, от чего в настоящее время зависят POST /api/appointments и appointment.booked. Включите в список вызывающие элементы времени выполнения, потребителей событий, спецификации API, коллекции Postman, развертывания и владельцев. Рассматривайте результаты построения графа как подсказки и проверяйте все, что доступно в этом чекауте.

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

Без графа Claude был бы ограничен лишь тем, что случайно оказалось в репозитории. С его помощью Claude знает, какие другие системы и команды должны быть учтены в плане.

3. Используйте Orbit для поиска внешнего API

Затем я прошу Claude решить задачу публичного обнаружения:

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

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

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

Для этой демонстрации я выберу соответствующие конечные точки Nylas и скажу следующее:

Используйте шаг интеграции Orbit для выбранных мной конечных точек Nylas. Создайте техническое задание для проверки доступности до подтверждения записи на прием, а затем для создания события в календаре и приглашения пациента. Укажите требования к аутентификации, значения, которые должны передаваться между запросами, и любые ограничения, с которыми нам нужно справиться.

Используйте шаг интеграции Orbit для выбранных мной конечных точек Nylas. Создайте техническое задание для проверки доступности до подтверждения записи на прием, а затем для создания события в календаре и приглашения пациента. Укажите требования к аутентификации, значения, которые должны передаваться между запросами, и любые ограничения, с которыми нам нужно справиться.

Теперь у Claude есть публичные детали реализации от Orbit и частная карта зависимостей из Контекстного графа.

4. Внесите изменения с учетом обоих контекстов

Теперь подсказка для реализации может быть конкретной, не заставляя агента гадать:

Реализуйте эту интеграцию. Используйте результаты Контекстного графа для сохранения существующего процесса записи на прием и обновите каждый артефакт в репозитории, затронутый изменением. Обновите спецификацию API и коллекцию Postman, добавьте тесты контрактов и путей сбоев, а также покажите мне всех потребителей или владельцев вне репозитория, которым требуется отдельное изменение или проверка. Не утверждайте, что эти внешние изменения были сделаны.

Реализуйте эту интеграцию. Используйте результаты Контекстного графа для сохранения существующего процесса записи на прием и обновите каждый артефакт в репозитории, затронутый изменением. Обновите спецификацию API и коллекцию Postman, добавьте тесты контрактов и путей сбоев, а также покажите мне всех потребителей или владельцев вне репозитория, которым требуется отдельное изменение или проверка. Не утверждайте, что эти внешние изменения были сделаны.

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

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

5. Проверьте контракт и добавьте тесты в CI

Наконец, я прошу Claude использовать навыки плагина testing и CI:

Используйте навык тестирования Postman API для проверки обновленной коллекции на соответствие контракту и запустите тесты рабочего процесса записи на прием. Затем используйте навык интеграции с CI, чтобы добавить те же проверки в существующий конвейер CI. Покажите измененные файлы, запущенные команды и все оставшиеся сбои.

Используйте навык тестирования Postman API для проверки обновленной коллекции на соответствие контракту и запустите тесты рабочего процесса записи на прием. Затем используйте навык интеграции с CI, чтобы добавить те же проверки в существующий конвейер CI. Покажите измененные файлы, запущенные команды и все оставшиеся сбои.

Результатом является не просто код интеграции. Контракт, коллекция, тесты и пайплайн перемещаются вместе с реализацией, а результирующие файлы остаются доступными для проверки в Git.

Как насчет изменений, которые граф еще не проиндексировал?

В этом заключается тонкость.

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

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

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

Таким образом, рабочий процесс до слияния заключается не в «сделать изменение, дождаться индексации, а затем проверить, что сломалось». Он состоит в следующем:

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

Почему это лучший подход к агентскому жизненному циклу разработки ПО (SDLC)

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

Меняется лишь то, насколько сильно агенту приходится гадать.

Orbit не дает ему писать стороннюю интеграцию по памяти. Context Graph не дает ему воспринимать один процесс оформления заказа как всю систему целиком. Плагин Claude Code предоставляет ему конкретные способы обновления и проверки артефактов, относящихся к коду.

Это также объясняет аргумент об эффективности использования токенов. Агенту без этого контекста приходится выполнять широкий поиск, читать большие наборы документации и изучать репозитории, которые могут содержать или не содержать ответ. Orbit сужает поиск по публичному API до конечных точек, соответствующих задаче. Context Graph сужает внутренний поиск до сервисов и связей, которые имеют значение. Модель может потратить свое контекстное окно на проверку и реализацию, а не на поиск методом грубой силы.

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

Orbit помогает агенту найти возможности. Context Graph показывает ему последствия. Используемые вместе, они превращают задачу «добавить интеграцию с календарем» из локальной задачи по написанию кода в изменение, которое агент может осмыслить в рамках всего рабочего процесса API.