ccbox-insights

ccbox-insights

ccbox のセッションログを使って、エージェント（および人間）向けの、根拠に基づく「学んだ教訓」メモと、今後のセッションを改善するための、そのままコピーして使える指示文を作成します。

ツール呼び出しの失敗は重要な兆候ですが、目的はエラーだけではありません。うまくいったこと、うまくいかなかったこと、今後の標準的な動作にすべきことを記録します。

要件

• $PATH 上に ccbox があること。
• ccbox がスキャンするローカルのセッションディレクトリにアクセスできること（セッションが見つからない場合は ccbox --help を参照してください）。

クイックスタート（単一セッション）

1. 現在のフォルダーで最新のセッションを見つけます。

ccbox sessions --limit 5 --offset 0 --size

2. 最新のセッションのタイムラインを確認します（必要に応じて --limit を増やしてください）。

ccbox history --full --limit 200 --offset 0

ワークフロー（推奨）

段階的なパイプラインに従います。収集 -> フィルタリング -> 要約 -> ラベル付け -> 集約 -> 統合 -> 指示の提案。

Stage 0：対象範囲を選択

• セッション：根本原因を詳しく分析するための単一の .jsonl ログ。
• プロジェクト：1 つのプロジェクトの直近 N 件のセッションから、繰り返し発生する失敗パターンを見つけます。
• 全体：複数のプロジェクトにまたがるパターンを見つけるためのサンプル。

Stage 1：ccbox で根拠を収集

• プロジェクトの検出：ccbox projects
• セッションの一覧表示：ccbox sessions [project-path] --limit N --offset 0 --size
• タイムラインの取得：ccbox history [log-or-project] --full --limit N --offset 0
• スキルの区間（任意）：ccbox skills [log-or-project] --json

すばやくトリアージする場合は、タイムラインから失敗の兆候を探します（例）：error、failed、non-zero、rejected、permission、timeout。

Stage 1.5：確認、訂正、中断を特定

ユーザーによる確認や訂正は、ワークフローの破綻を示す重要な根拠として扱います。エージェントがどこで道を外れたのか、次回それを防ぐルールは何かを特定します。

次のようなユーザーメッセージを探します。

• 意図を明確にするもの（「X のことを言ったのです」「そうではありません」「代わりに Y を使ってください」）。
• 間違いを正すもの（「これは間違っています」「やめてください」「元に戻してください」「指示に従っていません」）。
• 事後に制約を再度伝えるもの（「X を実行しないでください」「絵文字は使わないでください」「cargo を使わないでください」「バージョンを変更しないでください」「自動でリリースしないでください」）。
• 摩擦（ハング、再試行の繰り返し、「キャンセル」、スレッドの放棄）によってセッションを中断するもの。

該当する出来事ごとに、簡潔な「軌道修正記録」を作成します。

• きっかけ：エージェントが直前に行ったこと（ツール呼び出し、計画、編集、または仮定）。
• 訂正：意図の確認や訂正につながったユーザーの発言を正確に記録します。
• 修正：訂正後に何が変わったか（新しい方法、別のツール、より限定した対象範囲）。
• 教訓：遠回りを防げたはずのルール（そのままコピーして使える、プロジェクトまたは全体を対象とするもの）。

セッションが明確な解決に至らず終了した場合（またはユーザーが放棄した場合）は、結果にその旨を記し、根拠に基づいて、中断した可能性のある理由を説明します（例：ハングやタイムアウト、無効なツールの使用の繰り返し、制約の矛盾）。

Stage 2：長いタイムラインを要約（必要な場合のみ）

タイムラインが大きすぎて一度に分析できない場合は、区切って要約します。

• 注目する点：ユーザーの依頼、ツール呼び出し、ツールの出力やエラー、結果。
• 保持する内容：ツール名、コマンドライン、エラーメッセージ、ユーザーからのフィードバック。
• 各区間の要約は 3～5 文に収めます。

Stage 3：セッションごとにツール呼び出しの観点を抽出

対象範囲内の各セッションについて、references/facets.md に準拠する JSON オブジェクトを 1 つ作成します。

スキルの区間が利用できる場合（ccbox skills --json 経由）、可能であれば各失敗に、その時点で有効だったスキルのコンテキストを注記します（例：「この失敗は commit スキルの区間内で発生しました」）。

厳守事項：

• セッションログにある根拠のみを使用します。不明な点を推測してはいけません。
• 「ツールの失敗」と「誤ったアプローチ」を区別します（ツールは成功していても、手段が適切でない場合があります）。
• ユーザーによる明示的な拒否は、独立したカテゴリとして数えます（ツールの失敗ではなく、実行した操作が拒否されたものです）。

ステージ 4：集約と分析

ファセットのセットを集約し、以下を作成します。

• 失敗が多いツールと失敗のカテゴリ。
• 具体的な証拠の抜粋を添えた、3つの根本原因のテーマ。
• 継続的な指示にすべき、繰り返し見られるユーザーの制約。
• ツール呼び出しの失敗を減らし、UX を改善する、エンジンに依存しない推奨事項。

出力テンプレートとして references/report.md を使用します。

ステージ 5：指示の更新案を作成（プロジェクトレベル＋グローバル）

すぐにコピーして使える、追加用のスニペットを2セット作成します。

• プロジェクトレベル：AGENTS.md に追加する箇条書き。
• グローバル：ユーザーのグローバルエージェント指示に追加する箇条書き。

ガイドライン：

• ローカルパス、リポジトリ名、単発のインシデントの詳細を含めないでください。
• 一度限りの修正よりも、繰り返し発生するエラー（2回以上）を防ぐルールを優先してください。
• 各指示には、実行すべきこと、避けるべきこと、その理由を含めてください（1文）。

ステージ 6：成果物

以下を作成します。

• 簡潔な学習事項メモ（Markdown）。references/report.md に従ってください。
• 追加用の AGENTS.md スニペット（プロジェクトレベル）。
• 追加用のグローバル指示スニペット。

任意（将来のメモリーシステム向け）：

• 「AutoMemorial 候補」：継続的なエージェントのメモリーに加えるべきルールを、証拠と適用範囲（プロジェクトまたはグローバル）を付けて、簡潔で構造化されたリストにします。

参考資料

• ファセットのスキーマと分類体系：references/facets.md
• レポートのテンプレートと指示のテンプレート：references/report.md