meticulous-simulate-and-diff

セッションをシミュレーションして差分を分析する

このスキルでは、単一のシミュレーションを実行し、結果を解釈する方法について説明します。simulate コマンドのオプションをすべて確認するには、meticulous-cli スキルの simulate リファレンスを参照してください。

開始する前に、meticulous-cli-update スキルを実行して Meticulous CLI とスキルを最新の状態にしてください。ただし、この会話中にすでに実行済みの場合は、スキップしてください。

前提条件

• 再生する sessionId
• appUrl（ローカルの開発サーバー。元の記録時の URL を使用する場合は空欄のままにします）
• 任意：baseReplayId — スクリーンショットの差分比較に使う、以前のリプレイの ID。これがない場合、スクリーンショットは保存されますが、比較は行われません。

baseReplayId がない場合は、ダウンロード済みのテスト実行から確認できます。

meticulous download test-run --testRunId=latest
# Then inspect ~/.meticulous/test-runs/<testRunId>/coverage.json
# or check the testCases[].replayId fields

ステップ 1 — シミュレーションを実行する

ベースリプレイあり（差分モード）

meticulous simulate \
  --sessionId=<sessionId> \
  --appUrl=<url> \
  --baseReplayId=<baseReplayId> \
  --headless

標準出力全体を取得します。確認するポイントは次のとおりです。

# Per-screenshot diff outcomes (one line each):
0.412% pixel mismatch for screenshot screenshot-1234.png (threshold is 0.100%) => FAIL!
0.000% pixel mismatch for screenshot screenshot-5678.png (threshold is 0.100%) => PASS

# Final summary block:
=======
View simulation at: https://app.meticulous.ai/projects/<org>/<project>/simulations/<headReplayId>
View comparison with base: https://app.meticulous.ai/projects/<org>/<project>/simulations/<baseReplayId>/compare-to/<headReplayId>
=======

FAIL! の行がない場合： セッションはベースと視覚的に同一です。リグレッションがないことを報告し、ステップ 6 に進んでください。

差分の場所を特定して分析するには、ステップ 2～6 に進み、その後フィードバックを送信してください。

ベースリプレイなし（クイックチェックモード）

baseReplayId がない場合は、省略してください。スクリーンショットは引き続きローカルに保存されるため、直接目視で確認できます。

meticulous simulate \
  --sessionId=<sessionId> \
  --appUrl=<url> \
  --headless

次に、リプレイディレクトリ（ステップ 2）を特定し、<replayDir>/screenshots/ 内のスクリーンショットを開いて、UI が正しく表示されることを確認してください。このモードでは差分画像は作成されず、目視のみで確認します。ステップ 3～5 は該当しませんが、確認後にステップ 6 は必ず完了してください。

ステップ 2 — head replay ID を抽出し、リプレイディレクトリを特定する

View simulation at: の URL から、<headReplayId>（最後のパス要素）を抽出します。

この実行で作成されたローカルのリプレイディレクトリを見つけるには、次のコマンドを実行します。

ls -lt ~/.meticulous/replays/ | head -5

最も新しく作成された項目が head replay のディレクトリです（タイムスタンプを含む名前です。例：2024-01-15T12-30-45.123Z-abc123/）。このパスを控えてください。以下では、このパスを <replayDir> と呼びます。

ステップ 3 — 差分があったスクリーンショットを特定する

ls ~/.meticulous/replays/<replayDir>/diffs/<baseReplayId>/

ここにある各 .png ファイルは、視覚的な差分が検出されたスクリーンショットに対応しています。ピクセル差分画像では、変更されたピクセルが色付きで強調表示されます。thumb_ が付いたサムネイル版もあります。

ファイル名を控えてください。スクリーンショット識別子（例：screenshot-after-event-42.png）と一致します。

ステップ 4 — 差分があった各スクリーンショットの HTML 差分を分析する

各スクリーンショットには、撮影直前に取得されたページの完全な HTML スナップショットを含む、対応するメタデータファイルがあります。これらのファイルはすでにディスク上にあります。

• head メタデータ： ~/.meticulous/replays/<replayDir>/screenshots/<screenshotFilename>.metadata.json
• base メタデータ： ~/.meticulous/replays/<baseReplayId>/screenshots/<screenshotFilename>.metadata.json

シミュレーションでベースリプレイをダウンロードする際に、ベースメタデータは永続的にキャッシュされるため、追加のダウンロードは不要です。

両方の .metadata.json ファイルを読み取ります。関連するフィールドは次のとおりです。

• before.dom — スクリーンショット撮影時のページの完全な HTML。変更内容を把握するため、この 2 つの文字列を比較します
• before.routeData.url — スクリーンショットが撮影されたページ／ルート

HTML を比較する際は、タグの追加や削除、class 属性の変更、テキストコンテンツの変更に注目してください。

スクリーンショットごとの標準出力行には、mismatchFraction（変更されたピクセルの割合）も出力されます。ピクセル差分がある一方で before.dom の文字列が同一の場合、構造上の変更ではなく、色の変化などの視覚的な変化です。

ステップ 5 — 調査結果を要約する

このスキルの主な成果物は、視覚的に何が変わり、その理由は何かを人が読みやすい形で説明したものです。上記で収集したピクセル差分の数、ルート URL、変更されたクラス名、HTML 差分を使って、_ユーザーの体験はどのように変わり、UI のどの部分がその変化を引き起こしたのか_を説明してください。

現在の状況に合った形式（会話形式の回答、構造化されたレポート、呼び出し元のワークフローへの入力など）で提示してください。参考になるシグナルは次のとおりです。

• 影響を受けたルート
• 変更された DOM 領域に現れた CSS クラス（通常、これらはコンポーネントに直接対応します）
• 変更が構造的なもの（DOM の追加・削除）か、純粋に視覚的なもの（HTML 差分を伴わないピクセルの変化）か
• 同じ変更が複数のスクリーンショットに現れているか（共有コンポーネントの変更が示唆されます）、それとも 1 枚のスクリーンショットだけに限られているか

標準出力に記録される比較 URL は、必ず提示してください。人が差分をすばやく視覚的に確認できます。 https://app.meticulous.ai/.../simulations/<baseReplayId>/compare-to/<headReplayId>

メモ

• ~/.meticulous/replays/<replayDir>/diffs/<baseReplayId>/ にあるピクセル差分画像は、直接開いて視覚的に確認できます。
• --baseReplayId を省略すると、差分を分析できません。スクリーンショットは引き続きローカルに保存されるため、最初の実行で取得したヘッドリプレイ ID を --baseReplayId に指定して再実行すれば、後から比較できます。
• 反復的な開発ワークフロー全体（セッションの検出、ステップごとのコミット、最後のクラウド実行）については、meticulous-iterative-dev スキルを参照してください。

ステップ 6 — Meticulous にフィードバックを送る

最後のステップとして、調査結果を要約した後、Meticulous チームに短いフィードバックを 1 件送信してください。シミュレーションと差分は変更の検証に役立ったか、分かりにくい点はあったか、タスクをより簡単に進めるためにどのような情報があればよかったかを伝えてください。

# CLI
meticulous agent submit-feedback --message="<one or two sentences>" --outcome=<helped|neutral|hindered> --skill=meticulous-simulate-and-diff

# MCP
submit_feedback(message="<one or two sentences>", outcome="<helped|neutral|hindered>", skill="meticulous-simulate-and-diff")