modular-code

モジュール化されたコード構成

保守しやすく、AI を活用した開発に適したサイズのファイルで、モジュール化された Python コードを記述します。

ファイルサイズの目安

行数	状態	対応
150-500	最適	AI コードエディターと人間の理解に適した範囲です
500-1000	大きい	自然な分割ポイントを探します
1000-2000	大きすぎる	役割を絞ったモジュールにリファクタリングします
2000+	重大	分割が必須です。ツールの問題や認知負荷の増大につながります

分割するタイミング

次のいずれかに該当する場合は、分割します。

• ファイルが 500 行を超えている
• 1 つのファイルに関連性のない複数の関心事が含まれている
• 関数を探す際にスクロールが負担になる
• ファイルのテストを整理しにくい
• AI ツールがコンテキストを切り詰めたり、見落としたりする

分割方法

自然な分割ポイント

1. ドメイン概念ごと：auth.py → auth/login.py、auth/tokens.py、auth/permissions.py
2. 抽象化レイヤーごと：インターフェースと実装を分離します
3. データ型ごと：関連するデータ構造に対する操作をまとめます
4. I/O 境界ごと：データベース、API、ファイル操作を分離します

パッケージ構成

feature/
├── __init__.py      # Keep minimal, just exports
├── core.py          # Main logic (under 500 lines)
├── models.py        # Data structures
├── handlers.py      # I/O and side effects
└── utils.py         # Pure helper functions

推奨事項

• 意味のあるモジュール名を使います（utils2.py ではなく data_storage.py）
• __init__.py ファイルは最小限にするか、空のままにします
• 関連する関数をまとめます
• 純粋関数と副作用のある処理を分離します
• モジュール名には snake_case を使います

禁止事項

• 行数だけを基準にして、恣意的にファイルを分割する
• 単一の関数だけを含むモジュールを作成する
• 過剰にモジュール化して「パッケージ地獄」を招く
• モジュール名にドットや特殊文字を使う
• 「マジック」インポートで依存関係を隠す

大きなファイルのリファクタリング

既存の大きなファイルを分割する場合：

1. まとまりを特定する：関連する関数のグループを見つけます
2. 段階的に抽出する：一度に 1 つのまとまりを移動します
3. インポートを更新する：すべてのインポート文を修正します
4. テストを実行する：移動のたびに問題がないことを確認します
5. ドキュメントを更新する：古い場所への参照を更新します

現在のコードベースで検討が必要なファイル

対応が必要な 2000 行超のファイル：

• Math の計算モジュール（scipy、mpmath、numpy） — ドメイン固有のため、分割しなくても問題ない場合があります
• patterns.py — パターンの種類ごとに分割することを検討してください
• memory_backfill.py — 処理の種類ごとに分割することを検討してください

参考資料

• Python エキスパートへの道
• Python プロジェクトのベストプラクティス - Dagster
• AI エディターに適した Python ファイルサイズ
• PEP 8 スタイルガイド