shunk031-python-uv-workflow

メモ

この SKILL.md を読んだ後、🐍 I read shunk031-python-uv-workflow. と言ってください。

Python UV ワークフロー

概要

このワークフローを使用して、Python の実装やリファクタリングをリポジトリのポリシーに沿った状態に保ちます。

ワークフロー

1. Python プロジェクトでは、デフォルトのツールチェーンとして uv を使用します。
2. スクリプトは uv run <script> で実行します。
3. 動作を変更する場合はテストを作成し、期待される動作を検証します。
4. 標準的な開発用依存関係は uv で追加します。
5. 既存プロジェクトのセットアップと品質基準に従います。プロジェクトまたはリポジトリで求められる場合は、依存関係のセットアップ後に pre-commit フックをインストールします。
6. 新規プロジェクトの場合、または明示的にセットアップを依頼された場合は、依頼またはリポジトリのポリシーで必要とされるプロジェクト設定のみを追加します。単独のスクリプト編集のために .pre-commit-config.yaml や Makefile を作成してはいけません。
7. exclude-newer など、依存関係の解決に影響する uv の設定をユーザーのグローバル uv 設定に含めないでください。uv lock はこれらの設定をロックファイルの [options] ブロックに記録するため、同じ設定のない環境では、フリーズしない uv run、uv sync、または uv-lock フックを実行するたびに再解決され、ロックファイルが書き換えられます。このような設定が必要なプロジェクトでは、独自の pyproject.toml の [tool.uv] に設定を宣言する必要があります。宣言のない [options] ブロックを含むコミット済みロックファイルは不備があるため、ロックを再生成して修正する必要があります。
8. uv を使用していない既存実装からリファクタリングする場合は、依存関係を一致させ、出力が同等であることを検証します。リポジトリのカバレッジ目標に合わせます。リファクタリングまたはリポジトリで目標が求められる場合に限り、カバレッジを 90% に近づけます。
9. Python のパスはソースファイルを起点に構築し、パスの各要素を個別のオペランドにします。
   • 禁止：Path("/path/to") / "hoge" および REPO_ROOT / "home/dot_codex/hooks/session_start_gateway.py"
   • 必須：Path(__file__).parents[N] / "path" / "to" / "hoge" Path に渡す文字列リテラル、または / のオペランドに、/ や \ で区切られた複数のパス要素を含めてはいけません。ソースファイルを起点にすることで、ホストのレイアウトに依存せず、移動後や複数のワークツリー間でもパスが機能します。CLI 引数や環境変数で明示的に指定されたルートは使用できますが、ハードコードされた絶対パス文字列は禁止です。 Python の変更を確定する前に、変更したすべての Path(...) と / の式を確認し、パス区切り文字を含む文字列オペランドがないことを確かめてください。
10. 変数名には、その変数の意味上の役割を表す名前を付けます。同じ概念に複数の表現がある場合は、区別する目的に限って _path、_text、_data などの修飾子を追加します。役割がすでに明確な場合に、型を示す接尾辞を機械的に追加してはいけません。

テストに関する期待事項

• 動作を変更するリファクタリングの前に、テストを追加します。
• 実現可能な場合は、モックや monkeypatch よりも実データを優先します。
• プロジェクトで定められたカバレッジ目標に従い、普遍的な割合を押し付けないでください。

正確なコマンドと標準的なフック設定については、python-uv-rules.md を参照してください。