errors

エラーパターン分析

Claude Code のセッションから収集したエラーを分析し、パターンを特定して実行可能な知見を得ます。

クイックスタート

/errors              # Batch analysis of historical error patterns
/debug               # CC 2.1.30 real-time debug for current session

使い分け

コマンド	目的	対象範囲
/errors	エラーパターンの一括分析（過去24時間／7日間）	過去のパターン
/debug	現在のセッション状態をリアルタイムでデバッグ	現在のセッション
fix-issue	特定のバグに対する根本原因分析（RCA）ワークフロー全体	1件の問題

CC 2.1.169 以降： /clear や再起動後も残るエラーの場合、claude --safe-mode を実行すると、すべてのカスタマイズ（CLAUDE.md／プラグイン／スキル／フック／MCP）が無効な状態で起動します。これは、詳細な分析に進む前に「ork／フック／MCP のバグ」と「CC のバグ」を切り分けるためのワンステップのテストです。

クイック分析

# Run batch analysis on last 24h of errors
python .claude/scripts/analyze_errors.py

# Analyze last 7 days
python .claude/scripts/analyze_errors.py --days 7

# Generate markdown report
python .claude/scripts/analyze_errors.py --report

収集される内容

エラー収集フックは次の情報を収集します。

• ツール名（Bash、mcp__memory__search_nodes など）
• エラーメッセージ（先頭500文字）
• ツール入力（失敗したコマンド／クエリ）
• タイムスタンプとセッション ID

場所： .claude/logs/errors.jsonl

現在のエラールール

警告を発生させる学習済みパターンを確認します。

cat .claude/rules/error_rules.json | jq '.rules[] | {id, signature, count: .occurrence_count}'

ファイル

ファイル	目的
.claude/hooks/posttool/error-collector.sh	エラーを JSONL に収集します
.claude/hooks/pretool/bash/error-pattern-warner.sh	リスクの高いコマンドの実行前に警告します
.claude/scripts/analyze_errors.py	パターンの一括分析
.claude/rules/error_rules.json	学習済みエラーパターン
.claude/logs/errors.jsonl	生のエラーログ

よくあるパターン

接続拒否／ポートの誤り

pattern: ECONNREFUSED|connection refused|ERR_CONNECTION_REFUSED|connect ECONNREFUSED
fix: The port may have changed or the service isn't running.
     1. Check services: portless list (if installed)
     2. Use named URLs: api.localhost instead of localhost:PORT
     3. Fallback: lsof -iTCP -sTCP:LISTEN -nP | grep -E 'node|python|java'
     4. Install Portless to avoid port guessing: npm i -g portless

pattern: ERR_CONNECTION_RESET|ECONNRESET|socket hang up
fix: Service may have crashed. Check process logs, restart the service,
     and use agent-browser to verify the app is responding:
     agent-browser open "https://myapp.localhost"

PostgreSQL の接続エラー

pattern: role "X" does not exist
fix: Use Docker connection: docker exec -it orchestkit-postgres-dev psql -U orchestkit_user -d orchestkit_dev

pattern: relation "X" does not exist
fix: Check MCP postgres server connection string - may be connected to wrong database

フックエラー（CC 2.1.98）

CC 2.1.98 以降は、フックエラーの標準エラー出力の先頭行がトランスクリプトに直接表示されるため、--debug は不要です。

pattern: hook.*error|hook.*failed|PreToolUse.*error
diagnosis: Read the stderr line shown in the transcript.
  1. If path error → check CLAUDE_PLUGIN_ROOT is set
  2. If JSON parse error → hook is returning invalid JSON
  3. If timeout → hook exceeds 50ms budget (PreToolUse) or 100ms (PostToolUse)
  4. If "module not found" → run: cd src/hooks && npm run build

関連スキル

• ork:fix-issue：特定したエラーを修正します
• debug-investigator：エラーの根本原因をデバッグします

新しいルールの追加

パターンが2回以上繰り返されると、analyze_errors.py によってルールが自動生成されます。 手動でルールを追加する場合は、.claude/rules/error_rules.json を編集します。

{
  "id": "custom-001",
  "pattern": "your regex pattern",
  "signature": "human readable signature",
  "tool": "Bash",
  "occurrence_count": 1,
  "fix_suggestion": "How to fix this"
}