Python ツールチェーン
適用義務
Python と TypeScript は、ライブラリと AI エージェントのエコシステムが最も充実しているため、AI 支援開発のデフォルト言語とする。
言語の優先順位:
- TypeScript だけの構成で足りる場合はそれを優先する(TypeScript ツールチェーンを参照)。
- Python バックエンドは、Python を使う明確な利点がある場合にのみ導入する(基準は下記)。
- Go と Rust は、性能が重要な処理やシステム領域に限って使う。導入には明確な理由とユーザーの承認が必要であり、プロジェクトの ADR に記録する。Go と Rust を参照。
特に次の要件がある場合は、Python バックエンドの導入が適している。
- バックエンドのロジックが十分に複雑である
- Python 固有のライブラリが意味のある価値を提供する
- 実装の一部を別チームが担当する
- データサイエンスエンジニアがワークフローの一部を変更する必要がある
- エージェントやデータ処理のロジックを、ほかの部分と分けて担当者に任せる必要がある
たとえば、エージェントのワークフローの一部をデータサイエンスチームが保守することが想定される場合、Python サービスは適切な選択になり得る。
標準の API フレームワーク、検証、サーバースタックについては Python API スタック を参照。
バージョン方針
既定は Python 3.12 とする。mise はインタープリターと uv 本体を提供し、環境と依存関係(uv.lock など)は uv が管理する。ML エコシステムとモデルの訓練データが追いつくまで、新しい CPython 系列を採用しない。エコシステムのデフォルトが変わった時点で再検討する。
モデルは学習データに基づいてコードを生成する。そのため、成熟して学習データにも十分含まれるバージョンほど、AI 支援開発でエラーが起きにくい。この原則は 中核となるエンジニアリング原則 に定められている。
Python のバージョンは、プロジェクトの mise 設定に固定する。
どの環境でも同じ依存関係のバージョンが解決されるよう、uv.lock をコミットする。
uv
Python の環境と依存関係は uv で管理し、別の環境管理・パッケージ管理ツールを併用しない。
標準ワークフロー:
uv init——プロジェクトを開始する。uv add <package>——ランタイムの依存関係を追加し、ロックファイルを更新する。uv add --dev <package>——リントやテストツールなど、開発専用の依存関係を追加する。uv remove <package>——依存関係を削除する。uv lock --upgrade——ロックされた依存関係のバージョンを更新する。uv sync——ロックされた環境をインストールする。uv run <command>——プロジェクト環境内でコマンドを実行する。
素の python や pip を実行してはならない。どちらもプロジェクト環境とロックファイルを経由しないためである。代わりに uv run python と uv add / uv sync を使う。
依存関係は pyproject.toml に定義する。uv.lock は生成物であり、手で編集してはならない。
単独のスクリプトでは、PEP 723 のインラインスクリプトメタデータで依存関係を宣言し、uv run script.py で実行する。
# /// script
# requires-python = ">=3.12"
# dependencies = ["httpx"]
# ///
採用しない代替案
次のツールは使わない。
- Pipenv
- Poetry
ruff
リント(ruff check)とフォーマット(ruff format)の両方に ruff を使い、品質ゲートに組み込んで pyproject.toml で設定する。ベースラインのルール:
[tool.ruff.lint]
select = ["E", "F", "I", "B", "UP", "SIM"]
E と F は構文レベルと正しさの問題を検出し、I はインポートを整列させ、B は典型的なバグパターンを検出し、UP は構文を最新化し、SIM は単純化できるコードを検出する。必要に応じてプロジェクト単位でこのベースラインを拡張する。黙って縮小してはならない。
採用しない代替案
次のツールは使わない。
- flake8
- black
言語の利用ルール
- すべての公開関数に型ヒントを付け、引数と戻り値の両方を含める。
- ファイルシステムのパスには
os.pathではなくpathlibを使う。 - 文字列の組み立てには f-string を使う。新しいコードで
%フォーマットやstr.formatを使わない。 - 可変オブジェクトをデフォルト引数にしてはならない(
def f(items=[]))。デフォルトにはNoneを使い、コレクションは関数内で生成する。 - ファイル、ソケット、セッション、クライアントなどのリソースは、コンテキストマネージャー(
with)で管理する。 - 例外を再送出するときは原因を保持し、
raise NewError(...) from errとする。 - 内部データ構造には
dataclassesを使う。Pydantic は検証境界でのみ使う。詳しくは Python API スタック を参照。
プロジェクトレイアウト
- パッケージは
src/の下(src/<package>/)に置き、tests/はプロジェクトルートでsrc/と並べる。 - この構成により、パッケージをインストールせずに誤ってインポートすることを防ぐ。