データ分析パイプラインの処理に18時間かかっていました。1日は24時間しかないので、パイプラインが終わる頃には、次の実行を始める時刻が近づいている状態でした。
根本原因は、同じデータを3回分析していたことでした。分析の構成を作り替えた結果、処理時間は18時間から3〜4時間(約80%減)になりました。ただし、計算を1か所に集めたことで、今度は循環的複雑度(CC)が60のメソッドが生まれました。この記事では、Claude Code と進めた「構成の刷新」と「複雑度の分解」の2段階を、数値とあわせて記録します。
Before:なぜ18時間かかっていたか
3つの処理パターンが、それぞれ独立に分析していた
1短期処理の分析(1分/5分/15分/30分/1時間/4時間/日次/週次間隔): 約6時間2中期処理の分析(5分/15分/30分/1時間/4時間/日次間隔): 約5時間3長期処理の分析(4時間/日次/週次間隔): 約7時間4合計: 約18時間たとえば4時間間隔のデータは3つの処理パターンで全く同じなのに、3回別々に計算していました。411種類の分析指標を3回計算するので、実質1,233回の計算です。本当に必要なのは411回でした。
なぜこうなっていたか
プロジェクトの初期に、処理パターンごとに独立したプログラムを作りました。「独立していれば影響範囲が限られて安全」という判断でしたが、データ量が増えるにつれて「同じ計算を何度もする」非効率が深刻になりました。
段階1:計算と判定を分ける
統合分析の構成
1Before:2 short_term.py → 全時間間隔を独自に分析 → 指標計算 → 条件判定 → トリガー出力3 mid_term.py → 全時間間隔を独自に分析 → 指標計算 → 条件判定 → トリガー出力4 long_term.py → 全時間間隔を独自に分析 → 指標計算 → 条件判定 → トリガー出力5
6After:7 unified_analyzer.py → 全時間間隔を1回だけ分析 → 全指標を計算8 ↓(結果を共有)9 shortTermTriggerFileGenerator.py → 条件判定のみ10 midTermTriggerFileGenerator.py → 条件判定のみ11 longTermTriggerFileGenerator.py → 条件判定のみ中心にある考え方は、「指標の計算」と「条件の判定」を分けることです。
unified_analyzer.pyは全指標を計算しますが、条件判定はしません*TriggerFileGenerator.pyは条件を判定しますが、指標の計算はしません
ステップ1:現状分析を AI に頼む
1プロンプト:2short_term.py、mid_term.py、long_term.py の3ファイルを読んで、3重複している処理を特定してください。4各ファイルで共通して実行されている関数・メソッドを一覧にしてください。AI は3ファイルを読み比べて、「4時間間隔の指標Aの計算が3回呼ばれている」「指標Bの計算が全ファイルで同一」といった重複を挙げました。
ステップ2:設計案を AI と比べる
1プロンプト:2重複計算をなくす構成を3案示してください。3各案の長所と短所を比べてください。4制約: 既存のトリガーファイルの形式(JSON)は変更しない。AI が示した3案は次のとおりです。
- 共通関数の抽出: 重複部分を共通モジュールにする
- 統合分析 + 判定の分離: 計算と判定を分ける(採用)
- キャッシュ方式: 計算結果をファイルに保存して再利用する
案2を選んだのは、キャッシュ方式ではファイルの読み書きのコストが増え、共通関数の抽出では「3回呼ぶ」構造そのものが変わらないためです。
ステップ3:処理パターンごとに段階的に移す
一度に全部を移すのは危険なので、処理パターンごとに移しました。
1Phase 1: long_term.py の指標計算を unified_analyzer.py に移す2 → テスト実行 → 本番デプロイ → 1週間運用3
4Phase 2: mid_term.py の指標計算を移す5 → テスト実行 → 本番デプロイ → 1週間運用6
7Phase 3: short_term.py の指標計算を移す8 → テスト実行 → 本番デプロイ → 最終確認各フェーズで、AI には「この Phase の変更だけを実装してください。他の Phase には触れないでください」と明示しました。あわせて、触ってよいファイルと触らないファイルも書きました。
1制約:2- 変更するファイル: unified_analyzer.py, long_term.py3- 変更しないファイル: mid_term.py, short_term.py, トリガーファイルのJSON形式ステップ4:移行前後で出力が同じかを確かめる
1各 Phase の移行前後で:21. 回帰テストを実行し、結果が一致することを確認する32. 本番のトリガーファイル出力を比較し、差分がないことを確認する43. 処理時間を計測し、短くなったことを確認する段階1の結果
| 指標 | Before | After |
|---|---|---|
| 処理時間 | 18時間 | 3〜4時間(約80%減) |
| コードの重複 | 約2,000行 | 0行 |
| 指標の計算回数 | 1,233回(411×3) | 411回 |
| バグ修正が必要な箇所 | 3ファイル | 1ファイル |
| メモリ使用量 | 低い(逐次処理) | 一時的に増える(まとめて処理) |
段階2:統合で1か所に集まった複雑度を分解する
副作用:CC 60 のメソッド
計算を unified_analyzer.py に集めた結果、「1つの分析対象について全指標を計算する」メソッド _analyze_target() に、411指標分の計算ロジックが詰め込まれました。if 文と for 文が何重にもネストし、循環的複雑度は60でした。
循環的複雑度(Cyclomatic Complexity、CC)は、分岐やループの数から制御フローの複雑さを数える指標です。一般的な目安は次のとおりです。
| CC | 目安 |
|---|---|
| 1〜10 | 単純で、テストしやすい |
| 11〜20 | やや複雑で、注意が必要 |
| 21〜50 | 複雑で、テストが難しい |
| 50以上 | テストしきれない。分割が必要 |
重複をなくしたことで「直す場所は1か所」になりましたが、その1か所が誰にも読めない状態では意味がありません。段階1と同じく、AI に分割を任せました。
依頼のプロンプト
1unified_analyzer.py の _analyze_target() メソッドの循環的複雑度を下げてください。2
3制約:4- 外部のインターフェース(引数・戻り値)を変更しないこと5- 既存のテストが全てPASSすること6- 新しいクラスは作成しないこと(メソッド分割のみ)7- 分割したメソッドにはプレフィックス _calc_ を付けること制約を付けずに「リファクタリングしてください」と頼むと、AI は次のような変更をしがちです。
- 新しいクラスを作る: 必要のない抽象化が増えます
- インターフェースを変える: 呼び出し元を全部直すことになります
- デザインパターンを持ち込む: コードベースに馴染まない構造が入ります
「インターフェースを変えない」「メソッド分割のみ」と縛ることで、変更を「中身の移動」に限定できます。段階1の「触らないファイルを明示する」と同じ考え方です。
使った分割のパターン
パターン1:分岐の中身をサブメソッドに出す
1# Before2def process(self, data):3 if data.kind == "A":4 # 分岐やループを含む20行のロジック5 elif data.kind == "B":6 # 分岐やループを含む20行のロジック7 elif data.kind == "C":8 # 分岐やループを含む20行のロジック9
10# After11def process(self, data):12 if data.kind == "A":13 self._calc_kind_a(data)14 elif data.kind == "B":15 self._calc_kind_b(data)2 collapsed lines
16 elif data.kind == "C":17 self._calc_kind_c(data)分岐そのものは残りますが、各分岐の中にあった分岐やループがサブメソッドに移るので、親メソッドの CC が下がります。サブメソッドは単独でテストできるようになります。
パターン2:ガード節で早期リターンする
1# Before(ネストが深い)2def execute(self, item, config):3 if item is not None:4 if item.score > config.min_score:5 if config.enabled:6 if not self.is_paused():7 # 実際の処理8
9# After(CC は同じだが、ネストが0段になる)10def execute(self, item, config):11 if item is None:12 return13 if item.score <= config.min_score:14 return15 if not config.enabled:4 collapsed lines
16 return17 if self.is_paused():18 return19 # 実際の処理ガード節は CC の数値を変えません。それでも、条件を上から順に読めるので、人間がレビューしやすくなります。
パターン3:__init__() から初期化以外の処理を出す
1# Before2def __init__(self, config):3 self.config = config4 # 50行の処理:設定の検証、デフォルト値の設定、依存関係の解決...5
6# After7def __init__(self, config):8 self.config = config9 self._validate_config()10 self._setup_defaults()11 self._resolve_dependencies()同じ手順を他の2つのエンジンにも当てた
分析パイプライン(エンジンA)の後、同じプロンプトと制約で、別の2つの処理エンジン(B・C)の大きなメソッドも分割しました。
| エンジン | 対象メソッド | Before | After |
|---|---|---|---|
| A(分析パイプライン) | _analyze_target() | 60 | 19(-68%) |
| B | __init__() | 53 | 21(-60%) |
| B | _process_batch_main() | 51 | 6(-88%) |
| C | run_session() | 42 | 23(-45%) |
| C | _monitor_resources() | 24 | 10(-58%) |
目標は CC 20以下でしたが、__init__()(21)と run_session()(23)は20をわずかに超えて残りました。5メソッドのうち3つは目標を達成し、2つは未達です。それでも、50前後から20前後まで下がれば、人間が頭の中で処理を追える範囲にはほぼ入ります。
回帰テストで、動作が変わっていないことを確かめる
手順は CLAUDE.md に書いておき、毎回この順で進めさせました。
1リファクタリングの手順:21. まず現在の全テストを実行して、PASS状態を確認する32. リファクタリングを実施する43. 全テストを再実行して、PASS状態が維持されていることを確認する54. 分割後の構造を確かめるテストを追加する1を省くと、もともと落ちていたテストと、分割で壊したテストの区別がつかなくなります。
| エンジン | 構造を確かめるテスト | 回帰テスト | 結果 |
|---|---|---|---|
| A(分析パイプライン) | 20件 | 4,119件 | 全PASS |
| B | 35件 | 2,064件 | 全PASS |
| C | 33件 | 1,270件 | 全PASS |
「構造を確かめるテスト」は、分割後のメソッドが期待どおりに呼ばれることを確認するテストです。「回帰テスト」は、分割の前後で出力が変わらないことを確認します。合わせて約7,400件の回帰テストが通ったことが、「動作は変わっていない」と言える根拠になります。
AIに大規模リファクタリングを任せるコツ
1. スコープを狭く区切る
1❌ 「このシステムをリファクタリングしてください」2✅ 「long_term.pyの指標A計算部分だけをunified_analyzer.pyに移動してください」「3つのファイルを一度に統合して」と頼むと失敗しやすく、「1ファイルずつ移して」と頼むと精度が上がりました。複雑度の分割も、1メソッドずつ頼んでいます。
2. 変えてよいもの・変えないものを書く
触るファイル、触らないファイル、変えないインターフェースを、プロンプトに明記します。AI は「ついでの改善」をしがちなので、何もしなくてよい範囲を先に決めておきます。
3. 前後で同じ出力になることを確かめる
段階1ではトリガーファイルの出力を、段階2では回帰テストを使って、前後の出力が同じであることを確かめました。出力の同一性を示せれば、移行は安全だと言えます。
4. 設計判断を ADR に残す
移行後に、判断の理由を DECISIONS.md に記録しました。将来の AI が「処理パターンごとの個別分析に戻しましょう」と提案してきても、「ADR-001 で却下済み」とすぐに判断できます。
学んだこと
1. 「動いているものは触るな」は負債を増やす
18時間のパイプラインを放置していたら、やがて24時間を超えて破綻していたはずです。性能の問題は「いつか対処する」ではなく、構造から直すべきでした。
2. 重複をなくすと、複雑さが1か所に集まる
重複の排除と複雑度の分解は、別々の作業ではなく1組でした。重複をなくすと修正箇所は減りますが、その分の複雑さが統合先に集まります。統合した直後に CC を測っておけば、段階2をもっと早く始められました。
3. 計算と判定の分離は、多くのシステムに使える
今回の「指標の計算」と「条件の判定」の分離は、データ分析パイプラインに限らず使えます。「データを作る側」と「データを使う側」を分けるのは、重複をなくす基本の形です。
まとめ
- 計算と判定を分ける: 全指標を1回だけ計算し、結果を各処理パターンで使い回すことで、18時間を3〜4時間にしました
- 統合後の複雑度も分解する: 1か所に集まった CC 60 のメソッドを、制約付きのメソッド分割で19にしました。2つのメソッドは目標の20をわずかに超えて残しています
- 段階的に移し、前後の出力で確かめる: 1パターンずつ・1メソッドずつ進め、トリガーファイルの比較と約7,400件の回帰テストで動作の不変を確認しました
ガード節の考え方は、データ形式の変更を、変換の関数では分岐を増やさずに受け止めた「同じ新形式のIDを、正規化は素通しし、検証は全件弾いた」でも使っています。また、重複を作らないための着手前の確認は「セッション着手前に状態を実体から再取得する」にまとめました。