reasoning-trace-optimizer

推論トレースオプティマイザー

推論トレースを分析し、AI エージェントをデバッグして最適化します。このスキルは MiniMax M2.1 のインターリーブ思考を活用し、エージェントの意思決定を深く把握して、具体的な改善策を生成します。

有効化するタイミング

• エージェントの推論トレースのデバッグ、分析、またはプロンプトの最適化が必要な場合
• エージェントのタスクが失敗し、ユーザーがその理由を知りたい場合
• ユーザーが「コンテキストの劣化」、「ツールの混乱」、「指示からの逸脱」に言及した場合
• エージェントのパフォーマンス向上やエラー削減の依頼があった場合
• ユーザーがデバッグセッションで得た知見を共有可能な形で生成したい場合
• 類似タスクで失敗が繰り返された後

主要な概念

インターリーブ思考

最初に一度だけ思考する標準的な推論モデルとは異なり、インターリーブ思考ではツールとのやり取りの間にも推論を行います。これは次の理由から重要です。

1. 長期にわたるタスクでは、多くのターンを通じて集中力を維持する必要があります
2. 外部からの変化（ツールの出力、環境の変化）にリアルタイムで適応する必要があります
3. デバッグでは、何を出力したかだけでなく、どのように意思決定したかを確認する必要があります

最適化ループ

Execute Agent → Capture Traces → Analyze Patterns → Optimize Prompt → Re-run
                                                          ↑____________|

検出されたパターンに基づいてプロンプトを改善し、収束するまで各反復を続けます。

パターン検出

アナライザーが検出する一般的な失敗パターン：

パターン	説明
context_degradation	長いコンテキストでモデルが情報を見失います
tool_confusion	モデルがツールの機能や出力を誤解します
instruction_drift	モデルが元の指示から徐々に逸脱します
goal_abandonment	モデルが元の目標の追求をやめます
circular_reasoning	モデルが進展のないまま同様の操作を繰り返します
premature_conclusion	モデルがタスクを完了する前に結論を出します

使用モード

モード 1：M2.1 エージェントのデバッグ

M2.1 でタスクを実行し、その推論を分析します。

from reasoning_trace_optimizer import TraceCapture, TraceAnalyzer

capture = TraceCapture()
trace = capture.run(
    task="Search for Python tutorials and summarize them",
    system_prompt="You are a research assistant.",
    tools=[search_tool],
    tool_executor=execute_search
)

analyzer = TraceAnalyzer()
analysis = analyzer.analyze(trace)

print(f"Score: {analysis.overall_score}/100")
for pattern in analysis.patterns:
    print(f"Found: {pattern.type.value} - {pattern.suggestion}")

モード 2：完全な最適化ループ

プロンプトが最適化されるまで、自動的に反復します。

from reasoning_trace_optimizer import OptimizationLoop, LoopConfig

config = LoopConfig(
    max_iterations=5,
    min_score_threshold=80.0,
)

loop = OptimizationLoop(config=config)
result = loop.run(
    task="Analyze this codebase and suggest improvements",
    initial_prompt="You are a code reviewer.",
    tools=[read_file_tool, search_tool],
    tool_executor=execute_tool
)

print(f"Improved: {result.initial_score} → {result.final_score}")
print(f"Final prompt:\n{result.final_prompt}")

モード 3：汎用セッション分析

任意のエージェントの過去の思考を分析します（Claude、GPT などに対応）。

このスキルを Claude Code で有効にすると、現在のセッションの思考ブロックを分析し、問題を特定して改善策を提案できます。

/reasoning-trace-optimizer analyze-session

モード 4：共有可能なスキルの生成

最適化で得た知見を、再利用可能な Agent Skills に変換します。

from reasoning_trace_optimizer import SkillGenerator

generator = SkillGenerator()
skill_path = generator.generate(
    result=loop_result,
    skill_name="web-search-best-practices",
    output_dir="./skills"
)

CLI コマンド

# Capture reasoning trace
rto capture "Search for Python tutorials" -s "You are a helpful assistant."

# Analyze a task
rto analyze "Debug this code" -o analysis.txt

# Run optimization loop
rto optimize "Research AI papers" --max-iterations 5 --generate-skill

# Generate skill from artifacts
rto generate-skill my-skill-name --artifacts-dir ./optimization_artifacts

Claude Code との統合

失敗時の自動起動

失敗を自動的に分析するように、フックに追加します。

{
  "hooks": {
    "post_tool_error": {
      "command": "rto analyze-session --last-error"
    }
  }
}

オンデマンド分析

スラッシュコマンドを使って、現在のセッションを分析します。

/reasoning-trace-optimizer

これにより、次の処理が行われます。

1. 現在のセッションから思考ブロックを抽出します
2. パターンと問題を特定します
3. プロンプトの改善策を提案します
4. 必要に応じてシステムプロンプトを更新します

ガイドライン

1. コンテキスト全体を保持する：最適なパフォーマンスを得るには、M2.1 で思考ブロックを含む応答履歴全体が必要です
2. 適切なツールを使う：曖昧さのない説明を記述して、ツールを明確に定義します
3. 現実的な収束しきい値を設定する：1 回の反復あたり 5～10％の改善が一般的です
4. 生成されたスキルを確認する：自動生成されたスキルは、共有する前に確認してください
5. トークン使用量を監視する：最適化の反復ごとに大量のトークンを使用します

例

最適化前

System: You are a helpful assistant.

Issue: Agent called wrong tools, lost track of goal after 3 turns
Score: 45/100
Patterns: tool_confusion, goal_abandonment

最適化後

System: You are a research assistant focused on finding accurate information.

IMPORTANT GUIDELINES:
- Always verify search results before summarizing
- If a tool returns an error, try an alternative approach
- Keep track of your original goal throughout the task
- Validate findings against multiple sources when possible

Issue: None
Score: 85/100
Patterns: None detected

参考資料

• MiniMax M2.1 のドキュメント：https://platform.minimax.io/docs
• インターリーブ思考ガイド：docs/interleavedthinking.md を参照
• エージェントの汎化：docs/agentthinking.md を参照

---

スキルのメタデータ

作成日：2025-01-11 作成者：Muratcan Koylan バージョン：0.1.0 Powered by：MiniMax M2.1 パートナーシップ：MiniMax AI との共同開発