| name | bp-python |
| description | Alt の Python 3.14+ 規約を適用する。型ヒント必須と Pyrefly、具体例外と原因チェーン、Pydantic/frozen dataclass の境界保護、asyncio と同期推論の分離、spawn プロセスプール、起動時 fail-closed を扱う。Python のコードを書く・直す・レビューするときに使う。ユーザが「Python」や規約名に触れなくても、Python サービス（news-creator, tag-generator, metrics, recap-subworker, recap-evaluator, acolyte-orchestrator）の実装・修正に入るなら使う。 |
| paths | ["**/*.py"] |
Python Best Practices
以下はタスク全体を通じて有効な規約であり、一度読んで終わる手順ではない。Python コードを書くたびに適用する。
詳細な根拠とコード例が必要になった時点で docs/best_practices/python.md の該当セクションだけを Read する
（全 13 セクション・444 行あるため全文読み込みはしない）。
重要原則
- 型ヒント必須: 公開関数・メソッドは完全アノテーション。
Any は境界最小限。uv run pyrefly check . 通過必須（mypy は ADR-000530 により非推奨）
- 例外は具体的に: 裸の
except: / except Exception: 禁止。raise DomainError("action") from err で原因チェーン保持
- Clean Architecture: Handler → Usecase → Port → Gateway → Driver（news-creator 準拠）。層越境・逆向き依存禁止
- Ruff + Pyrefly が一次ソース: フォーマット・静的検査はツールで自動化。Pyrefly ≥ 0.42.0 を採用（ADR-000530）。推奨ルール集合
E,W,F,B,UP,SIM,N,I,ANN,S,PTH,C4,BLE,ASYNC,TRY,RUF,PL。手動スタイル議論禁止
- Pydantic / frozen dataclass で境界保護: API 入出力は Pydantic v2、内部値オブジェクトは
@dataclass(frozen=True, slots=True)。生 dict を引き回さない
- context manager で資源管理:
with / async with で確実に close。async 並行は asyncio.TaskGroup / async with。裸 open() 禁止
- pytest + TDD: RED → GREEN → REFACTOR。FastAPI のモジュールレベル
APIRouter() はテスト分離を壊す → importlib.reload() で毎テスト再構築
- 同期推論をイベントループで実行しない:
async def 内の同期 ML 推論・psutil はループ全停止。anyio.to_thread.run_sync + CapacityLimiter、持続的 CPU-bound は process pool / 専用 worker
- 無言フォールバック禁止: import 失敗・env 未設定で anonymous / no-op に差し替えない。起動時 raise（→
.claude/rules/di-wiring.md）
- Python バージョン全経路固定:
.python-version + CI parity。3.14 構文は 3.11 ツールチェーンで解析不能
- async リソースは多層防御で回収: async generator の
finally は実行保証なし（PEP 525）→ contextlib.aclosing で包む。セマフォは slot_id / home_pool の所有権追跡 + release パス invariant + CancelledError ハンドラで取得済みリソースを棚卸し（ADR-000243, ADR-000606, ADR-000612）
- プロセスプールは spawn + メモリ見積り: CUDA は fork 子プロセスで再初期化不能 → spawn context 必須。spawn プールは「ワーカー数 × モデルサイズ」でメモリ線形増、子の OOM kill は親
.get() の無症状ハング → timeout 必須（ADR-000048, ADR-000550）
- 起動時 fail-closed / lazy init 禁止: 必須 artefact は Pydantic
@model_validator で起動時検証して即 exit。存在チェックは Path.exists() でなく is_file()（空ディレクトリで素通りする）（ADR-000825, PM-2026-036）
参照
完全なベストプラクティスは docs/best_practices/python.md を参照。
セクション: Project Structure, Type Hints & Static Analysis, Error Handling, Clean Architecture, Pydantic & Dataclass, Async Patterns, Resource Management, Logging, Testing, Tooling, Security, ML Runtime & Process Pools
