python-services

Python サービスと CLI

作業ルール

• 外部入力とレスポンスは境界で検証し、例外の原因を保持します。
• 結果がない場合と空の結果を区別します。 空のコレクションが成功を意味する場合は、空をデフォルト値にせず、レスポンスフィールドを必須にします。すべてのフィールドがデフォルト値を持つモデルでは、{} を成功として検証できてしまいます。実際の検証境界を通して、フィールドがない場合、名前が誤っている場合、明示的に空の場合、値が入力されている場合をテストします。
• 単純な逐次処理は同期的に行います。並行処理には上限を設け、キャンセルを伝播させ、タスクへの参照を保持します。
• ネットワーク呼び出しにはタイムアウトを設定し、失敗した場合と、処理のセマンティクス上リトライが許される場合にのみ再試行します。
• アトミックな書き込みとデータベース制約を使って、ジョブの冪等性を確保します。
• 公開済みの API の動作と、共有されているマイグレーション履歴を維持します。
• 運用上の疑問に合ったテレメトリーを設定し、その出力を検証します。

作業規律

• まずシンプルさを重視します。各変更を可能な限りシンプルにし、影響するコードを最小限に抑えます。
• 必要な箇所だけを変更し、無関係な変更は避けます。
• 場当たり的な回避策は使いません。修正に違和感がある場合は立ち止まり、すっきりとした解決策を実装します。
• 新しい抽象化を追加する前に、それが3か所以上で使われるか確認します。そうでなければ、インライン化します。
• 検証します。下記の「検証」セクションを参照し、完了を宣言する前に、警告ゼロですべてのチェックに合格してください。

検証

• uv run pytest が失敗ゼロで合格する
• uv run ruff check . が警告ゼロで合格する
• uv run ty check . がエラーゼロで合格する
• カバレッジ目標：80％以上（uv run pytest --cov を実行します。閲覧可能なレポートを生成するには --cov-report=html を追加します）

タスク別のリファレンス

該当する動作を実装またはレビューする前に、関連するリファレンスを読んでください。

• パッケージング、環境設定、CLI のセットアップ、または pytest の動作については、tooling-and-tests.md を参照してください。
• asyncio、バックグラウンドジョブ、再試行、プーリング、タイムアウト、またはヘルスチェックについては、concurrency-and-resilience.md を参照してください。
• API、検証、エラー、マイグレーション、ロギング、メトリクス、またはトレースについては、service-boundaries.md を参照してください。

該当するトピックに応じて、既存の専門リファレンスも参照してください。

• cli-tools.md。
• fastapi.md。