friction-detector

Friction-to-Learning パイプライン

概要

エージェントの実行中に摩擦の兆候を検出し、セッションをまたいで追跡して、繰り返し発生するパターンを恒久的なガイダンスに昇格させます。一時的なセッション中の摩擦と、持続的な CLAUDE.md のルールとの隔たりを埋めます。

研究の裏付け：Claude Coach（SQLite ストレージを使用したフックベースの摩擦検出）、alirezarezvani の self-improving-agent（3 層の MEMORY から CLAUDE.md への昇格）、および ACE フレームワーク（arXiv：実行時のフィードバックからプレイブックを進化させ、エージェントタスクで +10.6%）。

現状の課題：LEARNINGS.md は存在しますが、/abstract:aggregate-logs による手動の集約が必要です。このスキルは、自動的な摩擦検出と構造化された昇格経路を追加します。

摩擦のシグナルの種類

シグナル	検出方法	重み
繰り返される修正	セッション中にユーザーが同じツール呼び出しを 2 回以上上書きする	高
コマンドの失敗	終了コード != 0 のパターン（同じ種類のコマンドが繰り返し失敗する）	中
権限の拒否	予期しない動作を示す、ユーザーによるツール呼び出しの拒否	高
再読み込み	セッション中に同じファイルを 3 回以上読み込む（コンテキストの喪失）	低
再試行ループ	バリエーションを加えながら同じ操作を 3 回以上試みる	中
ユーザーの不満	明示的な否定的フィードバック、または修正を示す言葉遣い	高

重みスコア：発生ごとに高 = 3、中 = 2、低 = 1 ポイント
重み付きスコアによって昇格の速度が決まります。

3 層のストレージ昇格

Tier 1: Friction Log (ephemeral, per-session)
  Location: ~/.claude/friction/sessions/{date}-{id}.json
  Retention: 30 days, then pruned
  Threshold: 1 occurrence, logged, no action

Tier 2: Pattern Candidate (persistent, LEARNINGS.md)
  Location: ~/.claude/skills/LEARNINGS.md (friction section)
  Threshold: 3+ occurrences across 2+ sessions
  Action: flagged for review in next friction report

Tier 3: Graduated Rule (CLAUDE.md or skill update)
  Threshold: reviewed + user-approved
  Action: permanent guidance added to project/user config
  Constraint: NEVER auto-modify CLAUDE.md

昇格の計算式

graduation_score = (weighted_count * recency_factor) / sessions_seen

recency_factor:
  last 7 days  = 1.0
  8-14 days    = 0.7
  15-30 days   = 0.4
  31+ days     = 0.1

Tier 2 threshold: graduation_score >= 6.0
Tier 3 proposal:  graduation_score >= 12.0

検出ワークフロー

セッション終了時、コンテキスト使用量が 80% に達したとき（conserve:clear-context 経由）、または改善サイクルが失敗した後（abstract:metacognitive-self-mod が後退を検出したとき）に実行します。

ステップ 1：セッションのシグナルをスキャンする

検出した摩擦の兆候ごとに、共有のセッションキャプチャエンベロープ（ADR-0011）でラップします。これにより、後続の読み取り側は 1 つのパーサーで摩擦のシグナルと trace-capture エントリを取り込めます。

{
  "schema_version": "session-capture/1",
  "session_id": "2026-04-14-abc12345",
  "timestamp": "2026-04-14T10:23:00Z",
  "source": "friction-detector",
  "payload": {
    "signal_type": "retry_loop",
    "description": "rg command failed 3x, fell back to grep",
    "context": "searching for pattern in node_modules",
    "weight": "medium"
  }
}

エンベロープの採用前に書き込まれたレガシーファイルは、session-capture/0（ファイル全体をペイロードとして扱う）として読み取られます。契約と移行経路については、docs/adr/0011-session-capture-envelope.md を参照してください。

ステップ 2：既存のログと比較する

FRICTION_DIR=~/.claude/friction/sessions
mkdir -p "$FRICTION_DIR"

# Count prior occurrences of similar signals
if command -v rg &>/dev/null; then
  rg -c "$SIGNAL_TYPE" "$FRICTION_DIR"/*.json 2>/dev/null || echo "0"
else
  grep -rc "$SIGNAL_TYPE" "$FRICTION_DIR"/*.json 2>/dev/null || echo "0"
fi

ステップ 3：昇格スコアを計算する

セッションログ全体を集計します。重み付き発生数を合計し、鮮度による減衰を適用して、セッション数で割り、層のしきい値と比較します。

ステップ 4：昇格を提案する

Tier 2 のしきい値を超えた場合：摩擦セクションに LEARNINGS.md への追記を提案します。
Tier 3 のしきい値を超えた場合：根拠とともにユーザーに提案を提示し、明示的な承認を待ってから変更します。

ステップ 5：結果を保存する

セッションログを
~/.claude/friction/sessions/{date}-{session_id}.json
に書き込み、~/.claude/friction/index.json を更新します。

ノイズ対策ルール

次のシグナルは無視します。

1. 一度きりの失敗：一時的なネットワーク／CI エラー
   （3 回以上繰り返される場合を除く）
2. ユーザー主導の探索：意図的な実験はエージェントのエラーではありません
3. すでに昇格済みのパターン：既存の CLAUDE.md ルールまたはスキルの指示でカバーされているもの
4. 外部ツールの失敗：MCP サーバーのクラッシュなど、エージェントの動作とは無関係なツールのバグ

減衰係数：30 日を超えたシグナルは、元の重みの 10% のみ加算されます（昇格の計算式の recency_factor を参照）。

摩擦レポートの形式

## Friction Report: Session {date}

### New Signals (Tier 1)
- [RETRY] `rg` command failed 3x, fell back to `grep`
- [RE-READ] Read SKILL.md 4 times (lost file structure context)

### Recurring Patterns (Tier 2 candidates)
- [CORRECTION] User corrected file path format 4x across 3 sessions
  Score: 8.4 (threshold: 6.0)
  Candidate: Add path format guidance to CLAUDE.md

### Graduation Proposals (Tier 3)
- [RULE] "Always use absolute paths in Read tool"
  Evidence: 7 corrections across 5 sessions
  Score: 14.2 (threshold: 12.0)
  Action: Approve / Reject / Defer

### Noise Filtered
- 2 transient network timeouts (ignored)
- 1 user-initiated deep exploration (ignored)

統合

連携先：LEARNINGS.md（Tier 2 のパターン。/abstract:aggregate-logs と同じ形式）、
abstract:skill-improver（優先度スコアリング）、および
abstract:metacognitive-self-mod（パイプラインの有効性）。

取り込み元：セッションのトランスクリプト、
aggregate_learnings_daily フックのデータ、および
傾向の相関分析に使用するパフォーマンストラッカー。

使用しない場合

• 単発の孤立した失敗（再発するまで待ってください）
• スキルの作成（abstract:skill-authoring を使用してください）
• 通常のログ集約（/abstract:aggregate-logs を使用してください）

関連項目

• abstract:metacognitive-self-mod: 改善分析
• abstract:skills-eval: 評価基準
• /abstract:aggregate-logs: LEARNINGS.md の手動生成
• conserve:clear-context: 80% で摩擦スキャンを開始します

終了条件

• 「摩擦レポート形式」でセッション摩擦レポートを作成し、少なくとも 1 つのセクション（新しいシグナル、繰り返し発生するパターン、または昇格の提案）に内容を記載する
• 各シグナルを session-capture/1 スキーマに従い、JSON として ~/.claude/friction/sessions/{date}-{session_id}.json に書き込む
• graduation_score が 12.0 以上のパターンについて、Tier 3 の提案を生成する。スキルは CLAUDE.md を自動変更しない
• ノイズシグナル（ネットワーク障害、ユーザーによる探索）は「除外したノイズ」に記載し、昇格スコアリングの対象から除外する