python-design-patterns

出典に関する声明：wshobson/agents を原典としています。 （MIT License、Copyright (c) 2024 Seth Hobson。ライセンス全文は同じディレクトリの LICENSE.txt を参照してください。） 使用、変更、再配布は、当該 MIT ライセンスの条件に従い、著作権表示を保持する必要があります。

日本語の説明

このスキルでは、フルスタック開発に関連するベストプラクティスとパターンを案内します。

---

name: python-design-patterns description: KISS、関心の分離、単一責任、継承よりコンポジションを含む、Python のデザインパターンです。新しいサービスやコンポーネントを一から設計し、責務をどのように分割するかを決める場合、大きくなりすぎた神クラスやモノリシックな関数をリファクタリングする場合、新しい抽象化を追加するか重複を許容するか判断する場合、密結合や内部型の漏洩といった構造上の問題についてプルリクエストを評価する場合、新しいクラス階層で継承とコンポジションのどちらを採用するか選ぶ場合、または I/O とビジネスロジックが絡み合ってコードベースのテストが難しくなっている場合に、このスキルを使用します。

Python のデザインパターン

基本的な設計原則を使って、保守しやすい Python コードを書きます。これらのパターンは、理解、テスト、変更が容易なシステムの構築に役立ちます。

このスキルを使用する場面

• 新しいコンポーネントやサービスを設計する
• 複雑に絡み合ったコードをリファクタリングする
• 抽象化を作成するかどうかを判断する
• 継承とコンポジションのどちらを使うか選ぶ
• コードの複雑さや結合度を評価する
• モジュール型アーキテクチャを計画する

基本概念

1. KISS（シンプルに保つ）

機能する最もシンプルな解決策を選びます。複雑さには、具体的な要件による根拠が必要です。

2. 単一責任（SRP）

各単位には、変更する理由が1つだけあるべきです。関心事を、役割に特化したコンポーネントに分けます。

3. 継承よりコンポジション

クラスを拡張するのではなく、オブジェクトを組み合わせて動作を構築します。

4. 3回の法則

抽象化する前に、3つの事例がそろうまで待ちます。早まって抽象化するより、重複を残すほうが適切な場合がよくあります。

クイックスタート

# Simple beats clever
# Instead of a factory/registry pattern:
FORMATTERS = {"json": JsonFormatter, "csv": CsvFormatter}

def get_formatter(name: str) -> Formatter:
    return FORMATTERS[name]()

詳細なパターンと実例

パターンの詳しいドキュメントは references/details.md にあります。上記のナビゲーションだけでは不十分な場合は、このファイルを読んでください。

ベストプラクティスのまとめ

1. シンプルに保つ - 機能する最もシンプルな解決策を選びます
2. 単一責任 - 各単位には、変更する理由が1つだけあります
3. 関心事を分離する - 目的が明確な異なるレイヤーに分けます
4. 継承せず、コンポーズする - オブジェクトを組み合わせて柔軟性を高めます
5. 3回の法則 - 抽象化は急がずに待ちます
6. 関数を小さく保つ - 目的を1つに絞り、20～50行を目安にします（複雑さによって異なります）
7. 依存関係を注入する - テストしやすくするため、コンストラクターインジェクションを使います
8. 抽象化する前に削除する - 不要なコードを削除してから、パターンの適用を検討します
9. 各レイヤーをテストする - 関心事ごとに分離してテストします
10. 巧妙さより明示性 - 洗練されたコードより、読みやすいコードを優先します

トラブルシューティング

クラスが大きくなり、複数の責務を担っているように見えますが、分割するのは適切でないように感じます。 「変更理由」のテストを適用してください。このクラスの編集が必要になる可能性のある変更をすべて列挙します。異なる領域の項目（例：HTTP の解析、ビジネスルール、フォーマット）が含まれている場合は、分割してください。すべての変更が同じ領域の関心事に起因するなら、そのクラスの規模は適切かもしれません。

すべての依存関係をコンストラクター経由で注入すると、パラメーターが7個以上あるコンストラクターになってしまいます。 これは依存性注入の問題ではなく、1つのクラスに責務が多すぎる兆候です。まずクラスを小さな単位に分割すれば、それぞれのコンストラクターも自然と小さくなります。

コンポジションによって、追跡しにくい深くネストされたラッパーオブジェクトが生まれています。 コンポジションは浅く保ってください（2～3階層）。ラッピングが唯一の手段である場合は、デコレーターオブジェクトの連鎖よりも、Protocol ベースのアプローチやシンプルな関数合成のほうがすっきりしないか検討してください。

三度目のルールではまだ抽象化しないことになっていますが、重複したコードの片方だけを更新するとバグが発生します。 危険な形で差異が生じている重複コードは、より早く抽象化すべきです。三度目のルールは経験則であり、絶対的な決まりではありません。すでに不適切な形で差異が生じているなら、すぐに抽出し、共有される動作を検証するテストを追加してください。

サービス層が API 層からインポートしており、依存関係の方向が崩れています。 これはレイヤリング違反です。サービス層はハンドラーからインポートしてはいけません。共有する型／モデルのレイヤーを導入し、両者がそこからインポートするようにして、依存関係の矢印が下向き（API → Service → Repository）になるようにしてください。

関連スキル

• python-testing-patterns — ここで確立した依存性注入の構成を使い、各レイヤーを個別にテストします。インストール：npx skills add full-stack-skills/python-skills --skill python-testing-patterns。
• python-project-setup — 最初からレイヤーの境界を適用できるように、プロジェクト構造とツールを設定します。インストール：npx skills add full-stack-skills/python-skills --skill python-project-setup。

対応範囲

✅ 得意なこと

• フルスタック開発に関するベストプラクティス
• コードアーキテクチャの設計ガイダンス
• パフォーマンス最適化の提案

⚠️ 情報が必要なこと

• 具体的なプロジェクトのコンテキスト
• 技術スタックの情報

❌ 対応範囲外

• 技術分野以外のビジネス上の意思決定
• 具体的なコードの実装（ガイダンスのみを提供）

ワークフロー

Step 1: 要件分析

プロジェクトの要件と技術的な制約を理解します

Step 2: アーキテクチャ設計

システムアーキテクチャとコンポーネントの分割を設計します

Step 3: 実装ガイダンス

具体的な実装の提案とコードパターンを提供します

Step 4: コードレビュー

コードの品質とベストプラクティスへの準拠状況をレビューします

Step 5: 最適化の提案

パフォーマンスの最適化と改善の提案を行います

注意点

1. 過剰設計

単純なケースで複雑なデザインパターンを使わないようにしてください

2. パフォーマンスの軽視

特に本番環境では、パフォーマンスの最適化を軽視しないでください

3. セキュリティへの配慮

常にセキュリティとデータ保護を考慮してください

4. テストカバレッジ

特に境界条件について、十分なテストカバレッジを確保してください

5. ドキュメントの保守

ドキュメントをコードに合わせて常に更新してください