Skar – キャプチャしたAIエージェントのトレースをpytest回帰テストに変換

Skarは、キャプチャしたAIエージェントのトレースをpytest回帰テストに変換するオープンソースツールです。カスタムエージェントの特定の動作を固定し、コード変更による回帰を防ぎます。2つの補完的なパッケージで構成されています：npmパッケージ（@kalisky/skar）はCLIとMCPサーバーを提供し、トレースの検証、テスト生成、HTMLレポートの作成を行います。Pythonパッケージ（skar）はRecorderクラスを提供し、エージェントコードに組み込んで実行トレースをキャプチャし、JSON形式のトレースファイルを出力します。

Skarは主に、LangChain、LlamaIndex、Anthropic SDK、AutoGenなどのフレームワークを使用してツール呼び出しループを構築するカスタムエージェントを作成するチームを対象としています。あなたがコードを制御できるエージェントにのみ適用でき、Claude CodeやCursorのような外部エージェントの内部は対象外です。ただし、Skarはこれらのセッションをキャプチャして可視化することは可能で（HTMLレポートは任意のトレースで機能します）、「テストが動作のドリフトをキャッチする」という価値はエージェントのコードを制御している場合にのみ発揮されます。

典型的なワークフロー：skar.Recorderでエージェントを計装し、実行してトレースをキャプチャし、CLIまたはMCPサーバーのgenerateコマンドでトレースファイルをpytestテストケースに変換します。生成されたテストはアダプタモジュール（skar_adapter.py）に依存し、実際のエージェントコードをインポートして、モックされたLLMとツール実行でテストを実行します。アダプタは単なるトレースのリプレイではなく、実際のエージェントロジックを呼び出す必要があります。

SkarのMCPサーバーは4つのツールを提供：capture_claude_code_session（Claude Codeセッションログからトレースを生成）、generate_pytest_regression（トレースをpytestファイルに変換）、validate_trace（トレース形式の検証）、inspect_trace（エージェント動作の要約）。AIエージェントユーザーは、まずcapture_claude_code_sessionで最新セッションのトレースを取得し、続いてgenerate_pytest_regressionでテストを生成するのが一般的な流れです。既に他の形式のトレースがある場合は、ステップ1をスキップして直接generate_pytest_regressionにトレースファイルを渡せます。

インストール方法：推奨はグローバルインストールしてMCPを登録する方法（npm install -g @kalisky/skar；claude mcp add skar -- skar-mcp）。MCPホストを再起動すると4つのツールが利用可能になります。設定ファイルを使用する方法や、ゼロインストールでnpxを使う方法もあります。CLIではより細かい制御が可能で、--from-indexと--to-indexによるスライス、--redact-patternによるマスキング、--match-mode multisetによる順序を考慮しないテスト、--ignore-fieldによる特定フィールドの無視などがサポートされています。生成されるHTMLレポートはセルフコンテナで、コミット前に確認したりPRに添付したりできます。

生成されたテストは、アダプタモジュールを必要とします。このアダプタは実際のエージェントコードをインポートし、スクリプト化されたClaudeとツール実行を使ってエージェントを実行します。アダプタはトレースをそのまま再生するのではなく、実際のエージェントの解析、ループ制御、メッセージ構築のロジックを実行する必要があります。これにより、コードの回帰がテスト失敗として表面化します。

生成テストがキャッチするもの：ループ制御バグ、メッセージ構築の回帰、ツール配送のエラー、最終テキスト抽出のバグ、および揮発性パターンでカバーされない静かな引数ドリフト。キャッチしないもの（意図的）：LLMの動作変更（テストではClaudeをスクリプト化しており、実際のAPIは呼ばない）、ツール実装の回帰（ツール結果はトレースから再生され、実際のツールが誤った結果を返しても検知できない）、システムプロンプトの回帰（スクリプト化されたClaudeはプロダクションのプロンプト変更を反映しない）。これらをカバーするには、実際のLLMを使った別のテストを実行する必要があります。両者は補完的であり、代替ではありません。

トレーススキーマ（v0.1）は、schema_version、input、events、finalフィールドで構成されます。eventsにはtool_callタイプのイベントが含まれ、ツール名、引数、結果が保存され、順序は保持されます。

セキュリティ：Skarはネットワークコールを行わず、シェルを実行せず、evalやexecを使用しないプレーンなPythonを出力します。ただし、次の点に注意が必要です：(1) 生成されたテストにはトレースの生データが含まれ、APIキーや内部URLなどの機密情報がコミットされる可能性があるため、毎回レビューすること。(2) トレースファイルはインジェクションベクターとなり得るため、信頼できないソースからのトレースを処理しないこと。(3) アダプタはモックを使用すべきで、実際のデータベースやAPIを呼び出してはならない。(4) MCPのパス入力はユーザーの権限で実行されるため、ファイル操作には注意が必要。

Skarが存在する理由：「検査できる」と「この特定の失敗を二度と起こさせない」というギャップを埋め、カスタムエージェントのコード変更に対する回帰テストを提供するためです。