はじめに
ソースリポジトリ: kamae-py
Kamae Python は、サーバーサイド Python 3.12 以降向けの設計スタンスとガイド集である。uv で依存を管理し、Pydantic v2 の判別共用体と凍結状態モデルでドメインを表現し、状態変更を純粋関数で記述する。
すべてのリファレンスを通読する必要はない。今のタスクに関係するトピックだけを開けばよい。各リファレンス末尾の レビュー観点 には、そのトピックのコードレビューで確認すべき項目がまとめてある。
何を目指すか
Section titled “何を目指すか”Kamae が防ぎたいのは、次のような失敗である。
status: strと大量のオプショナルフィールドで表せてしまう無効な状態typing.castや未検証の dict アクセスによる境界の穴- 例外に頼る想定内のビジネス失敗
- ORM エンティティとドメインモデルの混同
- ログ・メトリクス・エラーへの PII 漏洩
- 状態変更とドメインイベントの非アトミックな永続化
Python では、凍結 Pydantic モデル・kind 判別子・TypeAdapter・純粋な遷移関数を組み合わせ、実用的な範囲でこれらをランタイム検証と型チェックの両面から抑える。
- 状態はバリアントで分ける — 各ビジネス状態を個別の凍結 Pydantic v2 モデルとし、
Annotated[..., Field(discriminator="kind")]で共用体にまとめる。 - 遷移は純粋関数 — 入力型が許可するソース状態、戻り値型がターゲット状態になる関数として表現する。時刻・ID・乱数は引数で注入する。
- 境界で一度パースする — API・DB・ファイル・キュー・SDK のデータは
TypeAdapterで受け、検証済みモデルからドメインへ変換する。 - 失敗は明示的に — 想定されるドメイン失敗はユースケース固有の型で表し、例外はフレームワーク境界と想定外のインフラ失敗に留める。
- PII はデフォルトでマスク — ログ・トレース・エラー・メトリクス・イベントに載せる ID は許可リストで管理する。
- 永続化はアトミックに — 状態変更とドメインイベントを同じトランザクションで保存し、冪等なリトライ経路を用意する。
- 品質ゲートを揃える — 触ったコードでは
uv run ruff format、uv run ruff check、uv run mypy、焦点を絞ったuv run pytestをクリーンに保つ。
前提となるツールチェーン
Section titled “前提となるツールチェーン”新規プロジェクトの既定は次のとおり。既存コードベースでは、まずリポジトリの慣習を確認する。
- Python 3.12.x または 3.13.x（
requires-python = ">=3.12,<3.14"） - 依存管理は uv（
pip/ Poetry / Pipenv は導入しない） - バリデーションは Pydantic v2（ジェネリックモデルを使う場合は 2.11+ を推奨）
- 静的解析は Ruff と mypy（
plugins = ["pydantic.mypy"]）
状況別の読み方
Section titled “状況別の読み方”新規ドメインを設計するとき
Section titled “新規ドメインを設計するとき”既存コードベースへ段階的に導入するとき
Section titled “既存コードベースへ段階的に導入するとき”オブザーバビリティと PII だけ見るとき
Section titled “オブザーバビリティと PII だけ見るとき”- PII と観測経路の保護
- ロギングとメトリクス
- テストのアサーションは テストデータ
インフラ・開発環境の整備
Section titled “インフラ・開発環境の整備”| 関心 | リファレンス |
|---|---|
| ユースケース配線、DI | アプリケーション配線 |
| CPU バウンド、GIL、asyncio | 並行性と非同期 |
| リトライ、サーキットブレーカー | インフラの耐障害性 |
ネイティブ、ctypes、model_construct | unsafe 境界 |
| 公開 API の docstring | 公開 API のドキュメント |
| バリデーションコスト | Pydantic のパフォーマンス |
| ローカル開発・ブートストラップ | 開発環境とセットアップ |
| CI | CI セットアップ |
新しいリファレンスに全文スニペットをコピーせず、次の定義へリンクする。
| トピック | 正規リファレンス |
|---|---|
| ハッピーパスのユースケース | 状態遷移 — ユースケースを薄く保つ |
| 永続化エラーのマッピング | エラーハンドリング — early return |
| リポジトリポート（本番） | 永続化、集約、イベント — 小さなプロトコル |
| リポジトリポート（入門） | ドメインモデリング — Protocol |
| エンドツーエンドコード | タクシー配車の例 |
| Mypy / Pydantic プラグイン設定 | ドメインモデリング — mypy 設定 |
| 品質ゲートのコマンド | 品質ゲート — 基本コマンド |
リファレンス一覧
Section titled “リファレンス一覧”- アプリケーション配線
- 公開 API のドキュメント
- 境界防御
- CI セットアップ
- 並行性と非同期
- 開発環境とセットアップ
- ドメインモデリング
- エラーハンドリング
- インフラの耐障害性
- ロギングとメトリクス
- 移行戦略
- ORM アダプター
- 永続化、集約、イベント
- PII と観測経路の保護
- Pydantic のパフォーマンス
- 品質ゲート
- 状態遷移
- テストデータ
- unsafe 境界
タクシー配車の例 では、Pydantic v2 の判別共用体、凍結状態モデル、純粋遷移、ドメインイベント、境界パースを一通り追える。