Claude CodeにPostmanプラグインを入れると、AIエージェントが勝手にテストゲートを緩めるのを防ぎながらAPIライフサイクル全体を自律実行できる

11月10日、Postmanが「Postman Plugin for Claude Code: A Hands-On Guide」と題した記事を公開した。AIエージェントはAPIドキュメントを人間のように読まない——この前提から出発し、Claude CodeにPostmanプラグインを導入することで、APIの設計・モック・テスト・ゲートを一貫して扱えるワークフローを構築する方法を詳しく解説している。「エージェントにAPI仕事をさせる」のではなく、「エージェントが間違えにくい構造を先に作っておく」という設計思想が通底しており、実践的な知見が詰まった記事だ。

「AIエージェントはドキュメントを読まない」という前提から始まる

記事の書き出しが刺さる。

Most APIs were written for a human who reads the docs, squints at an error message, and tries again. An AI agent doesn't do any of that well.

AIエージェントはスペックに書いてある通りにエンドポイントを呼ぶ。在庫切れ時の挙動がスペックに書かれていなければ、エージェントは「推測」する。エージェントループの中での推測は、リトライ・ハルシネーションパラメータ・混乱したオンコールエンジニアにつながる、というわけだ。

この課題に対するPostmanの答えが、**Postman Plugin for Claude Code**だ。Claude Codeのターミナルから、APIライフサイクル（discover・design・mock・test・document・gate）の各ステップに対応するPostman CLIコマンドをエージェントが自律的に実行できるようにする。

インストールは2コマンドで完了

claude plugin marketplace add anthropics/claude-plugins-official
claude plugin install postman@claude-plugins-official

※上記コマンドは本記事執筆時点（2025年11月）の仕様に基づく。Claude CodeのCLI仕様は更新されることがあるため、最新の手順は公式ドキュメントも合わせて確認されたい。

Postman CLI自体は別途インストール不要。初回実行時にプラグインのbootstrapスキルが自動で検出・インストールする。Node.js 18以上、Postmanアカウント（無料プラン可）、git init済みのディレクトリがあれば動く。

プラグインをインストールすると、Claude Codeは以下のスキル群を持つ。

セッション開始・クリア・コンパクト時にSessionStartフックが自動で挿入され、非自明なAPI作業はpostman:api-engineerスキル経由でルーティングするよう指示される。エージェントへの介入を最小化しつつ、Postmanのベストプラクティスを強制する設計だ。

一番面白い部分：エージェントが勝手にゲートを緩めるのを防ぐ設計

記事で最も実践的な知見が詰まっているのが、CLAUDE.mdとCIゲートの組み合わせだ。

postman initでリポジトリをワークスペースに紐付けた後、CLAUDE.mdに以下を書く。

## API work
- `openapi.yaml` is the contract. Change it before you change code.
- Make HTTP calls with `postman request`, not curl.
- Before you say a change is done, run `postman spec lint openapi.yaml`
  and `postman collection run` against the mock.
- Never run `postman workspace push`. CI does that after merge.
- Never edit `.github/workflows/api-gate.yml` or lower a `--min-score`
  threshold to make a check pass. Ask me.

最後のルールについて、記事はこう言う。「チェックを赤から緑にするプレッシャーの下に置かれたエージェントは、喜んでチェック自体を緩める」。だからエージェントが手を届かせられない場所にゲートを置き、それを明文化するのが重要だという。

CIゲート（.github/workflows/api-gate.yml）ではpostman spec lint・postman collection run・postman ai-readinessの3つが走り、いずれかが閾値を下回ればマージをブロックする。エージェントがコードを書いても、このゲートだけは人間が管理する。

v3コレクションのディレクトリ構造が「エージェント向け」な理由

Postman Collection v3フォーマットでは、コレクションがディレクトリツリーに展開される。

postman/collections/
  Orders API/
    .resources/
      definition.yaml
      create order.resources/
        examples/
          201 Created.example.yaml
          409 Out of Stock.example.yaml
    create order.request.yaml
    get order.request.yaml
    cancel order.request.yaml

1リクエスト＝1ファイルなので、エージェントが必要なファイルだけを読み込める。コレクション全体をJSONとしてロードするよりトークン消費が大幅に削減される。PRのdiffも1リクエストの変更が1ファイルの変更に対応するため、レビューしやすい。保存済みサンプル（.example.yaml）は人間向けドキュメントとAI適性スコアの両方に使われる。

実際のワークフロー：Ordersサービスを段階的に構築

記事では「Ordersサービスを最初から作る」というシナリオで、各フェーズのプロンプトが公開されている。

Goal 1: 既存APIの探索

I need an orders API with create, get, and cancel operations, and orders
need payment. Before we build anything: does either already exist in our
workspaces or on the Postman Public API Network? Search with --ownership
all. If there's no existing payments API, use Orbit to find public payment
provider APIs that fit, and tell me what each one can't do before you
recommend one.

--ownership allを指定することで、自分のワークスペースとPostman Public API Networkを両方検索する。デフォルト（organization）のままでは公開・パートナーAPIが見えない点に注意。

Goal 2: プランモードでスペックを先に書く
Claude Codeのプランモード（Shift+Tabで切り替え）を使い、実装前にOpenAPIスペックの設計をレビューする。operationId・description・RFC 9457（Problem Details for HTTP APIs）準拠のエラーレスポンス・サンプルレスポンスを全オペレーションに要求する。RFC 9457はHTTP APIにおけるエラーレスポンスの標準フォーマットを定めたRFCで、type・title・status・detailフィールドを持つJSONオブジェクトでエラーを表現する。エージェントがエラーの意味を機械的に解釈しやすくなるため、AI向けAPIでは特に有効だ。

その後のフェーズとして、スペックからモックを立ち上げ→実装→コレクションテスト→AI適性スコアリング→CIゲート追加、という順序で進む。各フェーズで使うCLIコマンドはすべてClaude Codeが自律実行し、人間は必要に応じてプロンプトを書くだけだ。

まとめ

このプラグインの核心は「エージェントにAPI仕事をさせる」ではなく、「エージェントが間違えにくい構造を先に作っておく」ことだ。スキル・CLAUDE.md・CIゲートの3層で、エージェントの自由度と安全性のバランスを取る設計になっている。

詳細はPostman Plugin for Claude Code: A Hands-On Guideを参照していただきたい。