troubleshooting-assistant

トラブルシューティングアシスタントスキル

Claude Patent Creator の問題を特定して解決するための専門的な診断システムです。

使用するタイミング

システムが動作しない、エラーメッセージが表示される、パフォーマンスが遅い、MCP サーバーが読み込まれない、検索結果がない、またはエラーが返される、GPU が検出されない、BigQuery の認証に失敗する、インデックスの構築に失敗する、テストが失敗する、予期しない動作が発生する場合に使用します。

トラブルシューティングの方法

Problem Reported
  |
[1] Gather Information (errors, recent changes, system state)
  |
[2] Reproduce Issue (minimal test case, consistent?)
  |
[3] Isolate Component (which part failing? dependencies?)
  |
[4] Diagnose Root Cause (check logs, test components, verify config)
  |
[5] Apply Fix (targeted solution, verify works)
  |
[6] Prevent Recurrence (document, add monitoring, update checks)

よくある問題と簡単な解決方法

問題	簡単な解決方法
MCP サーバーが読み込まれない	claude mcp list -> 見つからない場合は再登録します
GPU が検出されない	PyTorch を CUDA 対応版で再インストールします
BigQuery の認証に失敗する	gcloud auth application-default login
インデックスが見つからない	patent-creator rebuild-index
インポートエラー	venv を有効にします：venv\Scripts\activate
検索が遅い	GPU の使用状況を確認し、top_k を減らし、HyDE を無効にします
関連性の低い結果	MPEP の用語を使ってクエリを言い換えます

詳細な問題ガイド

MCP サーバーの問題

問題： サーバーが読み込まれない、ツールが動作しない／エラーを返す

• 5 段階の診断ワークフロー
• パスの確認と修正
• 依存関係のトラブルシューティング
• サーバーの再起動手順

GPU と BigQuery の問題

問題： GPU が検出されない、パフォーマンスが遅い、BigQuery の認証に失敗する、クエリがタイムアウトする

• CUDA の検出と PyTorch の再インストール
• パフォーマンスの診断と最適化
• BigQuery の認証と権限
• タイムアウトの設定

インデックス、依存関係、設定

問題： インデックスが見つからない、構築に失敗する、ModuleNotFoundError、インポートエラー、環境変数が読み込まれない、関連性の低い検索結果

• インデックスの再構築手順
• OOM（メモリ不足）の解決策
• 仮想環境の有効化
• Pydantic の検証エラー
• 設定のトラブルシューティング
• 検索品質の調整

診断ツール

ヘルスチェック一式

# Full system health
patent-creator health

# Individual components
python scripts/test_gpu.py
python scripts/test_bigquery.py
python scripts/test_analyzers.py
python scripts/test_install.py

コンポーネントの切り分け

# Test MPEP search
python -c "from mcp_server.mpep_search import MPEPIndex; \
           index = MPEPIndex(); index.build_index(); \
           print('OK' if index.search('test', top_k=1) else 'FAILED')"

# Test BigQuery
python -c "from mcp_server.bigquery_search import BigQueryPatentSearch; \
           search = BigQueryPatentSearch(); \
           print('OK' if search.search_by_keywords('neural network', limit=1) else 'FAILED')"

# Test analyzers
python -c "from mcp_server.claims_analyzer import ClaimsAnalyzer; \
           analyzer = ClaimsAnalyzer(); \
           print('OK' if analyzer.analyze('1. A test claim.') else 'FAILED')"

• ログ分析（デバッグモード）
• MCP 通信のデバッグ
• パフォーマンスのプロファイリング
• メモリのプロファイリング
• 問題のエスカレーション手順

予防のためのベストプラクティス

1. 定期的なヘルスチェック（毎週 patent-creator health を実行）
2. 警告やエラーがないかログを監視します
3. 依存関係を最新の状態に保ちます（デプロイ前にテストします）
4. 変更前にバックアップを取ります（特にインデックスの再構築時）
5. 変更内容を記録します
6. 変更後にテストします（テストスイートを実行します）
7. バージョン管理を行います（git を使用します）
8. 環境の一貫性を保ちます（同じ Python／CUDA バージョンを使用します）

クイックリファレンス

最もよくあるエラー

エラー	カテゴリ	解決策
"Tool not found"	MCP	claude mcp list
"ModuleNotFoundError"	依存関係	venv を有効にして再インストールします
"CUDA not available"	GPU	PyTorch を CUDA 対応版で再インストールします
"Permission denied" (BigQuery)	認証	gcloud auth application-default login
"Index not found"	インデックス	patent-creator rebuild-index
"Out of memory"	インデックス構築	バッチサイズを減らします
"Validation error"	入力	Pydantic モデルのパラメーターを確認します

診断コマンド

# System health
patent-creator health

# Test components
python scripts/test_gpu.py
python scripts/test_bigquery.py
python scripts/test_install.py

# Check registration
claude mcp list

# Check paths
patent-creator verify-config

# Enable debug logging
export PATENT_LOG_LEVEL=DEBUG