/sc:troubleshootでデバッグを構造化する：Claude Codeの分析コマンド活用術

1
人間: 「このエラーを直してください」
2
       TypeError: unsupported operand type(s) for +: 'NoneType' and 'float'
3

4
AI:   「None チェックを追加しました」
5
       if value is not None:
6
           result = value + offset
7

8
人間: 「テストは通ったけど、なぜ value が None になるのか未解決」

1
[症状]
2
- エラーメッセージ: TypeError: unsupported operand type(s) for +
3
- 発生場所: unified_analyzer.py:245
4
- 発生条件: source_alphaの分析時のみ
5
- 頻度: 毎回
6
- 環境: 本番（launchd経由）

1
[仮説]
2
H1: 外部APIのレスポンスにNullフィールドが含まれている
3
H2: 中間データのParquetファイルにNaN値がある
4
H3: 前段の計算で例外がキャッチされ、Noneが返されている
5
H4: 環境変数の不足で設定ファイルが読めていない

1
# H1の検証: APIレスポンスの確認
2
response = api_client.get_records("source_alpha", count=10)
3
print(response)  # → Nullフィールドなし → H1棄却
4

5
# H2の検証: Parquetの中身を確認
6
df = pd.read_parquet("pipeline_source_alpha_*.parquet")
7
print(df.isnull().sum())  # → moving_avg_14列に3個のNaN → H2有力
8

9
# H3の検証: 前段の処理のログ確認
10
# → NaN発生は createIntermediateData.py の出力段階から存在 → H2確定

1
[根本原因]
2
createIntermediateData.py がAPIから取得したデータの先頭3行では
3
移動平均（Moving Average）の計算に必要な過去14件のデータポイントが
4
不足しているため、moving_avg_14がNaNとなる。
5

6
下流の unified_analyzer.py ではNaN値を想定した処理がないため、
7
NoneType + float のTypeErrorが発生する。

1
# 根本原因の修正: データ生成時にNaN行を除去
2
df = df.dropna(subset=["moving_avg_14"])
3

4
# 防御的チェックの追加（上流が修正されても安全）
5
if pd.isna(avg_value):
6
    logger.warning(f"moving_avg_14 is NaN for {source}, skipping")
7
    continue

1
プロンプト:
2
/sc:analyze unified_analyzer.py の _analyze_source メソッドに
3
moving_avg_14 の NaN チェックを追加する変更の影響範囲を分析してください。

1
分析結果:
2
[品質]
3
- 変更箇所の循環的複雑度: +1（許容範囲）
4
- テストカバレッジへの影響: NaN入力のテストケース追加が必要
5

6
[セキュリティ]
7
- 問題なし
8

9
[パフォーマンス]
10
- dropna()は全行スキャンのため、大量データでは影響あり
11
- 推奨: 計算の先頭ウォームアップ期間を除外するアプローチ
12

13
[影響範囲]
14
- unified_analyzer.py: 直接変更
15
- outputFileGenerator.py: moving_avg_14を参照（動作変更なし）
1 collapsed line
16
- batch_engine.py: 中間データにmoving_avg_14が含まれる前提（変更不要）

1
プロンプト:
2
/sc:analyze 施策B3（バッチ分割処理）と施策B4（Z-score閾値判定）の
3
コードを分析し、リソース操作の競合がないか確認してください。

1
分析結果:
2
⚠️ 潜在的リスク検出:
3

4
B3の _allocate_grid_resource() と B4の _check_zscore_threshold() が
5
同一データソースのリソースを操作する可能性があります。
6

7
B3: リソースを確保 → resource_id を取得
8
B4: 全リソースをスキャン → Z-score 閾値超えで解放
9

10
B4は「自分が確保したリソース」と「B3が確保したリソース」を
11
区別できない設計になっています。
12

13
推奨: リソースにタグ（施策ID）を付与し、
14
自施策のリソースのみを操作する設計に変更。

1
Step 1 [症状]:
2
- output_*.json が7日間生成されていない
3
- launchdジョブは正常実行（launchctl listに表示）
4
- stderrログにエラーなし
5
- 最終正常動作: 03-01
6

7
Step 2 [仮説]:
8
H1: daily_preparation.py が異常終了しているが、exitコード0で終了
9
H2: データ読み込み対象ファイルが空で、処理がスキップされている
10
H3: インポートエラーが発生しているが、except句で握りつぶされている
11
H4: 別施策のデプロイでモジュール名が変更された
12

13
Step 3 [検証]:
14
# H4の検証: git log で 03-01 前後のコミットを確認
15
git log --oneline --since="2026-02-28" --until="2026-03-08"
17 collapsed lines
16
# → 03-01に施策B4のデプロイあり。core/ 配下のファイル名変更を含む
17

18
# 当該ファイルのインポートを確認
19
python -c "from core.shared.tier_classifier import TierClassifier"
20
# → ModuleNotFoundError! （ただしlaunchd環境ではexceptで握りつぶし）
21

22
Step 4 [根本原因]:
23
施策B4のデプロイで _dataProcessingEngineA/core/shared/ 内のモジュール名が
24
変更されたが、daily_preparation.py では旧名でインポートしていた。
25
launchd環境では PYTHONPATH の設定により、相対インポート
26
`from core.shared.X import Y` が解決できず ModuleNotFoundError が発生。
27
しかし外側の try-except で握りつぶされ、エラーログなしで終了していた。
28

29
Step 5 [修正]:
30
1. 絶対インポートに変更: from _dataProcessingEngineA.core.shared.X import Y
31
2. CI/CD に絶対インポート強制チェックを追加
32
3. CLAUDE.md にインポートルールを追記

1
❌ 「動きません」
2
✅ 「source_alphaの分析時のみ、unified_analyzer.py:245でTypeError。
3
    source_betaでは正常。launchd経由の本番環境で発生。」

1
❌ 「エラーが出ました」
2
✅ 「以下のstderrログを確認してください：
3
    [2026-03-24 09:05:12] ERROR - TypeError: unsupported operand type(s)
4
    for +: 'NoneType' and 'float'
5
    File "/Users/htada/projects/_dataProcessingEngineA/unified_analyzer.py",
6
    line 245, in _analyze_source」

1
✅ 「H1（APIレスポンスの問題）は検証済みで棄却。
2
    H2（Parquetデータの問題）を検証中です。」

1
✅ 「修正だけでなく、同じ種類のバグを今後防ぐための
2
    CLAUDE.mdルールまたはテストを提案してください。」