session-archaeology

セッション考古学

Agent Skills™ の一部です。googleadsagent.ai™ 提供

説明

セッション考古学とは、過去のエージェントセッションを体系的に掘り下げて分析し、再利用可能なパターンを抽出し、繰り返し発生する失敗モードを特定し、運用履歴から新たなスキルを導き出す手法です。エージェントの各セッションでは、推論、ツールの使用、エラー、修正、最終結果をすべて含む、豊富な成果物である完全なトランスクリプトが生成されます。ほとんどのチームはこのデータを破棄します。セッション考古学では、このデータを利用可能な最も価値の高いトレーニングシグナルとして扱います。つまり、特定のドメイン、特定のコードベース、特定のワークフローにおける、実環境での実行トレースです。

このスキルは、数千件におよぶ過去の Google Ads 分析セッションを掘り下げ、Buddy™ を継続的に改善するために googleadsagent.ai™ で用いられている方法論を形式化したものです。考古学のプロセスでは、正確な推奨につながったプロンプトパターン、確実に完了したツール呼び出しの順序、成功したエラー回復戦略を特定します。得られた知見は新しい Agent Skills™ や既存スキルの改善として体系化され、継続的改善の好循環を生み出します。

このプロセスは、個別セッションのレビュー（今回の実行で何がうまくいかなかったか）、セッション横断のパターン分析（多くの実行でどのようなパターンが繰り返されるか）、傾向の特定（エージェントの振る舞いが時間とともにどう変化しているか）の3つのレベルで行われます。各レベルでは、異なる知見と異なる種類の改善が得られます。

使用する場面

• エージェントの品質が頭打ちになり、新たな最適化シグナルが必要な場合
• 実際の実行データから新たなスキルやルールを導き出したい場合
• 繰り返し発生する失敗から、ランダムなエラーではなく体系的な問題が示唆される場合
• エージェントの振る舞いのパターンを理解する必要がある新しいチームメンバーをオンボーディングする場合
• 実際のセッショントランスクリプトから回帰テストスイートを構築する場合
• モデルのバージョン移行に備える場合（モデルバージョン間の振る舞いを比較する）

仕組み

graph TD
    A[Session Transcripts] --> B[Session Parser]
    B --> C[Event Extraction]
    C --> D[Pattern Classifier]
    D --> E{Pattern Type}
    E -->|Success Pattern| F[Skill Candidate]
    E -->|Failure Pattern| G[Mistake Taxonomy Entry]
    E -->|Neutral| H[Archive]
    F --> I[Pattern Validation]
    G --> I
    I --> J[Cross-Session Correlation]
    J --> K{Frequency > Threshold?}
    K -->|Yes| L[Skill Codification]
    K -->|No| M[Watch List]
    L --> N[Agent Skills™ Repository]
    M --> J

考古学のワークフローは、生のセッショントランスクリプトを構造化されたイベントストリームに解析するところから始まります。各ツール呼び出し、各モデル応答、各エラー、各人間による介入が個別のイベントになります。パターン分類器は各イベントシーケンスにタイプを割り当てます。成功パターン（タスクを確実に達成するツールチェーン）、失敗パターン（根本原因を特定できる繰り返し発生するエラー）、中立パターン（明確に良くも悪くもないもの）です。成功パターンと失敗パターンは検証に進み、そこでセッション間の相関を分析します。頻度のしきい値を超えたパターンは、正式なスキルまたはルールとして体系化されます。

実装

セッショントランスクリプトパーサー：

from dataclasses import dataclass, field
from typing import Literal

@dataclass
class SessionEvent:
    timestamp: str
    event_type: Literal["tool_call", "model_response", "error", "human_input", "correction"]
    content: dict
    duration_ms: int = 0
    token_count: int = 0
    success: bool = True

@dataclass
class ParsedSession:
    session_id: str
    events: list[SessionEvent] = field(default_factory=list)
    total_tokens: int = 0
    total_duration_ms: int = 0
    outcome: Literal["success", "partial", "failure"] = "success"

def parse_session_transcript(transcript_path: str) -> ParsedSession:
    with open(transcript_path) as f:
        lines = [json.loads(line) for line in f if line.strip()]

    session = ParsedSession(session_id=transcript_path)
    for entry in lines:
        event = SessionEvent(
            timestamp=entry.get("timestamp", ""),
            event_type=classify_event_type(entry),
            content=entry,
            duration_ms=entry.get("duration_ms", 0),
            token_count=entry.get("usage", {}).get("total_tokens", 0),
            success=not entry.get("error"),
        )
        session.events.append(event)
        session.total_tokens += event.token_count
        session.total_duration_ms += event.duration_ms

    session.outcome = determine_outcome(session.events)
    return session

パターン抽出エンジン：

class PatternExtractor:
    def __init__(self, min_frequency=3, min_confidence=0.7):
        self.min_frequency = min_frequency
        self.min_confidence = min_confidence
        self.pattern_store = {}

    def extract_tool_sequences(self, sessions: list[ParsedSession]) -> list[dict]:
        sequences = []
        for session in sessions:
            tool_events = [e for e in session.events if e.event_type == "tool_call"]
            for window_size in range(2, min(6, len(tool_events) + 1)):
                for i in range(len(tool_events) - window_size + 1):
                    seq = tuple(e.content.get("tool_name") for e in tool_events[i:i + window_size])
                    success = all(e.success for e in tool_events[i:i + window_size])
                    sequences.append({"sequence": seq, "success": success, "session": session.session_id})
        return self.aggregate_sequences(sequences)

    def aggregate_sequences(self, sequences):
        counts = {}
        for seq in sequences:
            key = seq["sequence"]
            if key not in counts:
                counts[key] = {"total": 0, "success": 0, "sessions": set()}
            counts[key]["total"] += 1
            counts[key]["success"] += int(seq["success"])
            counts[key]["sessions"].add(seq["session"])

        patterns = []
        for seq, stats in counts.items():
            if stats["total"] >= self.min_frequency:
                confidence = stats["success"] / stats["total"]
                if confidence >= self.min_confidence:
                    patterns.append({
                        "sequence": seq,
                        "frequency": stats["total"],
                        "confidence": confidence,
                        "sessions": len(stats["sessions"]),
                    })
        return sorted(patterns, key=lambda p: p["confidence"] * p["frequency"], reverse=True)

ミス分類体系ビルダー：

class MistakeTaxonomy:
    CATEGORIES = {
        "hallucination": {"description": "Model generated factually incorrect content"},
        "tool_misuse": {"description": "Wrong tool selected or incorrect parameters"},
        "context_loss": {"description": "Agent lost track of prior context or instructions"},
        "scope_creep": {"description": "Agent exceeded the boundaries of the task"},
        "format_violation": {"description": "Output did not match required format"},
    }

    def __init__(self):
        self.entries = []

    def classify_mistake(self, event: SessionEvent, context: list[SessionEvent]) -> dict:
        error_text = str(event.content.get("error", ""))
        prev_events = context[-5:]
        category = self.match_category(error_text, prev_events)
        return {
            "category": category,
            "event": event,
            "context_window": prev_events,
            "suggested_fix": self.suggest_fix(category, error_text),
        }

    def suggest_fix(self, category: str, error_text: str) -> str:
        fixes = {
            "hallucination": "Add verification loop with ground-truth checking",
            "tool_misuse": "Add pre-flight tool parameter validation",
            "context_loss": "Implement context checkpointing between stages",
            "scope_creep": "Add task boundary assertions in system prompt",
            "format_violation": "Add schema grader to verification pipeline",
        }
        return fixes.get(category, "Review and add specific guard for this error type")

ベストプラクティス

1. セッションを自動で解析する — セッションの完了直後にすべてのセッショントランスクリプトを解析してインデックス化するフックを設定します。古いデータは価値が下がります。
2. まず失敗モードに注目する — 成功パターンも有用ですが、失敗パターンはエンジニアリング時間あたりで最も大きな効果をもたらします。
3. 継続的に更新するミス分類体系を構築する — 推奨される修正方法と発生回数を含む、あらゆる失敗タイプの分類済みで検索可能なデータベースを維持します。
4. 最低発生頻度を設ける — 1回だけ観測されたパターンはノイズの可能性があります。スキルとして体系化する前に、異なるセッションで少なくとも3回発生していることを条件にします。
5. 時間の経過に伴うパターンの変化を追跡する — 発生頻度が増えている失敗パターンは、リグレッションを示します。減少している場合は、最近の修正が有効であることを示します。
6. 成功したツールの順序からスキルを導き出す — 同じ3つのツールの順序が成功したセッションの80％に見られる場合は、推奨ワークフローとして体系化します。
7. 共有前に匿名化する — セッショントランスクリプトにはユーザーデータ、API キー、ビジネスロジックが含まれます。チーム横断の分析を行う前に機密情報を削除します。

プラットフォームの互換性

機能	Claude Code	Cursor	Codex	Gemini CLI
セッションのトランスクリプトへのアクセス	✅ JSONL ログ	✅ エージェントのトランスクリプト	✅ 実行ログ	✅ セッションログ
自動解析	✅ フック	✅ 拡張機能	✅ スクリプト	✅ スクリプト
複数セッションにまたがる分析	✅ 完全対応	✅ 完全対応	✅ 完全対応	✅ 完全対応
パターンの抽出	✅ 完全対応	✅ 完全対応	✅ 完全対応	✅ 完全対応
スキルの導出	✅ SKILL.md	✅ SKILL.md	✅ 指示	✅ システムプロンプト

関連スキル

• 検証ループ - グレーダーの出力を、パターンマイニング用の構造化された評価データとしてセッション考古学に取り込みます
• 認知の足場 - どの足場ゾーンが最良の結果をもたらすかを考古学的分析で検証し、注意のパターンを明らかにします
• コンテキストエンジニアリング - セッショントランスクリプトからトークン使用パターンを抽出し、コンテキスト予算の割り当てを最適化します

キーワード

session-archaeology, pattern-mining, mistake-taxonomy, session-analysis, skill-derivation, cross-session-analysis, agent-improvement, transcript-parsing, failure-analysis, agent-skills

---

© 2026 googleadsagent.ai™ | Agent Skills™ | MIT License