Плагин Postman для Claude Code: практическое руководство

9 ноября 2026 г.

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

Плагин Postman для Claude Code — это то, как я устраняю этот разрыв прямо из терминала. Он дает Claude Code набор навыков, которые запускают настоящий Postman CLI для каждого этапа работы с API: обнаружение, проектирование, имитация, тестирование, документирование и контроль. В этой статье я установлю его, а затем создам небольшой API заказов от начала до конца с помощью промптов, которые вы можете скопировать. Попутно я укажу, где собственные функции Claude Code (режим планирования, хуки, субагенты и циклы /goal с лимитами токенов) делают рабочий процесс более эффективным.

Если вы хотите увидеть версию этой же идеи для выступления на конференции, то в коротком докладе «Postman в терминале» все сводится к одному предложению: агенту по написанию кода не нужен пользовательский интерфейс. Ему нужна команда для каждого шага, закрепленные навыки, которые говорят, какую команду запустить, и шлюз, который он не может редактировать. Это основа для всего, что последует далее.

Что вам понадобится

• Claude Code, выполнен вход
• Node.js 18 или более поздней версии, которую плагин использует для настройки Postman CLI за вас
• Учетная запись Postman. Бесплатный тарифный план подходит, а локальные команды, такие как линтинг, имитация и запуск коллекции, не требуют входа в систему. Только те действия, которые затрагивают облако Postman.
• Пустой каталог с выполненной командой git init

Установка плагина

Установите плагин из официального маркетплейса плагинов Claude Code от Anthropic. Зарегистрируйте маркетплейс один раз, затем установите:

Это вся установка. Вам не нужно устанавливать Postman CLI самостоятельно. Навык начальной загрузки плагина проверяет его наличие при первом обращении Claude и устанавливает его, если он отсутствует, поэтому отдельного этапа настройки нет.

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

Запустите новый сеанс Claude Code, чтобы плагин загрузился. Плагин также регистрирует размещенный MCP-сервер по адресу mcp.postman.com. Запустите /mcp в сеансе, выберите postman и завершите процесс входа в браузере. Это нужно только для инструментов, которые взаимодействуют с вашим рабочим пространством Postman, например, для поиска существующих коллекций вашей команды.

Чтобы подтвердить, что все загрузилось, запустите /plugin и найдите postman. Или спросите Claude:

Что плагин дает Claude

При каждом запуске, очистке и сжатии хук SessionStart внедряет короткий блок инструкций, предписывающий Claude направлять нетривиальную работу с API через навык postman:api-engineer. Этот навык является точкой входа и передает управление специалистам:

Навык api-engineer содержит мнения, которые важны для этой статьи. Контракт на первом месте. Проверяйте каждое изменение на соответствие контракту. Рассмотрите возможность имитации до того, как будет создана реализация. Не отправляйте изменения в облако без согласия. Я бы написал примерно те же правила на доске, поэтому я доверяю ему выполнение необратимых работ без присмотра.

Установите основные правила один раз с помощью CLAUDE.md

Навыки подсказывают Claude, как использовать Postman. Файл CLAUDE.md говорит ему, как работает ваш репозиторий. Запустите postman init один раз в проекте, что свяжет репозиторий с рабочим пространством и зафиксирует навыки вместе с вашим кодом, чтобы агент товарища по команде (или задание CI) получал те же рекомендации без установки чего-либо:

Затем добавьте короткий раздел в CLAUDE.md:

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

Почему важны спецификация OpenAPI и коллекции v3

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

Спецификация OpenAPI — это контракт. В ней говорится, что обещает API: операции, параметры, схемы и случаи ошибок. Это также первое, что читает агент, поэтому его качество определяет потолок для всего последующего. Имитация, тесты, документация и оценка готовности — все это вытекает из него. Расплывчатая спецификация порождает расплывчатые имитации и низкую оценку.

Коллекция v3 — это исполняемое доказательство. В формате v3, ориентированном на git, коллекция Postman перестает быть одним большим файлом collection.json и становится деревом каталогов в postman/collections/. Каждый запрос, папка и сохраненный пример получают свой собственный YAML-файл:

Такая структура окупается тремя способами, когда работу выполняет агент:

• Небольшие различия (diffs). Добавление теста к одному запросу изменяет один файл. Обзоры запросов на слияние (pull request) показывают именно это, а конфликты слияния остаются редкими.
• Дешевый контекст. Claude читает только один нужный запрос, а не всю коллекцию, поэтому токены тратятся на работу, а не на загрузку JSON.
• Сохраненные примеры — это документация. Файлы .example.yaml записывают, как выглядят ответы 201 и 409. Примеры также являются сигналом, который поощряет проверка готовности, поэтому одни и те же файлы служат людям, агентам и оценке.

Две привычки помогают этому работать. Во-первых, плагин поставляет навык collection-schema-v3 с точной схемой и правилами именования, и вам следует сказать Claude прочитать его, прежде чем он начнет редактировать что-либо в postman/. Во-вторых, проверяйте то, что он пишет, так как неправильно сформированный YAML-файл выдает ошибку без уведомления, чего никогда не случится в интерфейсе. Вам не нужно запоминать команды. Спросите Claude:

Внутри Claude запускает две команды Postman CLI: postman spec lint openapi.yaml -f error и postman collection lint "postman/collections/Orders API" -f error. Флаг -f error заставляет завершаться с ошибкой только результаты уровня ошибки. Вы увидите те же команды позже в хуке и шлюзе CI, где ничто не побуждает Claude запускать их.

Храните спецификацию и коллекцию в том же репозитории, что и код. Когда все три меняются в одном запросе на слияние, проверка — это один diff, а CI проверяет все три вместе.

Создание API заказов с помощью промптов и целей

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

Цель 1: проверить, существует ли уже API

Прежде чем Claude что-либо напишет, выясните, не решил ли кто-то уже эту задачу. Это навык api-discovery, и он отвечает из трех разных источников. Они не обмениваются данными, поэтому отсутствие результата в одном ничего не говорит о других.

Поиск Postman соответствует коллекциям, спецификациям и имитациям, которые сохранили люди. Команда postman search принимает флаг --ownership. Значение по умолчанию, organization, ищет только в ваших собственных рабочих пространствах. external ищет все за пределами вашей организации, где находится Postman Public API Network. all ищет и там, и там. Скажите Claude использовать all, прежде чем он сделает вывод, что ничего не существует, потому что публичный или партнерский API невидим в области видимости по умолчанию.

Orbit, которую вызывает для вас api-discovery skill, делает еще один шаг вперед для сторонних провайдеров. Ее вызов поиска возвращает кандидатов для вашей задачи, включая их лимиты, а integrate превращает выбранный вами вариант в бриф с базовым URL, требованиями к аутентификации, шагами и подводными камнями. Это гораздо меньший объем контекста, чем загрузка полной спецификации OpenAPI вендора для ответа на один вопрос. Orbit не предоставляет учетные данные провайдера, поэтому их все равно придется оформлять самостоятельно. Граф контекста — это отдельная карта инженерных сервисов, которую мы будем использовать в Цели 6.

Вот промпт, который задействует первые два пункта. Сервис заказов мы должны построить сами, а вот прием платежей — пожалуй, нет:

Один промпт, три источника. Иллюстративная сессия; точные вызовы, которые делает Claude, будут зависеть от вашего рабочего пространства.

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

Внимание: поддержка Orbit включена в последнюю версию навыка api-discovery. Если Claude не упоминает Orbit, когда вы спрашиваете, обновите плагин и начните новую сессию.

Цель 2: сначала напишите контракт в режиме планирования (plan mode)

Нажимайте Shift+Tab, пока Claude Code не перейдет в режим планирования, а затем запросите контракт. Режим планирования оставляет Claude только в режиме чтения при создании предложений, поэтому вы проверяете проект до того, как будет изменен хотя бы один файл.

Утвердите план, и Claude напишет openapi.yaml. Вот к какому результату вы стремитесь. Это полная, готовая к запуску спецификация для первых двух операций; попросите Claude добавить отмену (cancel) тем же способом.

Посмотрите, что спецификация сообщает агенту из того, что человек домыслил бы сам. Ответ 409 говорит: «не повторяйте попытку». Ответ 404 говорит: «проверьте идентификатор». Сумма — это целое число в центах с указанием причины. Заголовок Idempotency-Key делает повторные попытки безопасными, и описание говорит об этом прямо. Это именно те детали, которые определяют, сможет ли агент восстановиться или уйдет в штопор. Спецификация OpenAPI дает вам каждое поле, необходимое для этого, а RFC 9457 предоставляет машиночитаемый формат ошибки, чтобы вам не приходилось изобретать его самостоятельно.

Цель 3: разблокируйте потребителей с помощью мока, который может выдавать ошибки

Команда клиентов (или другой агент) не должна ждать вашей реализации. Навык api-mocking генерирует локальный мок-сервер на основе спецификации, а его переопределения во время выполнения запроса позволяют репетировать сценарии сбоев.

Два заголовка меняют то, что мок возвращает для каждого запроса: x-mock-scenario выбирает именованный сценарий, а x-mock-response-code принудительно задает статус.

Под капотом Claude запускает postman mock generate, postman mock run и postman request. Мок состоит из двух файлов в postman/mocks/: config.yaml и default.js, представляющего собой обычный Node HTTP-сервер. Поскольку это стандартный код, Claude может прочитать его, и вы тоже.

Внимание: здесь нет горячей перезагрузки (hot reload). Если Claude редактирует default.js, ему придется остановить и перезапустить мок, чтобы изменения вступили в силу. Хорошая сессия с поддержкой навыков делает это самостоятельно, но если ответ выглядит устаревшим, проверить в первую очередь нужно именно это.

Цель 4: подтвердите контракт тестами

Теперь напишите проверки, которые гарантируют соответствие реализации контракту. Навык api-testing использует postman collection run для наборов утверждений pm.test, а флаг --use-mock направляет выполнение на мок вместо реального бэкенда.

Утверждения, которые пишет Claude, являются стандартными тестовыми скриптами Postman. Проверку пути ошибки я бы прочитал внимательнее всего:

Подобные тесты — это та часть контракта, на которую агент полагается больше всего, поскольку они описывают негативный сценарий. Они также превращают утверждение «мок говорит, что это работает» в «реализация совпадает с моком». Укажите ту же коллекцию для вашего реального сервиса, поменяв базовый URL в окружении.

Цель 5: оцените спецификацию на готовность к работе с агентами

Это шаг, который делает рабочий процесс нативным для ИИ, а не просто автоматизированным. Навык ai-readiness оценивает спецификацию (или коллекцию) с точки зрения того, может ли агент обнаружить ее, понять, правильно вызывать и восстанавливаться после ошибок. Пропущенные примеры, не задокументированные ошибки и неоднозначные параметры — все это снижает баллы.

Оценка попадает в одну из четырех категорий: Limited (Ограничено), Fair (Удовлетворительно), Good (Хорошо) или Excellent (Отлично), наряду с коэффициентом уверенности (confidence), который показывает, сколько сигналов удалось измерить. Попросите Claude сообщить то, что вывела команда, а не пересказывать это своими словами. Навык написан так, чтобы делать именно это, и это спасает вас от кивания числу, которое модель округлила в уме.

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

Цель 6: знайте, что вы сломаете, до того, как измените это

Как только у API появляются потребители, каждое изменение становится вопросом риска. Граф контекста — это общеорганизационная карта ваших API и зависящих от них сервисов, построенная на основе таких сигналов, как рабочие пространства Postman и ваши репозитории. Он отвечает на архитектурные вопросы, на которые поиск ответить не может, поскольку не существует ключевого слова для зависимости. api-discovery запрашивает его с помощью postman context-graph ask, принимающего вопрос на обычном английском языке:

Вы редко будете вводить это самостоятельно. Спросите у Claude о последствиях, прежде чем он прикоснется к контракту:

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

Относитесь к ответу как к сильной подсказке, а не как к доказательству. Граф отвечает на уровне эндпоинтов, поэтому он может подсказать вам, что потребитель вызывает GET /orders/{orderId}, но не укажет, какое именно поле этот потребитель читает. А сообщение «потребители не найдены» не означает безопасность — оно означает лишь то, что никто не был обнаружен. Более безопасным изменением здесь будет сохранить старое поле, добавить новое рядом с ним и пометить старое как устаревшее (deprecated).

Используйте возможности Claude Code, а не только промпты

Промпты продвигают вас далеко вперед. Эти функции превращают рабочий процесс в нечто повторяемое.

Режим планирования для всего, что изменяет контракт

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

Хук, который проверяет линтером каждое изменение спецификации

Хуки запускаются по выбранным вами событиям за пределами модели, поэтому они срабатывают каждый раз. Этот хук PostToolUse в файле .claude/settings.json проверяет спецификацию линтером всякий раз, когда Claude редактирует ее, и возвращает ошибки прямо обратно, чтобы Claude исправил их за тот же шаг. Код выхода 2 — это то, что отправляет stderr обратно в Claude.

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

Субагент для независимого обзора контракта

Агент, проверяющий свою собственную работу, склонен одобрять ее. Субагент начинает с чистого контекста и имеет только те инструменты, которые вы ему дали, что делает его лучшим ревьюером. Сохраните это как .claude/agents/contract-reviewer.md:

Затем спросите: Используй субагент contract-reviewer для моих изменений в openapi.yaml.

Предварительное одобрение безопасных команд

Claude Code запрашивает разрешение перед запуском команд оболочки, что правильно по умолчанию и утомительно для команд, которые вы запускаете по сорок раз на дню. Разрешите команды только для чтения и локальные команды в .claude/settings.json, а все, что касается облака, оставьте на усмотрение промпта:

Автономный режим и CI в качестве защитного барьера, который агент не может изменить

Claude Code работает в неинтерактивном режиме с помощью флага claude -p, что удобно для скриптовых ревью. Однако для самого защитного барьера я бы отказался от использования модели и запускал Postman CLI напрямую в CI. Детерминированную проверку невозможно убедить не падать.

Команда postman collection run завершается с ненулевым кодом выхода, если падает утверждение pm.test, а флаг --min-score приводит к сбою задания, если оценка готовности падает ниже вашего порогового значения. Для флага --use-mock требуется свежая версия Postman CLI, поэтому перед его использованием проверьте справку с помощью postman collection run -h. Выберите порог, который ваша спецификация проходит уже сегодня, а затем повышайте его по мере улучшений. Если вы хотите, чтобы Claude реагировал на сбой, второе задание может вызывать claude -p "Проверка api-gate не прошла. Прочитайте лог и предложите исправление" с ограниченным списком --allowedTools и открывать исправление в виде pull request для проверки человеком.

Используйте /goal для циклического выполнения до достижения результата

Все, что было рассмотрено выше, — это один промпт и один результат. Некоторые задачи требуют нескольких попыток: добиться успешного прогона коллекции или поднять оценку готовности выше определенного уровня. Для таких случаев команда /goal в Claude Code задает условие завершения и заставляет Claude работать в несколько итераций до его выполнения. После каждой итерации отдельная компактная и быстрая модель проверяет выполнение условия на основе того, что Claude показал в беседе. Если условие не выполнено, Claude начинает новую итерацию. Если выполнено — цель считается достигнутой.

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

Пример: сделать API быстрым и без ошибок

Допустим, существует сервис заказов, а в коллекции есть проверка времени отклика, например pm.expect(pm.response.responseTime).to.be.below(300). Вот цель для достижения успешного прохождения:

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

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

Вот что обеспечивает работоспособность такого условия:

• Одно измеримое целевое состояние. Ноль упавших проверок в сводке прогона, которую выводит CLI.
• Четко сформулированная проверка. Claude должен запустить коллекцию и вывести сводку, поскольку оценивающий компонент может судить только о том, что отображается в беседе. Он не выполняет команды и не читает файлы самостоятельно.
• Ограничения на пути к цели. Claude может изменять папку src/, но не тесты. Без этого предложения самым коротким путем к успеху станет удаление самого утверждения.
• Условие выхода. Лимит итераций и пункт об «отсутствии прогресса» ограничивают цикл.

Пример: повышение оценки готовности

Тот же подход работает и на уровне контракта, и это самая нативная для ИИ цель в данной статье:

Контролируйте расходы на токены

Цель выполняется без вашего поштучного промпта для каждого шага, поэтому расплывчатая формулировка может выполняться очень долго. Установите ограничения перед началом работы:

• Укажите лимит итераций в условии. Вариант вроде «или остановись после 15 итераций» является документированным паттерном. Claude сообщает о прогрессе на каждой итерации, а оценивающий компонент оценивает его на основе беседы.
• Добавьте пункт об отсутствии прогресса. Правило «Остановиться, если две попытки подряд ничего не меняют» прерывает зациклившийся процесс.
• Выберите одну метрику. Цель вроде «сделать API хорошим» никогда не завершится. А «Ноль упавших проверок» — завершится.
• Сохраняйте объем вывода небольшим. Флаг --bail завершает прогон коллекции при первой же ошибке, поэтому на каждой итерации читается короткий результат вместо полного отчета.
• Работайте в отдельной ветке. Если цикл завершился неудачно, вы просто отбрасываете ветку.
• Проверяйте счетчик. Запустите /goal без аргументов, чтобы увидеть условие, прошедшее время, количество оцененных итераций и потраченные токены. Команда /goal clear останавливает процесс.
• Ограничивайте автономные запуски. В скрипте вызов claude -p "/goal ..." запускает весь цикл за один раз. Используйте его в паре с флагами --max-turns и --max-budget-usd, которые работают только в режиме печати. Достижение любого из этих лимитов завершает запуск с ненулевым кодом выхода, что позволяет скрипту реагировать на это:

Итерация здесь — это один цикл «запрос-ответ», включающий вызов инструмента, а бюджет проверяется после каждого ответа, поэтому затраты могут превысить лимит на один ответ. Оставляйте небольшой запас. Предупреждение: флаг --max-budget-usd отображается в справке claude --help на моей машине, а --max-turns — нет, поэтому проверьте свою версию, прежде чем полагаться на него.

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

Когда вместо этого использовать /loop

/goal сходится к результату: он выполняется до тех пор, пока выполняется условие. Команда /loop повторяется через заданные интервалы времени, что больше подходит для наблюдения, а не для исправления. Используйте ее для опроса того, что меняется само по себе:

Используйте /goal для исправления неудачного прогона, а /loop или Postman Monitor — чтобы заметить появление сбоя. Для всего, что должно работать, пока ваш ноутбук закрыт, Monitor или задача в CI подходят лучше.

На что стоит обратить внимание

• Не позволяйте агенту делать push в ваш рабочий репозиторий. Собственные правила плагина запрещают отправку изменений без подтверждения, и я бы подкрепил это приведенным выше правилом запрета. Выполняйте push из CI после слияния.
• Сообщайте результаты в виде точных оценок, а не пересчитывайте их. Попросите Claude процитировать то, что вывел инструмент ai-readiness. Перефразированная оценка 82 легко превращается в «примерно 80».
• Запускайте справку (-h), прежде чем доверять какому-либо флагу. Инструкции предписывают Claude читать справку CLI перед использованием любого флага со значением по умолчанию. Поступайте так же, когда копируете команды из блога, включая этот. Флаги меняются от версии к версии CLI.
• Проверяйте, что именно отправляется вовне. Некоторые команды Postman CLI по умолчанию отправляют результаты запусков и аналитику в Postman. В файле README плагина перечислено, какие именно, и описано, как отключить это с помощью --no-report-events. Прочитайте его, прежде чем запускать плагин на конфиденциальной кодовой базе.
• Моки — это не сам сервис. Успешный прогон тестов на моке доказывает, что ваши тесты соответствуют контракту. Это ничего не говорит о вашей реализации, пока вы не направите ту же коллекцию на реальный сервис.

Что вы построили

Теперь у вас есть репозиторий, где контракт представлен в виде файла, мок и тесты создаются на его основе, оценка готовности является числом, которое можно отслеживать, ограниченная по времени цель может исправить упавший прогон, а CI-система удерживает планку качества. Claude Code пишет код, Postman CLI выполняет проверки, а правила хранятся в CLAUDE.md и пайплайне, а не в чьей-либо памяти.

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

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

Ресурсы

• Плагин Postman для агентов кодинга на GitHub
• Короткое выступление и демо Postman в терминале
• Документация Postman CLI
• Установка Postman CLI
• Настройка мок-серверов в Postman
• Контекстный граф API Postman
• Модуль плагина Claude Code на Postman Liftoff
• Навык обнаружения API плагина Postman, включая Orbit
• Справочник хуков Claude Code
• Субагенты Claude Code
• Спецификация OpenAPI
• Протокол контекста модели