agenttrace セッション監査 は何をしますか?
概要
このスキルを使用して、agenttrace でローカルのAIコーディングエージェントセッションを検査します。実行の背後にあるプロセス、つまりトークンとコストのスパイク、ツール障害、リトライループ、レイテンシギャップ、異常、健全性スコア、セッション間の差分に焦点を当てます。
agenttrace はローカルファーストであり、Claude Code、Codex CLI、Gemini CLI、Aider、Cursor エクスポート、OpenCode、Qwen Code、Kimi、および汎用のJSONまたはJSONLトレースなどのツールからセッションログを読み取ります。
このスキルを使用するタイミング
- ユーザーがAIコーディング実行が遅かった、高コストだった、浅かった、または信頼性が低かった理由を尋ねたとき。
- 失敗した、または疑わしいタスクを再試行する前に、ローカルのエージェントログを確認するとき。
- AI支援コーディングセッションのための軽量なCI健全性ゲートを構築するとき。
- 2つの試行を比較し、変更されたツールパス、リトライ、またはコストパターンを探すとき。
動作方法
ステップ 1: 利用可能なセッションを発見する
agenttrace バイナリが PATH 上で利用可能な場合は、インストール済みのものを優先します。現在のリポジトリが luoyuctl/agenttrace の場合は、代わりに go run ./cmd/agenttrace を使用します。
agenttrace --doctor
agenttrace --overview
セッションが検出されない場合は、--doctor によってチェックされたディレクトリを報告し、エクスポートされたセッションファイルまたはログディレクトリを尋ねます。
ステップ 2: 人間が読める監査レポートを作成する
ユーザーが検査または共有できる簡潔なレポートを希望する場合は、Markdownを使用します。
agenttrace --overview -f markdown -o agenttrace-overview.md
レポートでは、最もリスクの高いセッションを最初に提示し、その重要性を説明します。重要な異常、繰り返されるツール障害、トークンまたはコストの浪費、長いレイテンシギャップ、低い健全性スコア、不自然に浅いセッションなどです。
ステップ 3: 1つのセッションまたはディレクトリを検査する
クイックチェックには最新のセッションを使用し、ユーザーが明示的なエクスポートパスを提供した場合はそれを渡します。
agenttrace --latest
agenttrace --latest -f json
agenttrace path/to/session-or-export.json
agenttrace --overview -d path/to/session-dir
ステップ 4: セマンティクスが重要な場合に試行を比較する
トークンとレイテンシのメトリクスは、エージェントが自信を持って誤った実装パスを取った場合でも健全に見えることがあります。リスクがセマンティックドリフト(意味のずれ)である場合は、トレース監査と以前の試行または既知の正常な試行との差分を組み合わせます。
以下の点を確認します:
- 意図したタスクから逸脱している変更されたファイルまたはコマンド
- 参照試行と比較した、欠落しているテストまたは検証ステップ
- 明確な理由なく同じファイルの周りで繰り返される編集
- 必要な探索をスキップしたことによる低コスト
ステップ 5: 自動化ゲートを追加する
CIまたは反復可能なチームワークフローの場合は、JSON出力または健全性しきい値を使用します。
agenttrace --overview -f json -o agenttrace-overview.json
agenttrace --overview --fail-under-health 80 --fail-on-critical --max-tool-fail-rate 15
しきい値はプロジェクトに合わせて調整します。厳格なゲートは重要なワークフローに役立ちます。チームがベースラインを学習している間は、レポートのみのコマンドの方が適しています。
例
クイックローカルレビュー
agenttrace --overview
agenttrace --latest
長時間のコーディングエージェント実行後、次のプロンプトでタスクを分割すべきか、失敗するツールパスを回避すべきか、欠けているテストを追加すべきか、コンテキストをリセットすべきかを判断するために使用します。
CI健全性チェック
agenttrace --overview --fail-under-health 80 --fail-on-critical
CIでエージェントセッションログが利用可能であり、チームが重要な異常や不健全な実行に対するシンプルなガードを望む場合に使用します。
ベストプラクティス
- セッション発見が不確かな場合は
--doctorから始めます。 - 欠落しているフィールドはそのまま報告します。コスト、モデル、レイテンシ、健全性データをでっち上げないでください。
- プロンプト、コード、セッション内容はプライベートなローカルデータとして扱います。
- 自動化にはJSON出力を、人間のレビューにはMarkdown出力を優先します。
- プロセスの失敗にはトレースメトリクスを、セマンティックドリフトには差分/参照レビューを使用します。
制限事項
- agenttrace はローカルに存在するか、エクスポートとして提供されたログのみを分析できます。
- 一部のエージェントはコスト、モデル、キャッシュ使用、レイテンシを推測するのに十分なフィールドを公開しません。
- 健全なトレースメトリクスは最終的なコードの正しさを証明するものではありません。引き続きテストを実行し、差分をレビューしてください。
- CIゲートは、チームが通常のベースライン動作を理解するまでは、アドバイザリとして開始する必要があります。
セキュリティと安全に関する注意事項
- ユーザーが明示的に承認しない限り、プライベートなセッションログを外部サービスにアップロードしないでください。
- ユーザーが明示的にその出力パスを要求しない限り、ユーザーのレポートを上書きしないでください。
- プロンプト、ツール出力、環境変数、またはログに含まれる機密情報を印刷しないでください。
よくある落とし穴
-
問題: セッションが見つかりません。 解決策:
agenttrace --doctorを実行し、agenttrace をエクスポートされたファイルまたはログディレクトリに指定します。 -
問題: 実行は安価で高速に見えたが、誤ったリファクタリングを生成した。 解決策: セッションを以前の試行または既知の正常な差分と比較します。コストメトリクスだけではセマンティックドリフトを見逃します。
-
問題: 健全性ゲートを追加した後、CIの失敗が多すぎる。 解決策: JSONまたはMarkdownレポートから始め、通常のベースラインを検査し、その後しきい値を徐々に厳しくします。
関連スキル
@langfuse- 本番LLMアプリケーションのトレーシングと評価に使用します。@observability-engineer- より広範なサービス監視、SLO、インシデントワークフローに使用します。