regressguard

RegressGuard

コミットする前に、何が壊れたかを把握しましょう。

AI コーディングエージェントがアプリを編集すると、API コントラクトをひそかに壊すことがあります。フィールドの削除、ステータスコードの変更、失敗するようになったテストなどがあっても、成功したと報告する場合があります。RegressGuard は正常な状態のベースラインを記録し、何が後退したのかをあなた（またはエージェント）に正確に知らせます。

エージェント自身のループ内で動作するように設計されています。 RegressGuard はMCP サーバーとして提供されるため、Claude Code や Cursor などのエージェントは、人間が差分を見る前に自分の作業を検証して自己修正できます。追加の手順は不要です。同じエンジンは、人間や CI 向けの通常の CLI としても実行できます。

# Agent-native (primary): the agent calls these as MCP tools in its loop
check → status                  # see "Agent-native verification (MCP)" below
                                 # the baseline stays yours: agents cannot re-record it

# Human / CI (also works): two commands, no test-writing, under 15 seconds
regressguard snapshot   # record the known-good state
regressguard check      # compare after edits — see what broke

破損 → 検出 → 修正 → 成功。./demo/demo.sh を実行して、自分で試してみましょう。

---

インストール

macOS / Linux（推奨）

curl -fsSL https://raw.githubusercontent.com/Bharath-code/regressguard/main/install.sh | sh

確認

regressguard version   # first line must say "RegressGuard"

v0.1.x からアップグレードする場合 rg が ripgrep と衝突するため、バイナリ名を rg から regressguard に変更しました。rg の互換用コマンドはなく、古い rg upgrade では v0.2.0 を取得できません。インストーラーを再実行し、古い rg を削除してから regressguard hook install を実行してください （古いフックは rg を呼び出すため、regressguard doctor が警告します）。

---

クイックスタート（3 分）

1. プロジェクトを初期化する

cd your-project
regressguard init

RegressGuard は、テストコマンド、フレームワーク、開発サーバーの URL を自動的に検出します。

2. AI セッションの前にベースラインを記録する

開発サーバーが起動していることを確認してから、次を実行します。

regressguard snapshot

出力：

Snapshot

OK Tests       42 passed, 0 failed       6.8s
OK Routes      6 captured, 2 skipped
OK Schemas     6 hashed

Saved:
  .regressguard/snapshot.json

Next:
  Ask your AI agent to make the code change, then run:
  regressguard check

3. AI エージェントを実行する

Claude Code、Cursor、または Codex に変更を加えさせます。

4. コミット前にリグレッションを確認する

regressguard check

問題なし — 安全にコミットできます：

Check

OK No regressions detected

  Tests       42 passed, 0 failed
  Routes      6 unchanged
  Timing      within tolerance

Safe to commit.

リグレッションを検出 — コミットはブロックされます：

Check

X 2 regressions detected

  Route                                 Before    After     Change
  GET /api/users                        schema    schema    schema
    - role (string, removed)
    + age (number, added)
  POST /api/user/update                 200       500       status

Likely cause:
  Auth/session behavior or routing changed during the last code edit.

Changed files since snapshot:
  app/api/users/route.ts
  internal/auth/session.go

Next:
  regressguard check --verbose
  git diff

Commit blocked.

重大な問題がある場合、終了コードは 1 です。Git フックや CI と連携できます。

---

Git フック（すべてのコミットを自動保護）

regressguard hook install

これで、すべての git commit の前に regressguard check が自動実行されます。重大なリグレッションが検出されると、簡潔な出力とともにコミットがブロックされます。

RegressGuard pre-commit

X 1 regression detected
  POST /api/user/update status changed from 200 to 500

Run:
  regressguard check --verbose

Commit blocked. Use --no-verify only if you accept the risk.

リスクを受け入れる場合に限り、git commit --no-verify で回避できます。

---

エージェントネイティブな検証（MCP）

これは RegressGuard の主な動作モードです。人間が regressguard check を実行するのを待つ代わりに、AI エージェントは自分自身の編集ループ内でツールとして呼び出します。これにより、導入したばかりのリグレッションを検出して修正し、変更をあなたに返す前に対処できます。

サーバーを起動します（stdio トランスポート）。

regressguard mcp serve

Claude Code に登録する：

claude mcp add regressguard -- regressguard mcp serve

Cursor に登録する（.cursor/mcp.json）：

{
  "mcpServers": {
    "regressguard": { "command": "regressguard", "args": ["mcp", "serve"] }
  }
}

エージェントは次の 2 つのツールを利用できます。

ツール	目的
check	現在の状態をスナップショットと比較し、重大度を含む構造化された検出結果を返します
status	サブ秒で完了するヘルスチェック（スナップショットの経過時間、ルート／設定／フックの状態）を行います。テストは実行しません

ベースラインを管理するのは人間です。 エージェントには、デフォルトで snapshot ツールがありません。ベースラインを再記録できてしまうと、エージェントが自分自身のリグレッションを受け入れられるためです （check が失敗 → snapshot → check が成功）。ベースラインは regressguard snapshot で記録してください。それでもエージェントにベースラインを再設定させるには、.regressguard/config.json に次の設定を追加し、MCP サーバーを再起動します。

{ "mcp": { "allowSnapshot": true } }

ツールの応答は、regressguard check --json と同じ機械可読ペイロードです。詳しくは docs/json-contract.md を参照してください。各ツール呼び出しは、.regressguard/ 以下の追記専用監査ログに記録されます（ツール、ステータス、所要時間、タイムスタンプ）。

一般的なループは次のとおりです。エージェントがコードを編集 → check を呼び出す → 構造化された検出結果を確認する → リグレッションを修正する → 再び check を呼び出す → その後に完了を報告する。

---

コマンド

コマンド	目的
regressguard init	このプロジェクト用に RegressGuard を設定します
regressguard quickstart	1つのコマンドで自動設定とスナップショットの記録を行います
regressguard snapshot	現在の合格状態を記録します
regressguard check	現在の状態をスナップショットと比較します
regressguard status	サブ秒単位のヘルスチェックを行います（スナップショットの経過時間、ルート、フック）。テストは実行されません
regressguard explain <route>	特定のルートの変更前後の差分を表示します
regressguard watch	ファイルを監視し、変更時に自動で check を実行します
regressguard mcp serve	AI エージェントが自己検証できるよう、MCP サーバーを実行します（上記を参照）
regressguard hook install	コミット前の git フックをインストールします
regressguard hook uninstall	git フックを削除します
regressguard config get <key>	設定値を読み取ります
regressguard config set <key> <value>	設定値を書き込みます
regressguard doctor	セットアップの問題を診断します
regressguard upgrade	regressguard を最新バージョンに更新します
regressguard completion <shell>	シェルの自動補完（bash、zsh、fish）を生成します
regressguard version	バージョンとビルドメタデータを表示します

フラグ、使用例、終了コードを確認するには、regressguard <command> --help を実行してください。

---

設定

設定は .regressguard/config.json に保存されます（人が読みやすく、git の無視対象にできます）。

{
  "version": 1,
  "testCommand": "npm test",
  "serverUrl": "http://localhost:3000",
  "auth": {
    "mode": "bearer",
    "testToken": "your-test-token",
    "headerName": "Authorization",
    "prefix": "Bearer"
  },
  "ignoreFields": ["requestId", "traceId"],
  "routes": [
    { "method": "GET", "path": "/api/health" },
    { "method": "GET", "path": "/api/users" },
    { "method": "GET", "path": "/api/admin", "skip": true }
  ]
}

認証モード： bearer（Authorization ヘッダー）、cookie（Cookie ヘッダー）、または公開ルートのみの場合は省略します。

ignoreFields： スキーマ比較から除外するフィールドです。requestId や traceId のような、変化しやすいアプリ固有の値に便利です。

---

仕組み

1. regressguard snapshot はテストスイートを実行し、設定された各ルートにアクセスします。合格数と失敗数、HTTP ステータスコード、各レスポンスの正規化されたスキーマハッシュを記録します。

2. regressguard check は同じテストとルートを再実行し、スナップショットとの差分を確認します。

   • CRITICAL：テストスイートが新たに失敗した、ステータスコードが変わった、レスポンススキーマが変わった（例：フィールドの削除、追加、変更）
   • WARNING：レスポンス時間が200msを超えて増加し、かつベースラインの50％を超えた
   • PASS：すべてが許容範囲内

3. スキーマ比較では、JSON ペイロードが自動的に正規化されます。

   • デフォルトの動的キー：ハッシュ化の前に、一般的な16個の動的キー（id、uuid、token、nonce、timestamp、createdAt、updatedAt、deletedAt、created_at、updated_at、deleted_at、sessionId、accessToken、refreshToken、expiresAt、expires_at）を取り除きます。
   • パターン検出：ISO-8601形式の日付文字列、UUID、JWT を自動的に検出し、汎用的な型表現（"date"、"uuid"、"token"）に置き換えます。
   • ユーザーによるカスタマイズ：設定で定義されたカスタム ignoreFields を適用します。

   これにより、データベースの ID やタイムスタンプが変化しても、実行ごとにエンドポイントの構造が安定して保たれます。

4. 変更がブロック対象ではない WARNING のみであるルート（例：処理時間の回帰）は、個別の行に報告され、「Routes: N unchanged」の集計にも、--json 出力の summary.passed にも含まれません。

既知の制限事項

これらは v1 で意図的に選択したトレードオフです。網羅的な検出よりも、誤検知をゼロにすることを優先しています。これらはロードマップに含まれており、意図しないものではありません。

• テストの識別はベストエフォートです。 regressguard check は失敗したテストの名前（jest、vitest、bun、go test の出力）を記録し、ベースラインでは成功していたテストが失敗し始めると、失敗数の合計が変わらなくても CRITICAL としてフラグを立てます。ランナーの出力から名前を解析できない場合（またはベースラインが名前の記録より前に作成された場合）は、失敗数の比較にフォールバックし、失敗したテストの数が増加した場合にのみ CRITICAL とします。テストごとのアサーションを網羅的に行うには、CI で通常のテストランナーと regressguard check を併用してください。
• 配列のスキーマは最初の要素から推定されます。 スキーマ正規化では、JSON 配列の形状を最初の要素を使って表します。後続の要素の形状が異なる場合（異種配列）、その違いはスキーマハッシュに反映されず、フラグも立ちません。

---

終了コード

コード	意味
0	合格、または警告のみ — 安全にコミットできます
1	重大なリグレッションを検出 — コミットはブロックされます
2	使用方法、設定、または実行時のエラー

---

スクリプトと CI

# JSON output for scripts and agents
regressguard check --json | jq .status

# Verbose diagnostics on stderr (stdout stays clean JSON)
regressguard check --json --verbose

# Disable color for CI
NO_COLOR=1 regressguard check

GitHub Action — すべての PR で regressguard check を実行し、検出内容をコメントします。

- uses: Bharath-code/regressguard@v0
  with:
    server-command: npm run dev

プルリクエストでは、アクションはベースブランチにコミットされたスナップショット（regressguard check --base origin/main）と比較するため、.regressguard/snapshot.json を編集してリグレッションを隠そうとする PR も失敗します。ベースラインが変更された場合に人間の承認を必須にするには、CODEOWNERS ルールを設定してください。

/.regressguard/snapshot.json  @your-handle

.regressguard/snapshot.json をコミットしてください（regressguard init は .gitignore に .regressguard/* と !.regressguard/snapshot.json を追加します）。.regressguard/ 内のそれ以外のファイルはローカルに保持されます。

すべての入力（バージョンの固定、作業ディレクトリ、サーバー URL）については、action.yml を参照してください。

---

対応スタック（v1）

• フレームワーク：Next.js App Router、Express、Hono
• テストランナー：Vitest、Jest、Bun test、npm test
• パッケージマネージャー：npm、pnpm、yarn、bun
• 認証：Bearer トークン、Cookie ヘッダー、パブリックルート

Python、FastAPI、Django のサポートは v2 で予定されています。

---

デモ用フィクスチャ

デモとテスト用に、最小構成の Next.js API フィクスチャが fixtures/nextjs-app に含まれています。fixtures/README.md を参照してください。

---

オープンコア

このリポジトリの CLI と MCP サーバーは、永久に無料かつ MIT ライセンスです。ホスト型のチーム向けレイヤー（リポジトリ横断ダッシュボード、履歴の保持、コンプライアンス用エクスポート）の仕様は、docs/paid-layer-spec.md にまとめられています。1 台のマシンで 1 つのリポジトリに対して実行するものはすべて無料のままであり、有料レイヤーは追加機能のみを提供します。

---

変更履歴

リリース履歴については、CHANGELOG.md を参照してください。

---

ライセンス

MIT — LICENSE を参照してください。

---

git-scope と同じ開発者によるプロジェクトです。