python-conventions

Python の規約

Python の作業が主な作業項目である場合は、これらの規約を適用してください。

ディスパッチ

$ARGUMENTS	アクション
Active（Python の作業が主な作業項目の場合に自動呼び出し）	以下のオペレーター契約を適用します
Empty	規約の概要と振り分けのガイダンスを表示します
check	ツールの準拠状況のみを確認します

参照ファイル一覧

ファイル	用途
references/tooling-contract.md	インストール、実行、リント、型チェック、テストの各フローで必須となるコマンド順序
references/redirection-boundaries.md	Python の規約をシェル、JS/TS、またはドメイン固有のスキルに委ねるべき場合
references/exceptions.md	レガシー環境や企業環境で規約を適用しない場合
references/library-preferences.md	新しい Python の作業で推奨するライブラリのガイダンス
references/performance-tips.md	プロファイリングツール、最適化パターンのクイックリファレンス
references/testing-patterns.md	フィクスチャのスコープ、マーカー、conftest のひな形

オペレーター契約

Active

1. このスキルは、Python ファイル、Python ツール、または pyproject.toml がタスクの主な対象である場合にのみ適用します。
2. Python とシェル、JS/TS、またはその他の主要な作業項目が混在する場合は、references/redirection-boundaries.md を読みます。
3. パッケージ管理、コマンド実行、リント、型チェック、テストについて、references/tooling-contract.md の必須要件を適用します。
4. レガシー環境や制約のある環境に合わせた例外を推奨する前に、references/exceptions.md を確認します。
5. 新しい Python の作業でライブラリを選ぶ場合に限り、references/library-preferences.md を読みます。

Empty / Help

1. 必須要件を要約します：uv、uv run、uv add、ty、ruff、pytest、pyproject.toml。
2. 必須要件と推奨設定の違いを示します。
3. ツール、例外、ライブラリ、テスト、パフォーマンス、複数言語が混在する場合の振り分けについて、該当する参照ファイルを明示します。

check

1. ツールの準拠状況のみを確認し、ユーザーから依頼がない限り、実装に関する助言にまで範囲を広げません。
2. プロジェクトが uv、uv run、ty、ruff、pytest、pyproject.toml を想定どおりに使用しているかを報告します。
3. レガシー環境や例外経路からの逸脱を指摘し、その理由が references/exceptions.md に合致することを求めます。
4. リポジトリで必須のツールを mypy、pip install、または単独の python に置き換える推奨は却下します。

必須要件

• パッケージマネージャー：すべての Python パッケージ操作に uv を使用します
• 依存関係：用途に応じて uv add、uv add --group dev、uv remove、uv lock --upgrade-package <pkg> を使用します
• 再現可能なインストール：既存のロックファイルを使ったワークフローを検証する場合は uv sync --locked を使用します
• プロジェクト設定：Python プロジェクトの設定は pyproject.toml にまとめます
• 型チェック：mypy ではなく uv run ty check を使用します
• リント：uv run ruff check と uv run ruff format を使用します
• テスト：uv run pytest を使用します
• タスク実行：Python コマンドの実行には uv run <command> を使用します

仮想環境

• 仮想環境の管理は uv に任せます
• .venv ディレクトリを手動で作成したり、有効化したりしないでください
• プロジェクト環境内で実行するには uv run を使用します

推奨設定

推奨ライブラリ設定は、新しい Python の作業を始める際に、より優先度の高い既存の制約がない場合にのみ適用されます。既存の技術スタックを別のものに置き換えることを推奨する前に、references/library-preferences.md を読んでください。

プロジェクト構成

• プロジェクトのすべてのメタデータと依存関係に pyproject.toml を使用します
• プロジェクト名と一致するパッケージディレクトリにソースコードを配置します
• モノレポのサブパッケージには uv ワークスペースメンバーを使用します
• Python の作業を完了とする前に、references/tooling-contract.md に記載された必須のリント、フォーマット、型チェック、テストの一連の手順を実行します

パフォーマンスに関する規約

1. 最適化する前にプロファイリングを行います。
2. 手軽な Python のプロファイリングと最適化のパターンについては、references/performance-tips.md を使用します。
3. 広範なプロファイリング、回帰分析、またはパフォーマンス調査は performance-profiler に振り分けます。

テストに関する規約

1. Python のテストには pytest を使用し、プロジェクトのテストに関するデフォルト設定を pyproject.toml で行います。
2. フィクスチャ、マーカー、tmp_path、monkeypatch、パラメータ化、カバレッジポリシーについては、references/testing-patterns.md を使用します。
3. テスト戦略、テストスイートの設計、フィクスチャのアーキテクチャ、または複数言語にまたがるテスト計画は test-architect に振り分けます。

検証要件

変更を完了と宣言する前に、このスキルのディレクトリから実行します。

python scripts/check.py
git diff --check

完了条件：

1. scripts/check.py が終了コード 0 で終了すること。
2. git diff --check が終了コード 0 で終了すること。
3. このスキルのディレクトリ内に、ポータブル CLI に関する違反が残っていないこと。

スキル定義、公開向けの説明、リファレンスファイル、または評価の動作を変更した後は、利用可能であれば docs-steward を呼び出します。

重要なルール

1. タスクが明示的に承認済みの例外経路に該当しない場合、pip install、uv pip install、または裸の python を使用する Python のセットアップ方法は認めません。
2. references/exceptions.md にレガシー環境または制約のある環境での逸脱を正当化する記載がない限り、実行時依存関係には uv add を、開発専用の依存関係には uv add --group dev を必須とします。
3. 型チェックには uv run ty check を必須とします。このリポジトリのデフォルトの方法として、mypy や裸の ty check を推奨しないでください。
4. 例外が文書化されていない限り、Python の変更におけるデフォルトの完了ゲートとして、uv run ruff check、uv run ruff format、uv run ty check、uv run pytest を適用します。
5. uv.lock を手作業で編集しないでください。uv lock、uv sync、または依存関係のコマンドを使用します。
6. ガイドラインで推奨されるライブラリを、すでに確立しているローカルのスタックに必須の代替として提示しないでください。
7. レガシーなツールチェーン、別の環境マネージャー、または別のライブラリの使用経路を承認する前に、references/exceptions.md を読みます。
8. 混在言語の作業や Python が主ではない作業は、このスキルをタスク全体に無理に適用せず、references/redirection-boundaries.md を通じて適切な経路に振り分けます。

標準用語（以下のとおり使用します）：

• uv -- 必須のパッケージマネージャー兼タスクランナー
• ty -- 必須の型チェッカー（mypy ではありません）
• uv run ty check -- 必須の型チェックコマンド
• ruff -- 必須のリンター兼フォーマッター
• pyproject.toml -- プロジェクト設定の唯一の情報源
• uv run -- すべての Python コマンド実行に付けるプレフィックス
• uv sync --locked -- ロックファイルを使うワークフローにおける、再現可能なインストール確認のデフォルト

規模に応じた方針

• Python 以外が主のタスクに付随する Python ファイル：Python が管理する範囲に関わるハード要件のみを適用し、混在ワークフローに関する質問は references/redirection-boundaries.md を通じて適切な経路に振り分けます。
• Python が主となる機能開発またはリファクタリング：ツール、テスト、および関連する場合のガイドライン上の推奨事項を含む、運用要件の全体を適用します。
• リポジトリ全体に関わる Python ツールの変更または移行：check、references/tooling-contract.md、および references/exceptions.md を使用し、ハード違反と文書化済みの移行経路を区別します。

段階的な情報開示

• デフォルトですべてのリファレンスを読み込まないでください。
• コマンドの実行順序に関する質問では、まず references/tooling-contract.md を読みます。
• シェル、JS/TS、CI、またはフレームワーク固有の作業が依頼に混在している場合は、references/redirection-boundaries.md を読みます。
• タスクでレガシー環境、企業環境、または制約のある環境に関する例外が必要と思われる場合に限り、references/exceptions.md を読みます。
• 新しい Python の作業でライブラリを選ぶ場合に限り、references/library-preferences.md を読みます。
• パフォーマンスまたはテストのリファレンスは、現在のタスクが実際にそれらの領域に関わる場合に限り読みます。

対象範囲

対象： Python のツール使用規約、コマンドの選択、依存関係管理のルール、型チェック・リンティング・テストの基準、および例外を考慮したリポジトリのガイダンスです。

対象外： JS/TS の規約、シェルの規約、CI パイプラインの設計、プロファイリング調査、テストアーキテクチャ、フレームワークやドメインに固有の実装戦略です。