meticulous-use-session-data

Meticulous の構造化されたセッションデータ（記録されたユーザーフローと、コードの変更箇所をカバーするネットワークモック）を取得するには、このワークフローを使用します。

開始する前に、meticulous-cli-update スキルを実行して、Meticulous CLI とスキルが最新であることを確認してください。ただし、この会話の前のほうですでに実行している場合は、スキップしてください。

ステップ 1 — 関連するセッションを見つけてデータをダウンロードする

git リポジトリのルートから、次のコマンドを実行します。

meticulous local relevant-sessions --format=multi-file --minimum-times-to-cover-each-line=1

このコマンドは次の処理を行います。

1. 現在のブランチで変更されたコードパスを実行する、記録済みセッションを特定します。
2. 各セッションのデータを、構造化されたディレクトリツリーとして .meticulous/sessions/ にダウンロードします。

オプション：

オプション	型	デフォルト	説明
--format	multi-file	—	multi-file に設定すると、関連する各セッションのデータを構造化されたディレクトリツリーとしてダウンロードします
--minimum-times-to-cover-each-line	number	—	編集した各行をカバーするセッションを少なくともこの数だけ選択します。候補が他にもある場合は、最も多様な組み合わせを選択します
--include-superfluous-sessions	boolean	false	--minimum-times-to-cover-each-line を指定した場合に不要となる、変更の一部をテストするセッションも含めます
--outputDir	string	.meticulous/sessions	マルチファイル形式の出力ディレクトリ
--showMaybeRelevant	boolean	false	影響を受ける可能性のあるセッションも表示します
--startingPointSha	string	—	このコミット SHA 以降の変更のみを対象にします

ステップ 2 — 出力構造を理解する

ダウンロードしたデータは、次のように整理されています。

.meticulous/sessions/
  manifest.json                       # List of all sessions with summary metadata
  sessions/
    <sanitized-session-id>/           # Special characters in session IDs are replaced for filesystem safety
      summary.json                    # Session overview: URL, viewport, duration, event count
      user-events.json                # Sequence of user interactions (clicks, typing, navigation)
      network-requests/
        summary.json                  # All network requests: method, URL, status (no bodies)
        <order>.json                  # Individual request/response pairs (with bodies)
      storage/
        cookies.json                  # Initial cookie state
        local-storage.json            # Initial localStorage state
        session-storage.json          # Initial sessionStorage (if present)
        indexed-db.json               # Initial IndexedDB (if present)
      url-history.json                # Page navigation history with timestamps
      context.json                    # Feature flags, user ID, custom context (if present)
      websockets/                     # WebSocket data (if present)
        summary.json                  # WebSocket connections overview
        <connection-id>.json          # Events for each connection

ステップ 3 — データを確認する

1. まず manifest.json を確認します。 利用可能なすべてのセッションが表示されます。各エントリーには、セッション ID、開始 URL、イベント数、所要時間、ネットワークリクエスト数が含まれます。タスクに関連するセッションを選択します。

2. セッションディレクトリ内の summary.json を読み取ります。 開始 URL、ビューポートサイズ、合計所要時間、イベント数など、そのセッションの概要をすばやく確認できます。

3. ユーザーフローを理解するために、user-events.json を読み取ります。 各イベントには次の情報があります。

   • type：操作の種類（例：click、input、scroll）
   • selector：対象要素の CSS セレクター
   • timestampMs：イベントが発生した時刻
   • coordinates：クリック位置（該当する場合）

4. セッション中に実行されたすべての API 呼び出しを確認するには、network-requests/summary.json を参照します。 各エントリーには、HTTP メソッド、URL、ステータスコード、コンテンツタイプ、応答時間が表示されます。レスポンス本文は含まれないため、すばやく確認できます。

5. 特定の API 呼び出しの完全なリクエスト／レスポンスデータを確認するには、個々の network-requests/<order>.json ファイルを読み取ります。 テストを作成する際は、これらをモックデータとして使用します。サマリーの order フィールドはファイル名に対応しています。

6. アプリケーションの初期状態（Cookie、localStorage など）を把握する必要がある場合は、storage/ 内のファイルを確認します。

ステップ 4 — テストにデータを使用する

一般的な用途：

ユーザーフローを把握する

user-events.json を読んで、ユーザー操作の正確な順序を確認します。これにより、ユーザーが何をクリックし、入力し、どこへ移動したかがわかり、コード変更でサポートすべき内容を把握できます。

ネットワークモックを作成する

ネットワークリクエストのファイルを使って、テスト用のモックレスポンスを作成します。

1. network-requests/summary.json を読んで、関連する API エンドポイントを確認します。
2. 個々の network-requests/<order>.json ファイルを読んで、完全なリクエスト／レスポンスのペアを確認します。
3. テストでは、response.content.text フィールドをモックレスポンスデータとして使用します。

カバレッジを検証する

ユーザーイベントとネットワークリクエストをコード変更と照合し、セッションで変更したコードパスがカバーされていることを確認します。

別の方法：特定のセッションをダウンロードする

必要なセッション ID がすでにわかっている場合は、直接ダウンロードできます。

# CLI
meticulous download session --sessionId=<id> --format=multi-file

# MCP (returns the same structured data inline instead of writing it to disk)
get_session_data(sessionId="<id>")

CLI はデフォルトで .meticulous/sessions/ に書き込みます。出力先を変更するには --outputDir を使用します。

最後の手順 — Meticulous にフィードバックを送信する

セッションデータの利用が終わったら、Meticulous チームに簡潔なフィードバックを 1 件送信してください。セッションデータで必要なフローがカバーされていたか、また、どの情報が不足していたか、あるいはどのような情報があれば作業が容易になったかを伝えます。

# CLI
meticulous agent submit-feedback --message="<one or two sentences>" --outcome=<helped|neutral|hindered> --skill=meticulous-use-session-data

# MCP
submit_feedback(message="<one or two sentences>", outcome="<helped|neutral|hindered>", skill="meticulous-use-session-data")