python-project-structure

出典の記載：このスキルの内容は wshobson/agents に基づいています（MIT License, Copyright (c) 2024 Seth Hobson。ライセンス全文は同じディレクトリの LICENSE.txt をご覧ください）。 使用、改変、再配布にあたっては、MIT ライセンスの条項に従い、著作権表示を保持してください。

日本語の説明

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

---

name: python-project-structure description: Python プロジェクトの構成、モジュールアーキテクチャ、パブリック API の設計。新規プロジェクトのセットアップ、モジュールの整理、all を使用したパブリックインターフェースの定義、ディレクトリ構成の計画を行う際に使用します。

Python プロジェクトの構成とモジュールアーキテクチャ

明確なモジュール境界、明示的なパブリックインターフェース、保守しやすいディレクトリ構成を備えた、適切に整理された Python プロジェクトを設計します。適切な構成により、コードを見つけやすくなり、変更の影響を予測しやすくなります。

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

• Python プロジェクトをゼロから始めるとき
• 既存のコードベースをわかりやすく再構成するとき
• __all__ を使用してモジュールのパブリック API を定義するとき
• フラットなディレクトリ構成と階層的な構成のどちらにするか決めるとき
• テストファイルの配置方法を決めるとき
• 再利用可能なライブラリパッケージを作成するとき

基本概念

1. モジュールの凝集度

一緒に変更される関連コードをまとめます。モジュールには、明確な目的を一つだけ持たせます。

2. 明示的なインターフェース

__all__ でパブリックな要素を定義します。リストにないものはすべて内部実装の詳細です。

3. フラットな階層

浅いディレクトリ構成を優先します。実際のサブドメインがある場合に限り、階層を深くします。

4. 一貫した規約

プロジェクト全体で、命名と構成のパターンを一貫して適用します。

クイックスタート

myproject/
├── src/
│   └── myproject/
│       ├── __init__.py
│       ├── services/
│       ├── models/
│       └── api/
├── tests/
├── pyproject.toml
└── README.md

基本パターン

パターン 1：1 ファイルにつき 1 つの概念

各ファイルでは、単一の概念、または密接に関連する関数群に焦点を当てます。次のような場合は、ファイルの分割を検討してください。

• 複数の無関係な役割を担っている
• 300～500 行を超える（複雑さによって異なります）
• 異なる理由で変更されるクラスが含まれている

# Good: Focused files
# user_service.py - User business logic
# user_repository.py - User data access
# user_models.py - User data structures

# Avoid: Kitchen sink files
# user.py - Contains service, repository, models, utilities...

パターン 2：__all__ による明示的なパブリック API

各モジュールのパブリックインターフェースを定義します。リストにないメンバーは内部実装の詳細です。

# mypackage/services/__init__.py
from .user_service import UserService
from .order_service import OrderService
from .exceptions import ServiceError, ValidationError

__all__ = [
    "UserService",
    "OrderService",
    "ServiceError",
    "ValidationError",
]

# Internal helpers remain private by omission
# from .internal_helpers import _validate_input  # Not exported

パターン 3：フラットなディレクトリ構成

ネストは最小限に抑えます。深い階層はインポートを冗長にし、コードの移動を難しくします。

# Preferred: Flat structure
project/
├── api/
│   ├── routes.py
│   └── middleware.py
├── services/
│   ├── user_service.py
│   └── order_service.py
├── models/
│   ├── user.py
│   └── order.py
└── utils/
    └── validation.py

# Avoid: Deep nesting
project/core/internal/services/impl/user/

分離が必要な実際のサブドメインがある場合に限り、サブパッケージを追加します。

パターン 4：テストファイルの構成

いずれかの方法を選び、プロジェクト全体で一貫して適用します。

方法 A：テストをコードと同じ場所に配置

src/
├── user_service.py
├── test_user_service.py
├── order_service.py
└── test_order_service.py

利点：テスト対象のコードの隣にテストが配置されるため、カバレッジの不足箇所を簡単に確認できます。

方法 B：テスト用の並列ディレクトリ

src/
├── services/
│   ├── user_service.py
│   └── order_service.py
tests/
├── services/
│   ├── test_user_service.py
│   └── test_order_service.py

利点：本番コードとテストコードを明確に分離できます。大規模なプロジェクトで標準的な方法です。

高度なパターン

パターン 5：パッケージの初期化

__init__.py を使用して、パッケージの利用者にわかりやすいパブリックインターフェースを提供します。

# mypackage/__init__.py
"""MyPackage - A library for doing useful things."""

from .core import MainClass, HelperClass
from .exceptions import PackageError, ConfigError
from .config import Settings

__all__ = [
    "MainClass",
    "HelperClass",
    "PackageError",
    "ConfigError",
    "Settings",
]

__version__ = "1.0.0"

これにより、利用者はパッケージから直接インポートできます。

from mypackage import MainClass, Settings

パターン 6：レイヤードアーキテクチャ

関心事を明確に分離するため、アーキテクチャのレイヤーごとにコードを整理します。

myapp/
├── api/           # HTTP handlers, request/response
│   ├── routes/
│   └── middleware/
├── services/      # Business logic
├── repositories/  # Data access
├── models/        # Domain entities
├── schemas/       # API schemas (Pydantic)
└── config/        # Configuration

各レイヤーは下位のレイヤーにのみ依存し、上位のレイヤーには依存しないようにします。

パターン 7：ドメイン駆動型の構成

複雑なアプリケーションでは、技術的なレイヤーではなく、ビジネスドメインごとに構成します。

ecommerce/
├── users/
│   ├── models.py
│   ├── services.py
│   ├── repository.py
│   └── api.py
├── orders/
│   ├── models.py
│   ├── services.py
│   ├── repository.py
│   └── api.py
└── shared/
    ├── database.py
    └── exceptions.py

ファイルとモジュールの命名

規約

• ファイル名とモジュール名にはすべて snake_case を使用します：user_repository.py
• 意味がわかりにくくなる略語は避けます：usr_repo.py ではなく user_repository.py
• クラス名をファイル名に合わせます：user_service.py に UserService

インポートのスタイル

明確さと信頼性を高めるため、絶対インポートを使用します。

# Preferred: Absolute imports
from myproject.services import UserService
from myproject.models import User

# Avoid: Relative imports
from ..services import UserService
from . import models

相対インポートは、モジュールを移動したり再構成したりしたときに機能しなくなる可能性があります。

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

1. ファイルの責務を絞る - 1つのファイルに1つの概念を記述し、複雑さに応じて300～500行を目安に分割を検討します
2. __all__を明示的に定義する - 公開インターフェースを明確にします
3. フラットな構造を優先する - 実際のサブドメインがある場合にのみ、階層を追加します
4. 絶対インポートを使用する - より信頼性が高く、分かりやすくなります
5. 一貫性を保つ - プロジェクト全体でパターンを統一して適用します
6. 名前を内容に合わせる - ファイル名から用途が分かるようにします
7. 関心事を分離する - レイヤーを明確に分け、依存関係が一方向に流れるようにします
8. 構造を文書化する - 構成を説明するREADMEを含めます

対応範囲

✅ 得意なこと

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

⚠️ 必要な情報

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

❌ 対応範囲外

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

ワークフロー

Step 1: 要件分析

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

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

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

Step 3: 実装ガイダンス

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

Step 4: コードレビュー

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

Step 5: 最適化の提案

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

注意点

1. 過剰な設計

シンプルな場面で複雑なデザインパターンを使わないようにします

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

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

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

セキュリティとデータ保護を常に考慮します

4. テストカバレッジ

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

5. ドキュメントの保守

ドキュメントをコードと同期させて更新し続けます