python-design-modularity

Python の設計とモジュール化

概要

明示的なモジュール契約を備えた、読みやすさ優先の設計です。 コードを保守しやすく、安全に変更できるよう、制御フロー、データの流れ、所有権の境界を明確に保ちます。

これらの推奨事項は、望ましいデフォルトとして扱ってください。 デフォルトがプロジェクトの制約と相反する場合は、より適した代替案を提案し、トレードオフと補完策（テスト、オブザーバビリティ、移行、ロールバック）を明示してください。

使用する場面

• モジュール、パッケージ、または所有権の境界を再構成するとき
• 巨大なクラスや深くネストした階層を分割するとき
• コンポジションと継承のどちらを選ぶか検討するとき
• 関数型コア／命令型シェルの分離を適用するとき
• 複数のモジュールにまたがるリファクタリングを計画するとき
• コードの読みやすさやアーキテクチャの明瞭さをレビューするとき

使用しない場面：

• 純粋なパフォーマンス最適化 — python-concurrency-performance を参照してください
• エラー処理とレジリエンスのパターン — python-errors-reliability を参照してください
• 型の契約とプロトコル設計 — python-types-contracts を参照してください
• 保守する予定のない、一度限りのスクリプトや使い捨てコード

クイックリファレンス

• 制御フローとデータの流れを明示します。
• モジュールの所有権と不変条件を明示します。
• デフォルトではコンポジションを優先します。
• テスト容易性と関心の分離が向上する場合は、関数型コア／命令型シェルを適用します。
• 振る舞いの変更と構造的なリファクタリングを分離し、同じコミットに混在させないでください。

よくある間違い

• 振る舞いと構造を同時にリファクタリングする — 2種類のリスクが混在し、ロールバックが難しくなり、レビューも不明瞭になります。 片方を済ませてから、もう片方に取り組んでください。
• 最初に継承を選ぶ — 深い階層は、関連のない関心事を結び付け、局所的な推論を難しくします。 デフォルトではコンポジションを選び、「is-a」の関係が本当に安定している場合にのみ継承してください。
• 隠れたモジュール間の結合 — 境界を越えて実装の詳細をインポートすると、見えない契約が生まれます。 明示的なパブリック API を公開し、内部実装は非公開にしてください。
• 早すぎる抽象化 — 2回目や3回目の具体的な利用が現れる前に共通インターフェースを切り出すと、元に戻すコストが高い、不適切な抽象化につながります。 重複によって本当の分割点が見えてくるまで待ってください。
• 関数型コア／命令型シェルの分離を無視する — I/O とビジネスロジックを混在させると、単体テストが困難になり、変更の影響範囲も広がります。 副作用を境界に寄せてください。

対象範囲に関する注意

• これらの推奨事項は、一般的なケースで望ましいデフォルトとして扱い、普遍的なルールとは見なさないでください。
• デフォルトがプロジェクトの制約と相反する場合や、結果を悪化させる場合は、より適した代替案を提案し、このケースでそれが優れている理由を説明してください。
• デフォルトから逸脱する場合は、トレードオフと補完策（テスト、オブザーバビリティ、移行、ロールバック）を明示してください。

呼び出しに関する通知

• このスキルを名前で呼び出す際は、その旨をユーザーに伝えてください：python-design-modularity。

参考資料

• references/design-rules.md
• references/readability-and-complexity.md
• references/module-boundaries.md
• references/functional-core-shell.md
• references/refactor-guidelines.md