Claude CodeのSKILL機能でPostmanコレクションの回帰テストメンテを自動化した

背景

業務でレグレッションテストを実施した。要件は以下のとおり。

• 2025-10に実施した結合テスト（Postmanコレクション）をベースとしてテストケースを使用する
• 前回実施時（2025-10）以降に修正された不具合・改善をFIXし、正常系リクエストを再作成する
• 結果はNewmanで実行し、HTMLファイルで証跡を残す

SKILL化しようと思ったきっかけ

テストケースの修正に時間（工数）がかかることが課題だった。

テストケース数が多いことに加え、相関チェック（項目Aを修正したら、それに合わせて項目Bも変えなければならない）があったりと、修正箇所が広範にわたる。手動で対応していると工数がかさんでしまう。

SKILLとは

Claude Codeには、作業手順をファイルに定義しておくことで、スラッシュコマンド（例：/regression-postman-fix）として呼び出せる「SKILL」という仕組みがある。

SKILL化以前は、Claudeに作業を依頼するたびに同じ内容をプロンプトに記述していた。これには2つの問題があった。

1つは単純に手間がかかること。2つ目はClaudeの応答のブレだ。Claude Codeは/clearや再起動のたびにセッションがリセットされ、いわば「中の人が変わる」状態になる。毎回プロンプトで指示していると、その日の解釈次第で成果物のクオリティや内容にばらつきが生じる。

SKILLとして手順を定義しておくことで、誰が・いつ実行しても同じ品質で同じ成果物が得られるようになる。一種のバッチ処理やマクロに近いイメージだ。

SKILLの作成方法

SKILLは基本的にClaudeに作成させた。

最初に「これをやりたい」という概要をプロンプトに打ち込み、たたき台を作成させた。その後、実際に修正したいテスト仕様書（Postmanコレクション）を投入して作業させ、都度フィードバックを行いながらSKILLをブラッシュアップしていった。

実現できた内容

以下のinputを投入するだけで動く。

input	内容
Postmanコレクション	修正対象のテストコレクション（.postman_collection.json）
環境ファイル	Newman実行時の環境変数（.postman_environment.json）
前回テスト日	例：2025-10-01

処理の流れは以下のとおり。

① 前回テスト日以降に行われた仕様・バリデーションの変更をgit logで自動調査
② 洗い出した変更内容とPostmanコレクション内のリクエストを照らし合わせ、最新化
③ 以下をoutputとして出力
     - 修正後Postmanコレクション
     - 環境ファイル（Newmanで使えるようコピー）
     - Newman実行バッチ（`newman_run.bat`）
     - 修正箇所サマリ（Markdown）

outputフォルダをWindowsにコピーしてnewman_run.batをダブルクリックすれば、HTMLレポートとして証跡が生成される。

SKILL.mdの構造（抽象化サンプル）

実際のSKILLは以下のようなフェーズ構成で記述している。

Phase 1 : 受け取り・読込
  ├ inputフォルダ確認・ファイル選択・前回実行日入力
  └ コレクション読み込み・構造分析

Phase 2 : 調査（前回テスト日以降の変更を一覧化）
  ├ キャッシュ確認（当日調査済みならスキップ）
  ├ BFFバリデーション変更調査（git log）
  ├ Backendバリデーター変更調査（git log）
  ├ 時間依存フィールド確認
  └ 変更一覧をユーザーへ表示 ★ユーザー確認ポイント

Phase 3 : 修正
  ├ GraphQL Body修正
  ├ 全件検証
  └ 期待値修正

Phase 4 : 出力
  ├ 修正済みJSON保存
  ├ 修正サマリ.md出力 ★ユーザー確認ポイント
  └ Newman実行バッチ生成

ポイントは「★ユーザー確認ポイント」を明示している点だ。AIが一気通貫で処理するからこそ、どこで人間が介入・確認すべきかをSKILL.md内に明記している。

また複雑な処理（JSONの再帰走査、バッチファイル生成など）はPythonスクリプトに切り出している。AIに毎回書かせると実装にブレが出るため、スクリプトとして固定してしまう方がSKILLの安定性が上がる。

工夫した点：修正サマリによる人間レビューの担保

Claudeに調査〜修正を一気通貫で行わせているため、修正内容が正しいかどうかを人間が確認できる仕組みが必要だった。

「テストを無理やり通すために、仕様とは関係ない箇所を勝手に変えていないか」を見極めるために、outputとして修正サマリもMarkdownで出力させている。

修正フィールド	修正内容	根拠（feature番号・修正日）
<fieldName>	<旧値> → <新値>	2025-10-20 feature/xxxx
<fieldName>	null化	2025-10-29 feature/xxxx

確認時に特に見るのは根拠欄だ。前回テスト日以降の変更に対応したFIXなのかどうかを、feature番号と日付でトレースできる。根拠欄が空欄だったり、知らないfeature番号が入っていたりすれば、そこが要確認箇所になる。

**「AIが何をしたかを人間が検証できる形で出力させる」**という設計が、この自動化を実運用に耐えるものにしている。

苦労した点

Postmanのステップ数が多いためか、SKILL.mdにルールとして記述していても守ってくれないことが多々あった。

その都度「記載した内容を無視した原因を教えて」と原因究明を行い、SKILLをブラッシュアップしていったが、何度も同じミスを繰り返すこともあり、こちらが発狂するところであった（笑）

特に有効だったのは：

• 禁止事項を明示的に書く：「〇〇は一律置換禁止」のように、やってはいけないことをSKILL.mdに直接記述する
• スクリプトに逃がす：ルールを守らせるより、Pythonスクリプトとして固定してしまう

おまけ：Newmanまわりのハマりどころ

Newmanを使う場合、特にWindows環境では以下の罠がある。

#	問題	対策
1	^による行継続が日本語ファイル名で破損する	^を使わずnewmanコマンドを1行に収める
2	日本語ファイル名が文字化けする	バッチ先頭にchcp 65001 > nulを追加
3	%~dp0に日本語が含まれるとファイルパス解決に失敗する	先頭でcd /d "%~dp0"した後、--working-dir "."を使う
4	postman-cloud:///形式の画像参照がNewman CLIで動作しない	ローカルファイルに置換する
5	同一ファイルパスをコレクション内で3回以上使うと3回目以降のアップロードが空になる	フォルダ単位で連番コピーを作成して回避

これらはいずれもPostmanのGUI上では発生しない問題で、Newman CLIに切り替えて初めて踏む罠だ。同じ構成を取る方の参考になれば。

まとめ

• Postmanコレクションのメンテ作業をClaude CodeのSKILLとして定型化した
• 前回テスト日を入力するだけで、差分調査〜修正〜バッチ生成が完結する
• 重要なのはAIの作業を人間が検証できる形で出力させる設計。修正サマリの根拠欄でトレーサビリティを担保した
• SKILL.md自体もClaudeに作らせてブラッシュアップしていく進め方が効率的だった