Echoproof

Echoproof

日本語 | English

実際のトラフィックに基づいて、コードを変更するたびに API の動作を検証します。

Echoproof は、サービスの実際のリクエストとレスポンスを記録し、コード変更後のビルドに対して再生して、何が、どのエンドポイントのどのフィールドで、リクエストの何パーセントにおいて変わったのか、そしてその変更が意図されたものかどうかを報告します。結果は CI のゲートとして、またはコーディングエージェント（Claude Code、Cursor など）が自分の作業を検証するために直接利用できます。

record  ->  replay ke build lama dan baru  ->  diff semantik  ->  nilai terhadap niat  ->  gate

目次

• Echoproof を使う理由
• 主な機能
• インストール
• クイックスタート
• デモ
• コンセプト
• コマンドリファレンス
• 設定
• レポートの読み方
• CI との統合
• コーディングエージェントとの統合（MCP）
• セキュリティとプライバシー
• 制限事項
• 開発
• ライセンス

Echoproof を使う理由

コードの大部分が AI エージェントによって書かれるようになると、変更の量は人間がレビューできる能力をはるかに上回るペースで増加します。テストが通り、差分が整って見えても、システムの動作が正しいままとは限りません。テストは想定に基づいて書かれる一方で、バグは思いもよらない実データの組み合わせから発生することが多いためです。

Echoproof は、ユニットテストでもコードレビューでも答えられない次の問いに答えます。

この変更によって実際のトラフィックに対するシステムの動作は変わりますか。また、その変更は意図したものですか？

Echoproof が検出する例：ある PR は「カタログに currency フィールドを追加する」ことを意図していましたが、引数を誤った位置に設定してしまいました。その結果、8 種類のメニューのうち 3 種類の価格が変わり、残りの 5 種類は正しいままでした。ユニットテストは通り、コードの差分も問題なさそうに見えます。Echoproof はカタログの各リクエストで products[*].price: 18000 -> 22000 と報告し、リグレッションとしてマークします。

主な機能

• 実際のトラフィックから記録します。 すべてのリクエストとレスポンスを記録するリバースプロキシです。機密データはディスクに書き込む前にマスキングされます。
• セマンティック差分。 JSON をテキストの行単位ではなく、フィールド単位で比較します。変更をエンドポイントとフィールドごとにグループ化し、breaking、behavior、additive に分類します。
• ノイズに強い設計。 UUID、タイムスタンプ、ランダムな値を自動的に識別します。古いビルドを 2 回再生して、実行ごとに変化するフィールドを学習します。
• 状態を考慮した安全性。 エンドポイントごとに許可されない限り、書き込みリクエストは再生されません。古いビルドと新しいビルドは同じデータ上で比較し、各ラウンドの間にリセットコマンドを実行します。
• 変更の意図を考慮します。 変更の各グループを Claude が PR またはエージェントのタスクの説明に照らして評価できます。意図で説明されない変更はリグレッションとしてマークされます。
• CI とエージェントに対応。 マージゲート用の終了コード、PR コメント用の Markdown レポート、自動化用の JSON、そしてコーディングエージェント用の MCP サーバーを提供します。

インストール

Homebrew（macOS と Linux）

brew install est57/tap/echoproof

すぐに使えるバイナリ（推奨）

リリースページからご利用のプラットフォーム向けのアーカイブをダウンロードするか、ターミナルから実行します。

VERSION=v0.1.0
TARGET=aarch64-apple-darwin   # atau x86_64-apple-darwin, x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu
curl -sLO https://github.com/est57/echoproof/releases/download/$VERSION/echoproof-$VERSION-$TARGET.tar.gz
curl -sLO https://github.com/est57/echoproof/releases/download/$VERSION/echoproof-$VERSION-$TARGET.tar.gz.sha256
shasum -a 256 -c echoproof-$VERSION-$TARGET.tar.gz.sha256
tar -xzf echoproof-$VERSION-$TARGET.tar.gz
sudo mv echoproof-$VERSION-$TARGET/echoproof /usr/local/bin/

echoproof --version

Cargo を使う場合

Rust 1.85 以降がインストールされている場合：

cargo install echoproof

ソースコードから

要件： Rust 1.85 以降。デモの実行には curl が必要です。

git clone https://github.com/est57/echoproof.git
cd echoproof
cargo install --path crates/echoproof-cli

バイナリ echoproof は ~/.cargo/bin にインストールされます。このディレクトリが PATH に含まれていることを確認してください：

echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

echoproof --version

クイックスタート

以下の手順では、テスト環境で稼働中のサービスに対するコード変更を検証します。

1. 設定ファイルを作成します（任意。すべての設定にはデフォルト値があります）：

echoproof init

2. トラフィックを記録します。 サービスの前にプロキシを起動し、アプリケーション、Postman、自動テストからプロキシのアドレスにリクエストを送信します：

echoproof record --upstream http://127.0.0.1:8000 --listen 127.0.0.1:8080 --out traffic.jsonl

代表的なトラフィックが集まったら、Ctrl-C で停止します。

Laravel アプリケーションはプロキシなしで記録できます。 echoproof/laravel を使い、composer require echoproof/laravel を実行して、.env に ECHOPROOF_RECORD=true を設定すると、同じマスキングルールでトラフィックが storage/echoproof/traffic.jsonl に書き込まれます。

3. 2つのビルドを実行します。 変更前のバージョン（base）と変更後のバージョン（PR）を、同じデータベースを使って実行します。

4. 比較します：

echoproof check -s traffic.jsonl --base http://127.0.0.1:8001 -t http://127.0.0.1:8002

5. 結果を確認します。 終了コード 0 は予期しない変更がないこと、1 はリグレッションがあること、2 はエラーが発生したことを示します。レポートの読み方を参照してください。

変更が意図に沿っているか評価するには、PR の説明とコードの差分を追加します：

git diff main...HEAD > change.diff
echoproof check -s traffic.jsonl --base http://127.0.0.1:8001 -t http://127.0.0.1:8002 \
  --intent-file pr-description.md --code-diff change.diff --output echoproof-report.md

デモ

完全なデモは約10秒で実行でき、自分のサービスは不要です：

./scripts/demo.sh

デモでは、状態を持つ小規模な POS バックエンド（examples/demo-shop）を使用します。注文ごとに商品の在庫が減ります。「エージェントによる PR」では商品に currency フィールドを追加することを意図していますが、プロモーション割引とクーポンの適用方法も変更されます。

手順	内容
1. 本番バージョンから2,000件のリクエストを記録	記録プロセス
2. 同じバージョンにリプレイし、記録と比較	記録中に在庫が減っていることによる誤検知
3. --base と --reset を指定し、安全モードで base と PR のビルドを比較	誤検知が解消されます。currency が検出されます。書き込みリクエストは未検証として報告されます
4. 手順3と同様に、--allow-writes "POST /orders" を指定	プロモーションとクーポンを併用した注文でのみ、割引のバグを検出
5. Claude による意図の評価（ANTHROPIC_API_KEY が設定されている場合）	currency は意図された変更、割引の変更はリグレッションと評価されます

概念

スナップショット

スナップショットは、1行につき1組のリクエストとレスポンスを含む JSONL ファイルです。機密性の高いヘッダーとフィールドは、書き込まれる前にマスキングされます。同じスナップショットを繰り返し使用して、複数の PR を検証できます。

2つの比較モード

モード	コマンド	適した用途
記録との比較	echoproof check -s traffic.jsonl -t URL_PR	ステートレスなサービス、または記録時と同じデータを持つ環境
Base と PR の比較	echoproof check -s traffic.jsonl --base URL_BASE -t URL_PR	データベースを持つサービス（推奨）

base と PR の比較モードでは、記録されたレスポンスは基準として使用されません。Echoproof は、同じデータを使って両方のビルドに同じトラフィックを送信します：

reset  ->  replay ke base         ->  acuan
reset  ->  replay ke base lagi    ->  field yang berbeda dicatat sebagai noise
reset  ->  replay ke PR           ->  kandidat
diff acuan dan kandidat, abaikan noise

各ビルドのサーバーアドレス（画像 URL やページネーションリンクに含まれる http://127.0.0.1:8001 など）は自動的に正規化されるため、異なるポートで実行されている2つのビルドを比較できます。

安全モード

デフォルトでは、GET、HEAD、OPTIONS メソッドのみがリプレイされます。書き込みリクエストはスキップされ、合格としてカウントされません。レポートにはその件数が記載され、動作が未検証であることが警告されます。

変更を許可できる環境、またはリセット可能な環境に限り、エンドポイントごとに書き込みリクエストを許可します。

echoproof check ... --allow-writes "POST /orders" --allow-writes "PUT /cart/*"

各ラウンドの前に状態を復元するには、--reset（または replay.reset）を使用します。たとえば、データベースのダンプを復元するか、テスト環境のリセットエンドポイントを呼び出します。ノイズを学習中の場合、Echoproof はリセットなしで書き込みリクエストをリプレイすることを拒否します。実行間の状態変化がノイズとして扱われ、リグレッションが隠れてしまうためです。

セマンティック差分

• JSON はフィールド単位で比較されます。5 と 5.0 は同じとみなされ、キーの順序は無視されます。

• 変更はそれぞれ次のように分類されます。

  分類	例
  breaking	フィールドの欠落、型の変更（null への変更を含む）、2xx ステータスからエラーへの変更
  behavior	値の変更、配列の長さの変更、ステータスの変更
  additive	新しいフィールド

• パスは正規化されます。/products/42 は GET /products/{id} に、items[3].price は $.items[*].price になります。変更はリクエストごとに 1 回だけカウントされます。

• 同じ形式の UUID、ULID、日時はノイズとして扱われます。日付のみ（例：2026-10-14）は引き続き比較されます。

変更の意図

Echoproof に想定される変更を伝える方法は 2 つあります。

方法	粒度	使用する場面
--expect "GET /products/*"	エンドポイント	手軽で、外部サービスも不要
--intent "..."	エンドポイント、フィールド、値	想定される変更とバグが同じエンドポイントで発生しうる場合

--expect は、指定したエンドポイントでのすべての変更を許可します。PR でカタログを変更する際に、誤ってカタログの価格も壊してしまった場合、--expect "GET /catalog" ではその変更を検出できません。

--intent を指定すると、変更の各グループが Claude によって評価され、例示値を引用した理由とともに、intended、regression、unclear のいずれかの判定が付与されます。評価材料には、変更の意図、コード差分（任意）、影響を受けたリクエストの割合、変更前後の値を含む変更リクエストの例、比較対象となる同じエンドポイント内の未変更リクエストの例が含まれます。unclear の判定と評価されなかったグループは、リグレッションとして扱われます（フェイルクローズ）。

意図の評価には Anthropic API キーが必要です。1 回の実行につき API 呼び出しは 1 回で、変更がある場合にのみ呼び出されます。デフォルトモデルでの一般的な費用は、1 回の実行あたり約 0.01～0.02 米ドルです。

サードパーティへの呼び出し

決済ゲートウェイ、メッセージングサービス、その他の API を呼び出すサービスは、リプレイ時に実際に接続してはなりません。echoproof/laravel を使用すると、これらの呼び出しは各リクエストとともに記録され、ECHOPROOF_REPLAY=true を指定して実行したビルドは記録から応答し、それ以外のすべての呼び出しをブロックします。どちらのビルドも同一のサードパーティ応答を受け取り、Echoproof は各ビルドが 送信した 内容を比較します。

  x POST /checkout  3/3 changed (100.0%)  unexpected
      behavior  value changed   outbound[POST pay.example.com/v2/charges] $.amount  (3 requests)
            outbound[POST pay.example.com/v2/charges] $.amount: 18000 -> 1800000

この例では、チェックアウトのレスポンスは同一で、ゲートウェイに送信された金額のみが変わっています。記録されたことのない呼び出しは、breaking レベルの call added として報告されます。ビルドが Echoproof で読み取れない呼び出しを報告した場合、そのリクエストは検証されずに合格するのではなく、チェックに失敗します。

すべての言語：アウトバウンドプロキシ

Laravel 以外のサービスや、独自の HTTP クライアントを持つ SDK 経由でサードパーティーを呼び出すサービスでは、Echoproof をサービスのアウトバウンド呼び出し用プロキシとして使用できます。

echoproof ca init                                   # CA per proyek di .echoproof/, kunci mode 0600
echoproof ca env --runtime php                      # atau node, python, go: setting untuk service
echoproof record --upstream http://127.0.0.1:8000 --listen 127.0.0.1:8080 -o traffic.jsonl \
  --outbound-listen 127.0.0.1:8899                  # merekam setiap panggilan bersama request yang berjalan
echoproof check -s traffic.jsonl --base http://127.0.0.1:8001 -t http://127.0.0.1:8002 \
  --outbound-proxy 127.0.0.1:8899                   # menjawab setiap panggilan dari rekaman

プロキシと CA の設定は、テスト対象のサービスにのみ適用してください。Echoproof 自体は環境変数のプロキシ設定を無視します。リプレイ時、プロキシから実際の宛先への経路はありません。プロキシ設定を無視するクライアント（NODE_USE_ENV_PROXY=1 を指定していない Node 22.21 より前のバージョンや、独自にプロキシを設定するコードなど）は、実際のサービスを呼び出しますが、成功としてではなく call removed として記録されます。可能であれば、外部ネットワークへの経路がない状態でテストビルドを実行してください。サードパーティーが返す秘密の値（返された URL 内の API キーや、返されたヘッダー内のトークンなど）もマスキングされます。記録時に呼び出しを正確に特定できるのは、リクエストが一度に 1 つずつ届く場合のみです。そのため、ステージング環境またはスクリプトからのトラフィックを使って記録してください。

コマンドリファレンス

コマンド	機能
echoproof init	各設定の説明を含む echoproof.toml を作成します
echoproof record --upstream URL --out FILE	トラフィックを記録するリバースプロキシを起動します
echoproof replay -s FILE -t URL -o FILE	スナップショットをターゲットにリプレイし、そのレスポンスを保存します
echoproof diff BASELINE CANDIDATE	2 つのスナップショットを比較します
echoproof check -s FILE -t URL	記録に対してリプレイと差分比較を 1 ステップで実行します
echoproof check -s FILE --base URL -t URL	同じ状態でベースと PR をリプレイして差分比較します
echoproof accept CANDIDATE --baseline FILE	レビュー済みのレスポンスを新しいベースラインにします
echoproof mcp	コーディングエージェント向けの MCP サーバーを起動します

共通オプション：

オプション	対象	説明
--config FILE	すべて	設定ファイル。デフォルトは echoproof.toml です
--expect PATTERN	diff、check	変更が予想されるエンドポイント。複数回指定できます
--intent TEXT、--intent-file FILE	diff、check	Claude による評価用の変更意図
--code-diff FILE	diff、check	意図を評価するためのコード差分
--format text|markdown|json	diff、check	ターミナルへの出力形式。デフォルトは text です
--output FILE	diff、check	レポートを保存します。形式は拡張子（.md、.json）に従います
--max-examples N	diff、check	変更グループごとの例の数。デフォルトは 2 です
--base URL	check	ベースと PR の比較モードで使用するベースビルド
--reset CMD	check	各実行前に状態を復元するシェルコマンド
--noise-runs N	check	ノイズを学習するためにベースに対して追加でリプレイする回数。デフォルトは 1 です
--allow-writes PATTERN	replay、check	書き込みリクエストのリプレイを許可するエンドポイント。複数回指定できます
--concurrency N	replay、check	並列リクエスト数。デフォルトは 1 です
--save FILE	check	候補スナップショットを保存します

エンドポイントのパターン：POST /orders、GET /products/*（* は 1 つのセグメントに一致）、/admin/**（** は複数のセグメントに一致）、またはすべてに一致する *。

終了コード： 0 は成功、または予想された変更のみ、1 はリグレッションあり、2 はエラー（設定、ネットワーク、リセットの失敗、または意図の評価の失敗）です。

設定

すべての設定は任意です。echoproof init を実行すると、すべての設定とその説明を含むファイルが作成されます。

[record]
upstream = "http://127.0.0.1:8000"
listen = "127.0.0.1:8080"

[sanitize]
# Diterapkan saat merekam dan saat replay, sehingga nilai yang disamarkan tetap sebanding.
redact_headers = ["authorization", "cookie", "set-cookie", "x-api-key"]
redact_fields = ["password", "token", "pin", "card_number", "phone", "email"]

[replay]
concurrency = 1                                          # naikkan hanya untuk endpoint tanpa state
timeout_ms = 10000
headers = { authorization = "Bearer ${STAGING_TOKEN}" }  # menggantikan header yang disamarkan
safe_methods = ["GET", "HEAD", "OPTIONS"]
allow_writes = ["POST /orders"]                          # default kosong (mode aman)
reset = "./scripts/restore-test-db.sh"
noise_runs = 1

[diff]
ignore = ["updated_at", "$.meta.trace_id", "items[*].etag"]
expect = ["GET /products/*"]
auto_noise = true
compare_headers = ["content-type"]

[judge]
model = "claude-opus-5-5"
effort = "high"                                          # low, medium, high, xhigh, max
fallbacks = true

[mcp]
allowed_hosts = []                                       # host selain localhost yang boleh dipakai agent

ignore パターンは、名前のみ（updated_at）の場合、どの階層にも一致します。$ で始まるパターンやドットを含むパターン（$.meta.trace_id、items[*].etag）は、body のルートから評価されます。

環境変数：

変数	説明
ANTHROPIC_API_KEY	意図の判定に使う API キー（代替：ANTHROPIC_AUTH_TOKEN）
ANTHROPIC_WORKSPACE_ID	API キーが単一のワークスペースに紐付いていない場合に必須です
ANTHROPIC_BASE_URL	代替 API エンドポイント。localhost を除き、https が必要です
ECHOPROOF_JUDGE_TRACE	デバッグ用に判定リクエストとレスポンスをファイルに保存します（権限 0600）

レポートの確認

ターミナルでのレポート例：

echoproof: REGRESSION - 83 exchanges, 5 changed, 78 unchanged
  ignored 1 noisy fields that differ between runs of the base build: GET /up body
  intent judged by claude-opus-5-5: The currency field is added as intended. ...

  x GET /catalog                5/5 changed (100.0%)  unexpected
      behavior  value changed   $.result.products[*].price  (5 requests)
          [regression] The diff swaps the third argument of products() ...
          GET /catalog  [00e36fd43ade]
            $.result.products[1].price: 18000 -> 22000
      additive  added           $.result.currency  (5 requests)
          [intended] Adding 'currency' => 'IDR' matches the intent.

  - GET /branches               0/5 changed (0.0%)  unchanged

result: FAIL

記号	意味
x	エンドポイントが予期しない形で変化しました（リグレッション）
~	エンドポイントが期待どおり、または意図どおりに変化しました
-	エンドポイントに変化がないか、リクエストがリプレイされていません
(N requests)	該当する変化があったリクエストの数
[intended]、[regression]、[unclear]	意図の判定結果とその理由

その他の形式：

• --format markdown は、PR コメントにそのまま使えるレポートを生成します。
• --format json は、問題ごとにコーディングエージェントへ返せる一文を含む、構造化データ findings を生成します。

変更を確認して承認したら、その結果を新しいベースラインにします：

echoproof replay -s traffic.jsonl -t URL_PR -o candidate.jsonl
echoproof accept candidate.jsonl --baseline traffic.jsonl

CI との連携

Echoproof GitHub Action を使用します。この Action はリリースバイナリをインストールし、echoproof check を実行して、レポートをジョブのサマリーに書き込み、判定結果を出力として提供します：

- name: Start base and PR builds
  run: ./scripts/start-builds.sh   # base on :8001, PR on :8002, same test database

- run: git diff origin/${{ github.base_ref }}...HEAD > change.diff

- name: Behavior check
  id: echoproof
  uses: est57/echoproof-action@v1
  with:
    snapshot: traffic/baseline.jsonl
    base: http://127.0.0.1:8001
    target: http://127.0.0.1:8002
    reset: ./scripts/reset-db.sh
    intent: ${{ github.event.pull_request.title }}
    code-diff: change.diff
    anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}

- name: Comment on PR
  if: always()
  run: gh pr comment ${{ github.event.number }} --body-file "${{ steps.echoproof.outputs.report }}"
  env:
    GH_TOKEN: ${{ github.token }}

リグレッションがあるとステップが失敗し、マージがブロックされます。レポートのみを行う場合は、fail-on-regression: false を使用してください。他の CI システムでは、バイナリをインストールして echoproof check を直接実行します。終了コード 1 はリグレッションを意味します。

コーディングエージェントとの連携（MCP）

この録画では、Claude Code（Sonnet）に注文サービスのレジ担当者名を整理するよう依頼しています。同じファイルには、あらかじめ割引バグが仕込まれていました。チェックに失敗すると、エージェントはそのリグレッションをたどって自分が作成したものではないバグを見つけて修正し、チェックに合格してから初めてタスクの完了を宣言します。

echoproof mcp は、stdio を介して Model Context Protocol サーバーを実行します。これにより、コーディングエージェントは作業の完了を宣言する前に、自身が行った変更を確認できます。

コーディングエージェントにインストールする

まず echoproof バイナリをインストールします（brew install est57/tap/echoproof または cargo install echoproof）。以下の各エージェントは、プロジェクトフォルダーで echoproof mcp を実行するため、ローカルのビルドとスナップショットにアクセスできます。

Claude Code、プラグインとして（推奨）。このプラグインは MCP サーバーと verify-behavior スキルをインストールします。このスキルによって Claude は、変更をいつ、どのように検証すればよいかがわかるため、CLAUDE.md に追加の指示を記述する必要はありません。

/plugin marketplace add est57/echoproof
/plugin install echoproof@echoproof

シェルからは、claude plugin marketplace add est57/echoproof と claude plugin install echoproof@echoproof を実行します。

Claude Code、MCP サーバーのみ：

claude mcp add echoproof -- echoproof mcp

Cursor（プロジェクト内の .cursor/mcp.json または ~/.cursor/mcp.json）、Claude Desktop（claude_desktop_config.json）、および mcpServers マップを読み込むその他のクライアント：

{ "mcpServers": { "echoproof": { "command": "echoproof", "args": ["mcp"] } } }

Copilot エージェントモードを使用する VS Code（.vscode/mcp.json）：

{ "servers": { "echoproof": { "type": "stdio", "command": "echoproof", "args": ["mcp"] } } }

Codex CLI：codex mcp add echoproof -- echoproof mcp を実行するか、~/.codex/config.toml に設定します。

[mcp_servers.echoproof]
command = "echoproof"
args = ["mcp"]

Gemini CLI：gemini mcp add echoproof echoproof mcp を実行すると、プロジェクト内に .gemini/settings.json が書き込まれます。

Claude Code との連携は、エンドツーエンドでテスト済みです。その他のクライアントは同じ標準の MCP stdio を使用しますが、まだテストされていません。利用レポートを歓迎します。ChatGPT や Claude.ai などのウェブベースのアシスタントは、プロバイダーのサーバー上で実行され、コンピューター上のビルドにアクセスできないため、Echoproof を使用できません。

Echoproof は、MCP Registry 公式サイトに次の名前で登録されています。

mcp-name: io.github.est57/echoproof

ツール

ツール	主な入力	機能
echoproof_check	snapshot、target、base、intent、expect、allow_writes	リプレイと差分比較を実行します。エージェント向けレポート、構造化 JSON、run_id を返します
echoproof_diff	baseline、candidate、intent、expect	既存の 2 つのスナップショットを比較します
echoproof_exchange	run_id、id	完全なリクエスト、基準側と候補側のレスポンス、およびフィールドごとの変更を返します

エージェントのワークフロー：コードを変更してビルドを実行し、タスクを intent として echoproof_check を呼び出します。結果にリグレッションがあれば、echoproof_exchange で例を確認し、コードを修正して再度検証します。新しいベースラインの承認は引き続き人間が判断するため、サーバーには意図的に accept が用意されていません。

セキュリティとプライバシー

記録されるデータ

• [sanitize] に登録されたヘッダーとフィールドは、ディスクに書き込まれる前に [REDACTED] に置き換えられます。電話番号、メールアドレス、識別番号など、ドメイン内の個人データを含むフィールドを追加してください。
• スナップショットには業務データが含まれます。公開リポジトリの外に保存するか、.gitignore に含まれていることを確認してください。

--intent を使用する際に Anthropic に送信されるデータ

意図のテキスト、コード差分（指定されている場合）、エンドポイント名とフィールド名、影響を受けたリクエスト数、サンプルのリクエスト本文と変更前後の値（いずれもサニタイズ後）が送信されます。4,000 文字を超えるサンプル本文は切り詰められます。--intent を使用しない場合、データは送信されません。

組み込みの保護機能

• 書き込みリクエストは、エンドポイントごとに明示的な許可がない限りリプレイされません。
• スナップショット内のパスは検証され、挿入されたリクエストや認証情報が別のホストに送信されることはありません。
• レスポンスは 32 MB に制限されています。
• API キーは、localhost を除き、https 経由でのみ送信されます。
• 外部からのテキスト（意図、差分、トラフィック）によって評価用プロンプトの構造が変更されたり、Markdown レポートの表が壊れたりすることはありません。

コーディングエージェント向けの保護機能（MCP）

• target と base に指定できるのは localhost のみです。例外は、ホストが [mcp] allowed_hosts に登録されている場合です。リプレイでは replay.headers のヘッダーが引き継がれるため、エージェントがそれらを別のホストに送信できないようにする必要があります。
• ファイルパス（snapshot、save、code_diff_file）はプロジェクトフォルダー内にある必要があります。フォルダー外へのシンボリックリンクは拒否されます。
• リセットコマンドは echoproof.toml からのみ読み込まれ、エージェントから読み込まれることはありません。

制限事項

• 書き込みリクエストには、リセット可能なテスト環境が必要です。そのような環境がない場合は、安全モードを使用してください。このモードでは読み取りリクエストのみを検証します。
• サードパーティへの呼び出しは、echoproof/laravel（Laravel の Http クライアント）または外部プロキシ（プロキシ設定に従う任意のクライアント）を通じて、記録から応答します。プロキシ設定を無視するクライアントや、HTTP 以外の依存関係（SMTP、キュー、生のソケット経由の gRPC）は引き続き実際に呼び出されます。前者は call removed として表示されます。
• リクエスト間の ID：逐次リプレイ（concurrency = 1）では、記録時とは異なるリプレイ中に生成された ID（記録時の注文番号 9812、リプレイ時の注文番号 57 など）が、同じエンティティに対する後続のリクエスト（/orders/9812、order_id）に引き継がれます。トラフィックの記録時点ですでに存在していたデータの ID はマッピングできません。--base を指定した場合、そのようなリクエストは変更なしとは判定されず、not reproduced として報告されます。--no-id-mapping または [replay] map_ids = false でマッピングを無効にできます。
• リクエストの順序は、逐次リプレイ（concurrency = 1）によって維持されます。大量のトラフィックでは時間がかかることがあり、並列リプレイが安全なのはステートレスなエンドポイントのみです。
• 発生するはずの変更が発生しなかったことの検出は困難です。Echoproof は変更されたリクエストを報告するためです。
• まれにしか発生しないノイズは、1 回の学習実行では見逃される可能性があります。必要に応じて --noise-runs を増やすか、ignore パターンを追加してください。

開発

リポジトリの構成

crates/echoproof-core     format snapshot, sanitasi, diff, laporan, penilaian niat
crates/echoproof-cli      binary `echoproof`: perekam, replay, CLI, server MCP
examples/demo-shop     backend POS untuk demo dan eval
eval/judge             eval penilai niat: kasus uji, runner, dan grader
scripts/demo.sh        demo end-to-end

テストの実行

cargo test
cargo clippy --all-targets -- -D warnings

意図判定の評価

eval/judge には、判定器が意図された変更とリグレッションをどれほど正確に区別できるかを測定する、ラベル付き PR シナリオが 26 件（変更グループは 54 件）含まれています。デフォルト設定では、78 回の実行で判定器はゲート判定の正解率 100% を記録し、誤警告はありませんでした。現在のシナリオでは、より優れた設定を区別するには難易度が不十分なため、実際のシステムからのケースを追加しています。ケースの一覧は eval/judge/CASES.md にあります。

eval/judge/prepare.sh                                                         # buat fixture, tanpa biaya API
node eval/judge/run-eval.mjs --flow eval/judge/runs/intent-judge --variant baseline --reps 3
node eval/judge/summarize.mjs eval/judge/runs/intent-judge/baseline

ハーネスが --approve-harness で一度承認されるまで、ランナーは実行を拒否します。また、ランナーのコード、ケース、または判定器が変更されるたびに、再承認を求めます。

ライセンス

Echoproof は、選択した次のいずれかのライセンスの下でライセンスされています。

• Apache License, Version 2.0（LICENSE-APACHE）
• MIT License（LICENSE-MIT）

別途明記されていない限り、このプロジェクトに含めるために提出されたすべての貢献は、追加条件なしで同じ方法によりデュアルライセンスされます。