python-configuration

出典の明記：wshobson/agents （MIT License、Copyright (c) 2024 Seth Hobson）に含まれる内容を基にしています。完全なライセンステキストは同じディレクトリの LICENSE.txt を参照してください。 使用、改変、再配布は、MIT ライセンスの条項に従い、著作権表示を保持する必要があります。

日本語の説明

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

---

name: python-configuration description: 環境変数と型付き設定を使った Python の設定管理です。設定の外部化、pydantic-settings のセットアップ、シークレットの管理、環境ごとの動作の実装時に使用します。

Python の設定管理

環境変数と型付き設定を使って、設定をコードから外部化します。設定を適切に管理すれば、コードを変更せずに、どの環境でも同じコードを実行できます。

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

• 新しいプロジェクトの設定システムをセットアップするとき
• ハードコードされた値から環境変数に移行するとき
• 型付き設定に pydantic-settings を導入するとき
• シークレットや機密情報を管理するとき
• 環境ごとの設定（dev/staging/prod）を作成するとき
• アプリケーションの起動時に設定を検証するとき

基本概念

1. 設定の外部化

環境固有の値（URL、シークレット、機能フラグ）はすべて、コードではなく環境変数から取得します。

2. 型付き設定

設定をコード全体に散在させず、起動時に型付きオブジェクトに解析して検証します。

3. 早期に失敗させる

アプリケーションの起動時に、必須の設定をすべて検証します。設定が不足している場合は、明確なメッセージを表示して直ちにクラッシュさせます。

4. 適切なデフォルト値

ローカル開発には妥当なデフォルト値を用意し、機密性の高い設定には明示的な値を必須とします。

クイックスタート

from pydantic_settings import BaseSettings
from pydantic import Field

class Settings(BaseSettings):
    database_url: str = Field(alias="DATABASE_URL")
    api_key: str = Field(alias="API_KEY")
    debug: bool = Field(default=False, alias="DEBUG")

settings = Settings()  # Loads from environment

基本的なパターン

パターン 1：Pydantic による型付き設定

すべての設定を読み込み、検証する一元的な設定クラスを作成します。

from pydantic_settings import BaseSettings
from pydantic import Field, PostgresDsn, ValidationError
import sys

class Settings(BaseSettings):
    """Application configuration loaded from environment variables."""

    # Database
    db_host: str = Field(alias="DB_HOST")
    db_port: int = Field(default=5432, alias="DB_PORT")
    db_name: str = Field(alias="DB_NAME")
    db_user: str = Field(alias="DB_USER")
    db_password: str = Field(alias="DB_PASSWORD")

    # Redis
    redis_url: str = Field(default="redis://localhost:6379", alias="REDIS_URL")

    # API Keys
    api_secret_key: str = Field(alias="API_SECRET_KEY")

    # Feature flags
    enable_new_feature: bool = Field(default=False, alias="ENABLE_NEW_FEATURE")

    model_config = {
        "env_file": ".env",
        "env_file_encoding": "utf-8",
    }

# Create singleton instance at module load
try:
    settings = Settings()
except ValidationError as e:
    print(f"Configuration error:\n{e}")
    sys.exit(1)

アプリケーション全体で settings をインポートします。

from myapp.config import settings

def get_database_connection():
    return connect(
        host=settings.db_host,
        port=settings.db_port,
        database=settings.db_name,
    )

パターン 2：設定不足時に早期に失敗させる

必須の設定が不足している場合は、明確なエラーを表示してアプリケーションを直ちにクラッシュさせます。

from pydantic_settings import BaseSettings
from pydantic import Field, ValidationError
import sys

class Settings(BaseSettings):
    # Required - no default means it must be set
    api_key: str = Field(alias="API_KEY")
    database_url: str = Field(alias="DATABASE_URL")

    # Optional with defaults
    log_level: str = Field(default="INFO", alias="LOG_LEVEL")

try:
    settings = Settings()
except ValidationError as e:
    print("=" * 60)
    print("CONFIGURATION ERROR")
    print("=" * 60)
    for error in e.errors():
        field = error["loc"][0]
        print(f"  - {field}: {error['msg']}")
    print("\nPlease set the required environment variables.")
    sys.exit(1)

起動時に明確なエラーを表示するほうが、リクエスト処理中に原因の分かりにくい None エラーが発生するよりも適切です。

パターン 3：ローカル開発用のデフォルト値

ローカル開発には妥当なデフォルト値を用意し、シークレットには明示的な値を必須とします。

class Settings(BaseSettings):
    # Has local default, but prod will override
    db_host: str = Field(default="localhost", alias="DB_HOST")
    db_port: int = Field(default=5432, alias="DB_PORT")

    # Always required - no default for secrets
    db_password: str = Field(alias="DB_PASSWORD")
    api_secret_key: str = Field(alias="API_SECRET_KEY")

    # Development convenience
    debug: bool = Field(default=False, alias="DEBUG")

    model_config = {"env_file": ".env"}

ローカル開発用の .env ファイルを作成します（絶対にコミットしないでください）。

# .env (add to .gitignore)
DB_PASSWORD=local_dev_password
API_SECRET_KEY=dev-secret-key
DEBUG=true

パターン 4：名前空間付き環境変数

関連する変数にプレフィックスを付けて、分かりやすくデバッグしやすくします。

# Database configuration
DB_HOST=localhost
DB_PORT=5432
DB_NAME=myapp
DB_USER=admin
DB_PASSWORD=secret

# Redis configuration
REDIS_URL=redis://localhost:6379
REDIS_MAX_CONNECTIONS=10

# Authentication
AUTH_SECRET_KEY=your-secret-key
AUTH_TOKEN_EXPIRY_SECONDS=3600
AUTH_ALGORITHM=HS256

# Feature flags
FEATURE_NEW_CHECKOUT=true
FEATURE_BETA_UI=false

これにより、env | grep DB_ がデバッグに役立ちます。

詳細な使用例とパターン

詳細なセクション（## Advanced Patterns から始まります）は references/details.md にあります。上記の概要だけでは不十分な場合は、そのファイルを参照してください。

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

1. 設定をハードコードしない - 環境固有の値はすべて環境変数から取得します
2. 型付き設定を使用する - 検証機能を備えた Pydantic-settings を使用します
3. 早期に失敗させる - 起動時に必須の設定が不足していればクラッシュさせます
4. 開発用のデフォルト値を用意する - ローカル開発を簡単にします
5. シークレットをコミットしない - .env ファイル（gitignore 対象）またはシークレットマネージャーを使用します
6. 変数に名前空間を付ける - 分かりやすいように DB_HOST、REDIS_URL を使用します
7. settings シングルトンをインポートする - コード全体で os.getenv() を呼び出さないでください
8. すべての変数を文書化する - README に必須の環境変数を記載します
9. 早期に検証する - 起動時に設定が正しいことを確認します
10. secrets_dir を使用する - コンテナーにマウントされたシークレットをサポートします

対応範囲

✅ 得意なこと

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

⚠️ 必要な情報

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

❌ 対象外

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

ワークフロー

Step 1: 要件分析

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

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

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

Step 3: 実装ガイダンス

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

Step 4: コードレビュー

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

Step 5: 最適化の提案

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

注意点

1. 過剰な設計

シンプルな場面で複雑な設計パターンを使用しないでください

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

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

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

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

4. テストカバレッジ

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

5. ドキュメントの保守

ドキュメントをコードと常に同期させてください