Skills ログとデバッグ上級

入門レベルのデバッグは print に頼り、上級レベルのデバッグは体系的なログ機構に頼ります。

この記事では、Skill スクリプトに構造化ログを構築する方法と、複雑な実行フローで問題を特定する上級テクニックを紹介します。


logging で print を置き換える

print快速なデバッグには適していますが、本番の Skill では Python 標準ライブラリのloggingモジュールを使用する必要があります。

logging の利点は出力レベルを制御できることです。開発時には DEBUG 情報を出力し、本番時には WARNING 以上のみを出力します。

例

# ファイルパス:scripts/logger_setup.py
import logging
import sys
from datetime import datetime

def get_logger(name: str, level: str = "INFO") -> logging.Logger:
    """
構造化ロガーを作成

パラメータ:
name: ロガー名。通常はモジュール名(__name__)を使用
level: ログレベル。DEBUG / INFO / WARNING / ERROR
    """

    logger = logging.getLogger(name)
    logger.setLevel(getattr(logging, level.upper(), logging.INFO))

    # handler が重複して追加されるのを防ぐ
    if logger.handlers:
        return logger

    # コンソール出力:人間が読みやすい形式
    console = logging.StreamHandler(sys.stdout)
    console.setFormatter(logging.Formatter(
        "[%(asctime)s] [%(levelname)s] %(name)s - %(message)s",
        datefmt="%H:%M:%S"
    ))
    logger.addHandler(console)

    # ファイル出力:ログファイルに書き込む(オプション)
    log_file = f"/home/claude/skill_{datetime.now().strftime('%Y%m%d')}.log"
    file_handler = logging.FileHandler(log_file, encoding="utf-8")
    file_handler.setFormatter(logging.Formatter(
        "%(asctime)s [%(levelname)s] %(name)s:%(lineno)d - %(message)s"
    ))
    logger.addHandler(file_handler)

    return logger

# 使用例
if __name__ == "__main__":
    log = get_logger(__name__, level="DEBUG")

    log.debug("デバッグ情報:ファイルパス = /mnt/user-data/uploads/サンプル.csv")
    log.info("ファイルの処理を開始")
    log.warning("ファイルサイズが 50MB を超えています。処理に時間がかかる可能性があります")
    log.error("ファイル読み取り失敗:FileNotFoundError")
[10:23:01] [DEBUG]   __main__ - 调试信息:文件路径 = /mnt/user-data/uploads/サンプル.csv
[10:23:01] [INFO]    __main__ - 开始处理文件
[10:23:01] [WARNING] __main__ - 文件大小超过 50MB,处理可能较慢
[10:23:01] [ERROR]   __main__ - 文件读取失败:FileNotFoundError

実行時間の追跡

Skill の実行が遅い場合、時間のかかるボトルネックのステップを特定する必要があります。

例

# ファイルパス:scripts/timer.py
import time
import functools
import logging

log = logging.getLogger(__name__)

def timeit(func):
    """デコレータ:関数の実行時間を自動記録"""
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        start = time.perf_counter()
        result = func(*args, **kwargs)
        elapsed = time.perf_counter() - start
        log.info(f"{func.__name__} の実行時間: {elapsed:.3f} 秒")
        return result
    return wrapper

# 使用方法:計測したい関数に @timeit デコレータを付ける
@timeit
def load_csv(file_path: str):
    import pandas as pd
    return pd.read_csv(file_path)

@timeit
def calculate_stats(df):
    return df.describe()

# コンテキストマネージャで手動計時することもできる
class Timer:
    def __init__(self, label: str):
        self.label = label
    def __enter__(self):
        self.start = time.perf_counter()
        return self
    def __exit__(self, *args):
        elapsed = time.perf_counter() - self.start
        log.info(f"{self.label} の実行時間: {elapsed:.3f} 秒")

# Timer コンテキストマネージャを使用
if __name__ == "__main__":
    with Timer("データを読み込んでクリーニング"):
        import pandas as pd
        df = pd.read_csv("/mnt/user-data/uploads/サンプル_data.csv")
        df = df.dropna()
[10:23:05] [INFO] load_csv 耗时 0.342 秒
[10:23:05] [INFO] calculate_stats 耗时 0.018 秒
[10:23:05] [INFO] 读取并清洗数据 耗时 0.361 秒

構造化ログ:JSON 形式の出力

ログを人間が読むのではなくプログラムで解析する必要がある場合は、JSON 形式が適しています。

例

# ファイルパス:scripts/json_logger.py
import json
import sys
from datetime import datetime

def log_event(level: str, event: str, **context):
    """
構造化 JSON ログを出力

パラメータ:
level: ログレベル(info / warning / error)
event: イベント名
context: 追加のコンテキストキーと値のペア
    """

    entry = {
        "timestamp": datetime.now().isoformat(),
        "level":     level,
        "event":     event,
        **context
    }
    # stderr を使用してログを出力し、スクリプトの通常出力と混ざらないようにする
    print(json.dumps(entry, ensure_ascii=False), file=sys.stderr)

# 使用例
log_event("info",    "file_loaded",   file="/mnt/user-data/uploads/サンプル.csv", rows=1024)
log_event("warning", "null_detected", column="score", count=12)
log_event("error",   "parse_failed",  reason="エンコーディングが UTF-8 ではありません")
{"timestamp": "2026-05-18T10:23:05", "level": "info",    "event": "file_loaded",   "file": "/mnt/user-data/uploads/サンプル.csv", "rows": 1024}
{"timestamp": "2026-05-18T10:23:05", "level": "warning", "event": "null_detected", "column": "score", "count": 12}
{"timestamp": "2026-05-18T10:23:05", "level": "error",   "event": "parse_failed",  "reason": "编码不是 UTF-8"}

SKILL.md の命令実行のデバッグ

Claude が SKILL.md の命令に従って実行しない場合、SKILL.md に「チェックポイント」を挿入することで問題を特定できます。

## 调试检查点(开发模式,发布前删除)

在执行每个步骤前,先以以下格式输出一行状态确认:

`[STEP N] 开始:{步骤名称},输入:{关键参数}`

示例:
`[STEP 1] 开始:读取文件,输入:/mnt/user-data/uploads/サンプル.csv`
`[STEP 2] 开始:数据清洗,输入:1024 行`

这样可以在出错时快速定位到哪个步骤失败。

デバッグチェックポイントは一時的なものです。デバッグが完了したら、必ず SKILL.md からこれらの命令を削除してください。そうしないと、本番使用時にユーザーに余分なデバッグ出力が見えてしまいます。


よくあるデバッグシナリオ早見表

シナリオデバッグ方法
Skill がトリガーされないdescription を確認し、複雑なプロンプトでテストし、run_loop.py を実行して最適化
スクリプトで ImportError が発生pip install を実行し、パッケージ名と import 名が一致するか確認
ファイルパスのエラーまず ls /mnt/user-data/uploads/ でファイル名を確認
出力が文字化けするファイル読み込み時に encoding="utf-8" を明示的に指定
ステップの実行順序が正しくないSKILL.md で番号付きリストを使用してステップの順序を明確にする
結果が空になるスクリプトの重要な箇所に print を追加し、どのステップでデータが空になるか確認
その他の拡張