evolveguard

evolveguard

機能 • クイックスタート • CLI リファレンス • エージェントネイティブな使い方 • MCP サーバー • 比較 • よくある質問

Claude Agent Skill または Claude Code の MEMORY.md ファイルが自らを編集したとき、その変更が反映される前に動作のドリフトを検出します。

# PyPI -- Python CLI + library (genuine port, not a Node wrapper)
pip install evolveguard-cli

# npm -- JavaScript/TypeScript CLI + library
npm install -g evolveguard-cli

メモ

どちらのパッケージも公開済みで、名称も統一されています。PyPI と npm の両方で evolveguard-cli です （旧名称の evolveguard から 2026-07-19 に改名。旧パッケージは両方のレジストリで非推奨になりました）。npm install -g evolveguard-cli と pip install evolveguard-cli はどちらも現在利用できます。以下のデモ GIF はローカルビルドではなく、 公開済みパッケージを使って録画したものです。

機能

evolveguard record ./SKILL.md --fixtures ./fixtures.json
# ... skill gets edited, by a human or an agent ...
evolveguard check ./SKILL.md

EvolveGuard v0.2.0 -- Regression Check
skill: monorepo-scanner  baseline: 2026-07-15  fixtures: 1

[DRIFT] fixture: "scan a monorepo"  new tool call: fs.write (baseline had none)
         -> new tool call: fs.write (baseline had none) -- this edit introduces a
            capability the baseline never used

0 PASS, 1 DRIFT, 0 FAIL
exit code 1 (DRIFT blocks merge by default; override with --allow-drift)

これは、このリポジトリ独自の fixtures/labeled-non-breaking-edits/case-03-add-write-capability/ テストケースからの実際の出力です。スキルのフロントマターで filesystem: read-only が read-write に 変わるケースを設定しています。実際に試すには、このフォルダー内の before/SKILL.md に対して fixtures.json を使って evolveguard record を実行し、その後 after/SKILL.md に対して evolveguard check を実行してください。

特長

ライブエージェント実行ではなく、静的解析です。 record はスキルファイルの YAML フロントマター（宣言された tools、network、filesystem、scope、および同梱されている hooks）を解析し、スキルの本文とフックスクリプトをスキャンして、ネットワーク呼び出しやファイルシステムへの書き込みを示す証拠を調べ、それらを組み合わせて機能の範囲を作成します。check は同じロジックで編集後のファイルを再解析し、結果を差分比較します。TypeScript 版、Python 版のどちらでも、いずれのコマンドも eval を実行したり、サブプロセスを呼び出したり、スキルのフックスクリプトを実行したりしません。

2 段階の差分比較で、単一のフィクスチャでは見逃す可能性のある逸脱を検出します。 各フィクスチャの expectedToolCalls は、記録された機能の範囲をそのフィクスチャが対象とするものに絞り込みますが、check はスキルの機能全体の範囲も別途差分比較します。どのフィクスチャの expectedToolCalls にも含まれていない新たな機能も、黙って通過するのではなく、surfaceChanges エントリーとして表示されます。このリポジトリ独自の case-04-scope-widened フィクスチャで検証済みです。このフィクスチャでは、fs.write のスコープが ./workspace/** から ./** に広がります。

ラベル付きコーパスで再現性のある偽陽性ゼロを実現します。 npx vitest run src/evolveguard/benchmark.test.ts を実行すると、fixtures/labeled-non-breaking-edits/ に対して記録／チェック／差分比較のパイプラインが実行されます。このコーパスには、互換性を損なわないと手動でラベル付けされたケースが 2 件（表現の調整、誤字の修正）、互換性を損なうとラベル付けされたケースが 3 件（新たな書き込み機能、スコープの拡大、ネットワーク呼び出しが追加されたフックスクリプト）含まれています。このコミット時点では、互換性を損なわない 2 件はいずれも問題なく通過し、逸脱として検出されたものは 0 件です。コーパスはまだ小規模で、実際のスキル編集がさらに報告されるのに伴って拡張されます。

フックスクリプトに対するパストラバーサルガードを備えています。 スキルで宣言されたフックのパスは、読み込み前にそのスキル自身のディレクトリを基準に解決され、検証されます。これには、字句的な包含チェックの通過後に実行されるシンボリックリンクによる範囲外への脱出の再チェックも含まれます（src/evolveguard/paths.ts および python/src/evolveguard/paths.py）。

すべてのサブコマンドが --json に対応しています。 record、check、report はいずれも --json フラグを受け取り、安定した schemaVersion 付きの構造を返すため、コーディングエージェントはどのコマンドもサブプロセスとして呼び出し、結果を直接解析できます。

独立して保守され、互換性のある形式を採用した 2 種類の配布版です。 npm パッケージ（TypeScript、リポジトリのルート）と PyPI パッケージ（Python、python/）は、同じフロントマターのスキーマを解析し、バイト単位で互換性のあるベースラインとレポートの JSON を生成します。どちらかの CLI で記録したベースラインを、もう一方の CLI でチェックできます。ファイル形式の詳細については、docs/concepts.md をご覧ください。

evolveguard は、スキルが何を実行できると 宣言または示している かの変化を検出します。ライブの LLM エージェントを実行したり、実際の会話の記録を再生したりはしないため、特定のプロンプトに対してエージェントの実際の動作が変わるかどうかは判断できません。これは意図的なスコープ上の制限であり、ホスト環境が不要で、プリコミットフックや CI ジョブ内で完全にオフライン実行できる理由でもあります。

クイックスタート

# 1. Record a baseline against a skill and its labeled fixtures
evolveguard record ./skills/my-skill/SKILL.md --fixtures ./fixtures/my-skill.json
# writes ./skills/my-skill/.evolveguard-baseline.json

# 2. Edit the skill (by hand, or let an agent edit it)

# 3. Check for drift
evolveguard check ./skills/my-skill/SKILL.md
# writes ./evolveguard-report.json, exits 1 if drift was found

フィクスチャファイルは、ラベル付きプロンプトと、それぞれが使用すると想定されるツール呼び出しの形を並べた JSON 配列です。

[
  {
    "id": "scan-a-monorepo",
    "prompt": "scan a monorepo",
    "expectedToolCalls": [{ "tool": "fs.read" }, { "tool": "fs.write" }]
  }
]

expectedToolCalls は省略可能です。省略すると、そのフィクスチャはスキルの機能全体の範囲を使用するものとして扱われます。scopeMatches（glob）を指定すると、ツールの対象を特定のファイルシステムスコープに絞り込めます。例：{ "tool": "fs.write", "scopeMatches": "./workspace/**" }。

CLI コマンドリファレンス

インストール済み CLI の実際の --help 出力から生成されています（npm と PyPI の両方のビルドで確認済みです。フラグとデフォルト値は、どちらの配布版でも同一です）。

Usage: evolveguard [options] [command]

Regression-testing CLI for self-edited Claude Agent Skills (SKILL.md,
MEMORY.md) -- golden-transcript record/replay against a skill's own declared
and inferred capability surface, zero hosted infrastructure.

Options:
  -V, --version                  output the version number
  -h, --help                     display help for command

Commands:
  record [options] <skillPath>   Record a golden-transcript baseline for a
                                 skill against a set of labeled fixtures
  check [options] <skillPath>    Replay the fixtures from a baseline against
                                 the current (possibly edited) skill and report
                                 drift
  report [options] [reportPath]  Print a previously generated
                                 evolveguard-report.json
  mcp                            [coming soon] Expose record/check/report as
                                 MCP tools for a coding agent to call
                                 mid-session
  help [command]                 display help for command

Usage: evolveguard record [options] <skillPath>

Record a golden-transcript baseline for a skill against a set of labeled
fixtures

Arguments:
  skillPath          path to the SKILL.md or MEMORY.md file to baseline

Options:
  --fixtures <path>  path to a fixtures JSON file (array of {id, prompt,
                     expectedToolCalls?})
  --baseline <path>  path to write the baseline file (default:
                     <skill-dir>/.evolveguard-baseline.json)
  --json             output structured JSON instead of human-readable text
                     (default: false)
  -h, --help         display help for command

Usage: evolveguard check [options] <skillPath>

Replay the fixtures from a baseline against the current (possibly edited) skill
and report drift

Arguments:
  skillPath          path to the SKILL.md or MEMORY.md file to check

Options:
  --baseline <path>  path to the baseline file (default:
                     <skill-dir>/.evolveguard-baseline.json)
  --report <path>    path to write the report file (default:
                     "./evolveguard-report.json")
  --allow-drift      exit 0 even if drift is detected (drift is still reported)
                     (default: false)
  --json             output structured JSON instead of human-readable text
                     (default: false)
  -h, --help         display help for command

Usage: evolveguard report [options] [reportPath]

Print a previously generated evolveguard-report.json

Arguments:
  reportPath  path to the report file (default: "./evolveguard-report.json")

Options:
  --json      output structured JSON instead of human-readable text (default:
              false)
  -h, --help  display help for command

終了コード： 0 すべてのフィクスチャが PASS で、サーフェスレベルのドリフトがない場合、1 1 つ以上の DRIFT が見つかった場合（--allow-drift を渡すと、ドリフトを報告しながら終了コードを 0 にできます）、2 使用方法のエラー、または解析に失敗したファイルがある場合です。

警告

npm ビルドの evolveguard --version は現在、公開済みパッケージの package.json のバージョンがより新しいにもかかわらず、0.1.0 を出力します。PyPI ビルドはインストール済みパッケージのメタデータからバージョンを読み取るため、正しく表示されます。npm パッケージの現在の正確な公開バージョン番号が必要な場合は、--version ではなく上記のバッジを使用してください。

エージェントネイティブな使い方

すべてのサブコマンドは、エージェントが直接解析できる構造化出力を得るための --json に対応しています。

evolveguard check ./SKILL.md --json

{
  "schemaVersion": 1,
  "skillName": "monorepo-scanner",
  "results": [
    {
      "id": "scan-a-monorepo",
      "verdict": "DRIFT",
      "changes": [/* ... */]
    }
  ],
  "surfaceChanges": [],
  "summary": { "pass": 0, "drift": 1, "total": 1 },
  "exitCode": 1
}

メモ

Python 配布版には、実際の MCP サーバーが含まれています（下記のMCP サーバーを参照）。 npm／TypeScript 配布版の evolveguard mcp サブコマンドは、まだ「近日公開」のスタブです。提供開始までは、コーディングエージェントからサブプロセスとして record／check／report --json を直接呼び出すか、ツールチェーンの残りが npm パッケージを使用している場合でも、Python MCP サーバーを使用してください。

MCP サーバー

Python 配布版（PyPI の evolveguard-cli）には Model Context Protocol サーバーが含まれているため、MCP 互換エージェント（Claude Desktop、Claude Code など）は、シェルコマンドを実行してテキストを解析することなく、evolveguard を直接呼び出せます。npm／TypeScript 配布版にはまだ含まれておらず、その evolveguard mcp サブコマンドは引き続きスタブです。

pip install "evolveguard-cli[mcp]"

MCP クライアントの設定に追加してください。例として、Claude Desktop の claude_desktop_config.json の場合は次のとおりです。

{
  "mcpServers": {
    "evolveguard": {
      "command": "evolveguard-mcp"
    }
  }
}

公開するツールは run(args: list[str]) の 1 つです。ターミナルで入力するものとまったく同じ argv を使って、インストール済みの evolveguard CLI をシェルから実行し、{returncode, stdout, stderr, json?} を返します（コマンドが失敗した場合、タイムアウトした場合、またはゼロ以外で終了した場合は {error: ...} を返します）。このため、サブコマンドごとに専用の MCP ツールを用意しなくても、1 つのツールで record、check、report を扱えます。エージェントからの呼び出し例：

{ "tool": "run", "arguments": { "args": ["check", "./SKILL.md", "--json"] } }

これにより、evolveguard check ./SKILL.md --json が出力するものと同じ構造化レポートに加えて、生の returncode／stdout／stderr が返されます。

ライブラリ API

evolveguard は、CLI をシェルから呼び出す代わりに独自のツールへ統合したいチーム向けに、同じパイプラインを利用できるプログラム API も公開しています。両方の配布版は、同じ関数と、JSON 互換の同じファイル形式を提供します。一方の CLI で記録したベースラインを、もう一方でチェックできます（docs/concepts.mdを参照）。

TypeScript：

import {
  recordBaseline,
  replaySkill,
  diffAll,
  writeBaseline,
  readBaseline,
} from 'evolveguard';

const baseline = recordBaseline('./SKILL.md', './fixtures.json');
writeBaseline('./.evolveguard-baseline.json', baseline);

// ... skill gets edited ...

const saved = readBaseline('./.evolveguard-baseline.json');
const replay = replaySkill('./SKILL.md', saved);
const report = diffAll(saved, replay);

エクスポートされる API の全体については、src/evolveguard/index.ts を参照してください。parseSkillFile、deriveCapabilitySurface、loadSkill、buildFixtureSnapshots、loadFixtures、recordBaseline、replaySkill、diffFixture、diffAll、diffSurface、writeBaseline、readBaseline、writeReport、readReport に加え、共有の types.ts インターフェースが含まれます。

Python（pip install evolveguard-cli）：

from evolveguard import record_baseline, replay_skill, diff_all, write_baseline, read_baseline

baseline = record_baseline("./SKILL.md", "./fixtures.json")
write_baseline("./.evolveguard-baseline.json", baseline)

# ... skill gets edited ...

saved = read_baseline("./.evolveguard-baseline.json")
replay = replay_skill("./SKILL.md", saved)
report = diff_all(saved, replay)

Python 固有の手順と、evolveguard/__init__.py からエクスポートされる同じ API については、python/README.md を参照してください。

比較

Braintrustは、汎用的なLLM評価・可観測性プラットフォームです。稼働中のエージェントのトレースをすでに記録していて、実行ごとの統計的な評価スコアを求める場合には有力な選択肢ですが、SDKの統合とアプリごとの評価定義が必要です。evolveguardにはどちらも必要ありません。1つのSKILL.mdファイルとフィクスチャJSONを指定するだけで動作します。

agent-eval（同じ作者による別のリポジトリ）は、別の問いに答えるツールです。エージェントやフレームワークを問わず、自分で定義した2つのバージョンを実行し、その差に対するp値を計算することで、エージェントの動作が変わったかどうかを判定します。evolveguardはSKILL.md／MEMORY.mdのファイル差分を直接トリガーとし、ベースラインに記録された機能範囲が_この特定の編集_によって変化したかどうかを判定します。スキルの成果物そのものを解析し、何かを実環境で定義したり実行したりする必要はありません。

evolveguardとは何か、なぜ存在するのか

evolveguardは、Claude Agent Skillファイル（SKILL.md）やClaude Codeの自動メモリファイル（MEMORY.md）が人間またはエージェントによって編集された後に、機能のドリフトを検出するコマンドラインツール兼TypeScriptライブラリです。スキルで宣言されたフロントマタースコープと、本文や同梱されたフックスクリプト内にあるネットワークまたはファイルシステムへの書き込み動作を示す静的な証拠を解析し、それをベースラインとしてスナップショットに記録します。編集後に同じスナップショットを再生成し、差分を比較します。Claude CodeのAgent Skillsエコシステムでは、人間がすべての編集について回帰を確認しなくても、スキルやメモリファイルによってエージェントの動作が変わる可能性があるため、evolveguardが存在します。また、SDKの統合やエージェントの実行を必要とせず、この特定の成果物の形式を検査する既存のツールがありません。

ステータス

これはv0.1リリースです。既存のClaude Agent Skillsエコシステムに加わる、小規模で目的を絞ったツールです。独自の有料プランがなく、完全なMITライセンスで、同等に独立した2つのパッケージとして提供されています。

• PyPI（evolveguard-cli、Python）。公開先はpypi.org/project/evolveguard-cliです。Nodeバイナリのラッパーではなく、独立した正式な移植版です（python/README.mdを参照）。pip install evolveguard-cliで直接インストールできます。このパッケージは当初evolveguardという名前で公開されていましたが、その旧PyPIプロジェクトは廃止され、更新されなくなっています。代わりにevolveguard-cliをインストールしてください。
• npm（evolveguard-cli、TypeScript）。公開先はnpmjs.com/package/evolveguard-cliです。npm install -g evolveguard-cliで直接インストールできます。PyPIパッケージの命名規則に合わせるため、2026-07-19に旧名称のevolveguardから変更されました。旧名称は現在非推奨です。

FAQ

evolveguard とは具体的に何ですか？ 編集後の Claude Agent Skill ファイル（SKILL.md）と Claude Code の自動メモリファイル（MEMORY.md）における機能のドリフトを検出するコマンドラインツール兼ライブラリです。自己進化型エージェントのフレームワークではなく、エージェント自体の構築、実行、ホスティングも行いません。すでに変更されたスキル成果物のファイル差分に、人間またはエージェントが変更した後で反応する、回帰テスト用の CI ゲートです。詳しい定義については、上記の「evolveguard とは何か、なぜ存在するのか」を参照してください。

evolveguard は LLM を呼び出しますか？ いいえ。record と check はどちらも完全に静的で決定論的です。各コマンドが解析・スキャンする内容の詳細については、上記の「機能」を参照してください。

一般的なテストツールや評価ツールとの、主な差別化要因は何ですか？ ホストされているものも、統合が必要なものもありません。1 つの SKILL.md ファイルと fixtures JSON を指定するだけで、SDK 統合もライブエージェントの実行もなしに、すぐに record／check を実行できます。上記の「比較方法」の表に記載しているのは、セットアップ不要と引き換えに、一般的な評価プラットフォームより対象範囲が狭くなるというトレードオフです。

evolveguard は Braintrust とどう違いますか？ Braintrust は、SDK 統合と評価定義の手順が必要な、一般的な LLM 評価・可観測性プラットフォームです。ライブエージェントの実行から得られた実際のトレースを評価します。evolveguard にはそのどちらも必要ありません。スキルファイル自体を解析し、LLM を呼び出すこともありません。すでにトレースを記録していて、実行をまたいだ統計的な評価スコアリングを行いたい場合は、Braintrust を使用してください。SKILL.md／MEMORY.md の編集によって、スキルが実行できることが気付かないうちに広がっていないかを確認する、コミット前または CI のチェックが必要な場合は、evolveguard を使用してください。この作者が同じく開発したagent-evalとの比較を含む詳しい内容については、上記の「比較方法」の表を参照してください。

フロントマターのない MEMORY.md ファイルでも動作しますか？ はい。フロントマターがないファイルは、宣言されたスコープが空の状態で解析されます。そのため、その機能範囲は本文から見つかった静的な証拠のみで決まります。

対応プラットフォームとインストール方法を教えてください。 npm パッケージには Node.js >=20.12 が必要です（Node.js がサポートするすべての OS に対応）。npm install -g evolveguard-cli でインストールできます。PyPI パッケージには Python >=3.9 が必要です。pip install evolveguard-cli でインストールできます。どちらの配布物も純粋なライブラリ／CLI パッケージでネイティブバインディングがないため、どちらも OS 固有のビルド手順は必要ありません。

利用する前に知っておくべき、実際の制限は何ですか？ 確認できるのは、_宣言された、または表示されている_機能のみであり、実行時の動作は対象外です。あるスキルが check に合格しても、機能範囲に影響しない形で、特定のプロンプトに対して異なる動作をする可能性があります。また、誤検知ベンチマーク（上記の「機能」を参照）は、現在、手作業でラベル付けした変更前後のペアが 5 組だけの小規模なコーパスであり、大規模なデータセットではありません。そのため、0% という数値は統計的な保証ではなく、初期計測値として扱ってください。Python 配布版には実際の MCP サーバーが含まれています（上記の「MCP サーバー」を参照）。npm／TypeScript の mcp サブコマンドはまだ「近日公開」のスタブであり、npm ビルドの evolveguard --version の出力は、現在、実際に公開されているパッケージのバージョンより遅れています（上記の「CLI コマンドリファレンス」を参照）。

これは汎用的なエージェント進化フレームワークですか？ いいえ。上記の「比較方法」を参照してください。evolveguard は、自己進化型エージェントのフレームワークを構築またはホスティングするのではなく、すでに行われたスキル／メモリの編集のみをテストするよう意図的に設計されています。

evolveguard は商用利用を含め、無料で使えますか？ はい。MIT ライセンスで提供されており、プロプライエタリな有料プランや有料版はありません。LICENSEを参照してください。標準的な MIT の条件に従って、商用プロジェクトを含め、使用、変更、再配布できます。

貢献

CONTRIBUTING.mdを参照してください。変更にはすべて、両方の配布版でテストを追加します。フロントマターのスキーマ、機能範囲の導出、または差分の判定ロジックを変更する場合は、src/evolveguard/（TypeScript）とpython/src/evolveguard/（Python）の両方に変更を加え、両方のテストスイートに同等のテストを追加する必要があります。

セキュリティ

SECURITY.mdをご覧ください。evolveguard は、指定されたローカルファイルを読み取りますが、そのファイルを実行することはありません。ネットワークへの接続や、稼働中のエージェントの実行も行いません。

ライセンス

MIT。詳細はLICENSEをご覧ください。