Skills エラー処理とフォールトトレランス
理想的な状況でのみ動作する Skill は脆弱である。
堅牢な Skill は、一般的なエラーを予測し、明確なフィードバックを提供し、可能な限り自動的に回復する必要がある。
エラー処理の3つのレベル
| レベル | 発生場所 | 処理方法 |
|---|---|---|
| 入力検証エラー | 実行前 | 入力をチェックし、不正な場合は直接拒否して理由を説明する |
| 実行時エラー | スクリプト実行中 | 例外をキャッチし、構造化されたエラー情報を出力する |
| 結果の異常 | 実行完了後 | 出力が期待どおりか検証し、期待どおりでない場合はリカバリプロセスを開始する |
SKILL.md でエラー処理戦略を定義する
SKILL.md には、問題が発生したときに Claude が何をすべきかを示す、明確なエラー処理セクションを含める必要があります。
例
## エラー処理
### 入力の問題
- ファイルが存在しない:ユーザーにファイルパスが間違っていることを伝え、再アップロードを依頼する
- ファイル形式がサポートされていない:サポートされている形式(pdf、docx、txt)を一覧表示し、ユーザーに変換後に再試行してもらう
- ファイルが空:ファイルの内容が空で処理できないことを伝える
### 実行の問題
- スクリプトの実行に失敗:完全なエラー情報をユーザーに表示し、隠さない
- 依存関係が未インストール:まず自動インストールを試みる(pipinstall)、失敗した場合はユーザーに手動インストールを伝える
- タイムアウト:もし60秒を超えても未完了の場合、現在の進捗を出力し、ユーザーに待機を続けるかどうかを尋ねる
### 結果の問題
- 出力ファイルが空:処理ロジックを再確認し、考えられる原因をユーザーに説明する
- 出力形式が期待と異なる:実際の出力を表示し、ユーザーに満足しているかどうかを尋ねる
### 入力の問題
- ファイルが存在しない:ユーザーにファイルパスが間違っていることを伝え、再アップロードを依頼する
- ファイル形式がサポートされていない:サポートされている形式(pdf、docx、txt)を一覧表示し、ユーザーに変換後に再試行してもらう
- ファイルが空:ファイルの内容が空で処理できないことを伝える
### 実行の問題
- スクリプトの実行に失敗:完全なエラー情報をユーザーに表示し、隠さない
- 依存関係が未インストール:まず自動インストールを試みる(pipinstall)、失敗した場合はユーザーに手動インストールを伝える
- タイムアウト:もし60秒を超えても未完了の場合、現在の進捗を出力し、ユーザーに待機を続けるかどうかを尋ねる
### 結果の問題
- 出力ファイルが空:処理ロジックを再確認し、考えられる原因をユーザーに説明する
- 出力形式が期待と異なる:実際の出力を表示し、ユーザーに満足しているかどうかを尋ねる
スクリプトにおける標準エラー処理パターン
Python スクリプトは try-except 構造を使用し、status フィールドを含む JSON を統一して返す必要があります。
例
# ファイルパス: scripts/error_handling_demo.py
import json
import sys
import os
class SkillError(Exception):
"""Skill カスタム例外基底クラス"""
def __init__(self, message: str, code: str):
self.message = message
self.code = code # エラーコード。プログラムがエラーの種類を判断しやすくするため
super().__init__(message)
class InputError(SkillError):
"""入力検証エラー"""
pass
class ProcessError(SkillError):
"""処理プロセスエラー"""
pass
def validate_input(file_path: str) -> None:
"""入力を検証し、エラー時に InputError を送出する"""
if not file_path:
raise InputError("ファイルパスが指定されていません", "MISSING_FILE")
if not os.path.exists(file_path):
raise InputError(f"ファイルが存在しません:{file_path}", "FILE_NOT_FOUND")
if os.path.getsize(file_path) == 0:
raise InputError(f"ファイルの内容が空です:{file_path}", "EMPTY_FILE")
def process(file_path: str) -> dict:
"""メイン処理ロジック"""
try:
validate_input(file_path)
with open(file_path, "r", encoding="utf-8") as f:
content = f.read()
# 実際の処理ロジック(ここでは行数カウントに簡略化)
lines = content.split("\n")
return {
"status": "success",
"data": {
"file": file_path,
"lines": len(lines),
"chars": len(content)
}
}
except InputError as e:
# 入力エラー:ユーザーは修正後に再試行できます
return {
"status": "input_error",
"code": e.code,
"message": e.message,
"hint": "ファイルパスが正しいか、ファイルが存在して空でないかを確認してください"
}
except UnicodeDecodeError:
# エンコーディングエラー:具体的な修正方法を提示
return {
"status": "process_error",
"code": "ENCODING_ERROR",
"message": "ファイルのエンコーディングが UTF-8 ではないため、読み取れません",
"hint": "ファイルを UTF-8 エンコーディングで保存し直してから再試行してください"
}
except Exception as e:
# 予期しないエラー:デバッグしやすいよう完全に記録
return {
"status": "unexpected_error",
"code": "UNKNOWN",
"message": str(e),
"hint": "上記のエラー情報を開発者にフィードバックしてください"
}
if __name__ == "__main__":
file_path = sys.argv[1] if len(sys.argv) > 1 else ""
result = process(file_path)
print(json.dumps(result, ensure_ascii=False, indent=2))
import json
import sys
import os
class SkillError(Exception):
"""Skill カスタム例外基底クラス"""
def __init__(self, message: str, code: str):
self.message = message
self.code = code # エラーコード。プログラムがエラーの種類を判断しやすくするため
super().__init__(message)
class InputError(SkillError):
"""入力検証エラー"""
pass
class ProcessError(SkillError):
"""処理プロセスエラー"""
pass
def validate_input(file_path: str) -> None:
"""入力を検証し、エラー時に InputError を送出する"""
if not file_path:
raise InputError("ファイルパスが指定されていません", "MISSING_FILE")
if not os.path.exists(file_path):
raise InputError(f"ファイルが存在しません:{file_path}", "FILE_NOT_FOUND")
if os.path.getsize(file_path) == 0:
raise InputError(f"ファイルの内容が空です:{file_path}", "EMPTY_FILE")
def process(file_path: str) -> dict:
"""メイン処理ロジック"""
try:
validate_input(file_path)
with open(file_path, "r", encoding="utf-8") as f:
content = f.read()
# 実際の処理ロジック(ここでは行数カウントに簡略化)
lines = content.split("\n")
return {
"status": "success",
"data": {
"file": file_path,
"lines": len(lines),
"chars": len(content)
}
}
except InputError as e:
# 入力エラー:ユーザーは修正後に再試行できます
return {
"status": "input_error",
"code": e.code,
"message": e.message,
"hint": "ファイルパスが正しいか、ファイルが存在して空でないかを確認してください"
}
except UnicodeDecodeError:
# エンコーディングエラー:具体的な修正方法を提示
return {
"status": "process_error",
"code": "ENCODING_ERROR",
"message": "ファイルのエンコーディングが UTF-8 ではないため、読み取れません",
"hint": "ファイルを UTF-8 エンコーディングで保存し直してから再試行してください"
}
except Exception as e:
# 予期しないエラー:デバッグしやすいよう完全に記録
return {
"status": "unexpected_error",
"code": "UNKNOWN",
"message": str(e),
"hint": "上記のエラー情報を開発者にフィードバックしてください"
}
if __name__ == "__main__":
file_path = sys.argv[1] if len(sys.argv) > 1 else ""
result = process(file_path)
print(json.dumps(result, ensure_ascii=False, indent=2))
# 文件存在时的成功输出:
{
"status": "success",
"data": {
"file": "/mnt/user-data/uploads/サンプル.txt",
"lines": 128,
"chars": 5432
}
}
# 文件不存在时的错误输出:
{
"status": "input_error",
"code": "FILE_NOT_FOUND",
"message": "文件不存在:/mnt/user-data/uploads/missing.txt",
"hint": "请检查文件路径是否正确,文件是否存在且非空"
}
依存関係の自動インストールのフォールトトレランスパターン
スクリプトが依存する Python パッケージがインストールされていない場合、スクリプト内で自動的にインストールを試みることができます。
例
# ファイルパス: scripts/auto_install_demo.py
import subprocess
import sys
def ensure_package(package_name: str, import_name: str = None) -> bool:
"""
Python パッケージがインストールされていることを確認し、未インストールの場合は自動的にインストールする
パラメータ:
package_name: pip インストール時に使用するパッケージ名(例: "python-docx")
import_name: import 時に使用する名前(例: "docx")、デフォルトは package_name と同じ
"""
import_name = import_name or package_name
try:
__import__(import_name)
return True # インストール済み
except ImportError:
print(f"依存関係をインストール中:{package_name}...")
result = subprocess.run(
[sys.executable, "-m", "pip", "install", package_name,
"--break-system-packages", "--quiet"],
capture_output=True, text=True
)
if result.returncode == 0:
print(f"インストール成功:{package_name}")
return True
else:
print(f"インストール失敗:{package_name}")
print(result.stderr)
return False
# 使用例:スクリプトの先頭で全ての依存関係が準備されていることを確認する
if not ensure_package("pandas"):
sys.exit(1)
if not ensure_package("openpyxl"):
sys.exit(1)
# 依存関係の準備ができたら、通常どおり import
import pandas as pd
print("すべての依存関係が準備できました。実行を開始します...")
import subprocess
import sys
def ensure_package(package_name: str, import_name: str = None) -> bool:
"""
Python パッケージがインストールされていることを確認し、未インストールの場合は自動的にインストールする
パラメータ:
package_name: pip インストール時に使用するパッケージ名(例: "python-docx")
import_name: import 時に使用する名前(例: "docx")、デフォルトは package_name と同じ
"""
import_name = import_name or package_name
try:
__import__(import_name)
return True # インストール済み
except ImportError:
print(f"依存関係をインストール中:{package_name}...")
result = subprocess.run(
[sys.executable, "-m", "pip", "install", package_name,
"--break-system-packages", "--quiet"],
capture_output=True, text=True
)
if result.returncode == 0:
print(f"インストール成功:{package_name}")
return True
else:
print(f"インストール失敗:{package_name}")
print(result.stderr)
return False
# 使用例:スクリプトの先頭で全ての依存関係が準備されていることを確認する
if not ensure_package("pandas"):
sys.exit(1)
if not ensure_package("openpyxl"):
sys.exit(1)
# 依存関係の準備ができたら、通常どおり import
import pandas as pd
print("すべての依存関係が準備できました。実行を開始します...")
自動インストールは開発および軽量なシナリオにのみ適しています。本番環境の Skill では、依存関係をドキュメントに記載し、ユーザーが事前にインストールするようにし、実行時に自動インストールしないでください。
エラーメッセージの記述規範
良いエラーメッセージはユーザーが問題を迅速に特定するのに役立ちますが、悪いエラーメッセージはユーザーを混乱させるだけです。
| 観点 | 悪い書き方 | 良い書き方 |
|---|---|---|
| 問題の説明 | "エラーが発生しました" | ファイル report.csv はアップロードディレクトリに存在しません |
| 原因の説明 | (なし) | "ファイル名のスペルが間違っているか、ファイルがまだアップロードされていない可能性があります" |
| 対処方法の提示 | (なし) | "ファイルを再アップロードするか、ファイル名が正しいか確認してください" |
例
# 悪いエラーメッセージ
raise Exception("Error")
# 良いエラーメッセージ
raise InputError(
"ファイル サンプル_data.csv がアップロードディレクトリ内に見つかりません。"
"考えられる原因:ファイル名のスペルが間違っているか、ファイルがまだアップロードされていません。"
"ファイルを再アップロードしてから再試行してください。",
code="FILE_NOT_FOUND"
)
raise Exception("Error")
# 良いエラーメッセージ
raise InputError(
"ファイル サンプル_data.csv がアップロードディレクトリ内に見つかりません。"
"考えられる原因:ファイル名のスペルが間違っているか、ファイルがまだアップロードされていません。"
"ファイルを再アップロードしてから再試行してください。",
code="FILE_NOT_FOUND"
)