Error Resolver

すべての言語とフレームワークに対応した、第一原理に基づくエラー診断と解決のアプローチです。

コア哲学

5ステップエラー解決プロセス:

1. CLASSIFY  ->  2. PARSE  ->  3. MATCH  ->  4. ANALYZE  ->  5. RESOLVE
     |              |             |             |              |
 どの種類か？  重要情報を    既知の      根本原因       修正 +
             抽出          パターン？   分析          予防

クイックスタート

エラーが発生した場合:

1. 完全なエラーを貼り付ける (スタックトレースがあれば含める)
2. コンテキストを提供する (何をしようとしていたのか?)
3. 関連するコードを共有する (関わっているファイル/関数)

エラー分類フレームワーク

主要カテゴリ

カテゴリ	指標	一般的な原因
Syntax	Parse error、Unexpected token	タイプミス、括弧の欠落、無効な構文
Type	TypeError、型の不一致	間違ったデータ型、null/undefined へのアクセス
Reference	ReferenceError、NameError	未定義の変数、スコープの問題
Runtime	RuntimeError、Exception	ロジックエラー、無効な操作
Network	ECONNREFUSED、timeout、4xx/5xx	接続の問題、誤った URL、サーバーダウン
Permission	EACCES、PermissionError	ファイル/ディレクトリアクセス、sudo が必要
Dependency	ModuleNotFound、Cannot find module	パッケージの欠落、バージョン不一致
Configuration	Config error、env missing	不正な設定、環境変数の欠落
Database	Connection refused、query error	DB ダウン、不正な認証情報、不正なクエリ
Memory	OOM、heap out of memory	メモリリーク、大規模データ処理

二次属性

• Severity: Fatal / Error / Warning / Info
• Scope: Build-time / Runtime / Test-time
• Origin: User code / Framework / Third-party / System

分析ワークフロー

ステップ 1: 分類

エラーカテゴリを識別するため、次を検査します:

• エラー名/コード (ENOENT、TypeError など)
• エラーメッセージのキーワード
• 発生した箇所 (コンパイル、実行時、テスト)

ステップ 2: 解析

重要な情報を抽出します:

- エラーコード: [特定のコードがあれば]
- ファイルパス: [エラーが発生した場所]
- 行番号: [利用可能な場合は正確な行]
- 関数/メソッド: [エラーのコンテキスト]
- 変数/値: [関係していたもの]
- スタックトレース深度: [呼び出しスタックの深さ]

ステップ 3: パターンマッチング

既知のエラーパターンと照合します:

• 言語固有のパターンについては patterns/ ディレクトリを参照
• エラーシグネチャを既知の解決策と照合
• リプレイ履歴で以前の解決策をチェック

ステップ 4: 根本原因分析

5 つの Why 技法を適用します:

エラー: Cannot read property 'name' of undefined
  Why 1? -> user オブジェクトが undefined
  Why 2? -> API 呼び出しが null を返した
  Why 3? -> ユーザー ID がデータベースに存在しない
  Why 4? -> ID は古いキャッシュから取得された
  Why 5? -> キャッシュ無効化ロジックが実装されていない

根本原因: キャッシュ無効化ロジックの欠落

ステップ 5: 解決

実行可能なソリューションを生成します:

1. 即座の修正 - 今すぐに機能させる
2. 適切な修正 - 正しい解決方法
3. 予防 - 今後どう避けるか

出力形式

エラーを解決する際、以下を提供します:

## Error Diagnosis

**Classification**: [Category] / [Severity] / [Scope]

**Error Signature**:
- Code: [error code]
- Type: [error type]
- Location: [file:line]

## Root Cause

[このエラーが発生した理由の説明]

**Contributing Factors**:
1. [要因 1]
2. [要因 2]

## Solution

### Immediate Fix
[解決するためのクイックステップ]

### Code Change
[追加/変更する特定のコード]

### Verification
[修正が機能することを確認する方法]

## Prevention

[将来このエラーを防ぐ方法]

## Replay Tag

[このソリューションの一意識別子 - 将来の参照用]

リプレイシステム

リプレイシステムは、成功したソリューションを記録して将来の参照に活用します。

ソリューションの記録

エラーを解決した後、記録します:

# プロジェクトでソリューション記録を作成
mkdir -p .claude/error-solutions

# ソリューションファイル形式: [error-type]-[hash].yaml

ソリューション記録形式

# .claude/error-solutions/[error-signature].yaml
id: "nodejs-module-not-found-express"
created: "2024-01-15T10:30:00Z"
updated: "2024-01-20T14:22:00Z"

error:
  type: "dependency"
  category: "ModuleNotFound"
  language: "nodejs"
  pattern: "Cannot find module 'express'"
  context: "npm project, missing dependency"

diagnosis:
  root_cause: "Package not installed or node_modules corrupted"
  factors:
    - "Missing npm install after git clone"
    - "Corrupted node_modules directory"
    - "Package not in package.json"

solution:
  immediate:
    - "Run: npm install express"
  proper:
    - "Check package.json has express listed"
    - "Run: rm -rf node_modules && npm install"
  code_change: null

verification:
  - "Run the application again"
  - "Check express is in node_modules"

prevention:
  - "Add npm install to project setup docs"
  - "Use npm ci in CI/CD pipelines"

metadata:
  occurrences: 5
  last_resolved: "2024-01-20T14:22:00Z"
  success_rate: 1.0
  tags: ["nodejs", "npm", "dependency"]

リプレイ検索

エラーに遭遇したら:

1. エラーメッセージからエラーシグネチャを生成
2. .claude/error-solutions/ でマッチするパターンを検索
3. 見つかった場合、記録されたソリューションを適用
4. 新しい場合、完全な分析を実施してソリューションを記録

エラーシグネチャ生成

signature = hash(
  error_type +
  error_code +
  normalized_message +  # 特定の値を削除
  language +
  framework
)

例の変換:

• Cannot find module 'express' -> Cannot find module '{module}'
• TypeError: Cannot read property 'name' of undefined -> TypeError: Cannot read property '{prop}' of undefined

デバッグコマンド

デバッグ中に有用なコマンド:

Node.js

# 詳細なエラー出力
NODE_DEBUG=* node app.js

# メモリデバッグ
node --inspect app.js

# インストール済みパッケージの確認
npm ls [package-name]

# package.json の検証
npm ls --depth=0

Python

# デバッグモード
python -m pdb script.py

# インストール済みパッケージの確認
pip show [package-name]
pip list

汎用

# ファイルパーミッションの確認
ls -la [file]

# ポート使用状況の確認
lsof -i :[port]
netstat -an | grep [port]

# 環境変数の確認
env | grep [VAR_NAME]
printenv [VAR_NAME]

# ディスク容量の確認
df -h

# メモリの確認
free -m  # Linux
vm_stat  # macOS

一般的なデバッグパターン

パターン 1: 二分探索

エラー位置が不明な場合:

1. コードの半分をコメントアウト
2. エラーが続く場合、残りの半分に存在
3. 正確な行が見つかるまで繰り返す

パターン 2: 最小限の再現

エラーを再現する最小コードを作成します:

1. 空ファイルから始める
2. コードを少しずつ追加
3. エラーが現れたら停止
4. これが最小限の再現ケースです

パターン 3: ラバーダックデバッグ

問題を大声で説明します (または Claude に説明):

1. 何が起こるべきですか?
2. 実際に何が起こりますか?
3. 最近何が変わりましたか?
4. どのような前提を立てていますか?

パターン 4: Git Bisect

バグを引き起こしたコミットを見つけます:

git bisect start
git bisect bad  # 現在のコミットは不正
git bisect good [last-known-good-commit]
# Git があなたがテストするコミットをチェックアウトします
git bisect good/bad  # それぞれを良いまたは悪いとマーク
git bisect reset  # 完了時

リファレンスファイル

• patterns/ - 言語固有のエラーパターン

  • nodejs.md - Node.js 一般的なエラー
  • python.md - Python 一般的なエラー
  • react.md - React/Next.js エラー
  • database.md - データベースエラー
  • docker.md - Docker/コンテナエラー
  • git.md - Git エラー
  • network.md - ネットワーク/API エラー

• analysis/ - 分析方法論

  • stack-trace.md - スタックトレース解析ガイド
  • root-cause.md - 根本原因分析手法

• replay/ - リプレイシステム

  • solution-template.yaml - ソリューション記録用テンプレート