# AGENTS.md — beautyspot 開発ガイドライン

このファイルは、Codex（およびその他のAIアシスタント）が `beautyspot` プロジェクトにおいて適切に振る舞うためのコンテキストとコーディングルールを定義します。

## プロジェクトの目的と概要
`beautyspot` は、関数の実行結果を透過的にキャッシュし、複雑なデータパイプラインやML実験の再実行を高速化するPython OSSライブラリです。

- **言語・ツール**: Python >=3.12, `uv` (パッケージ管理), `pytest` (テスト), `mkdocs` (ドキュメント)
- **公開エントリーポイント**: `bs.Spot(...)` (DIによってすべてのコンポーネントを結びつけるファクトリ関数)

## 開発・実装の基本ルール

コードの追加や修正を行う際は、以下の原則に必ず従ってください。

### 1. 依存性の注入 (DI) の徹底
すべてのコンポーネントは注入され、ハードコードしてはいけません。デフォルト設定の結びつけは `__init__.py:Spot()` でのみ行います。`core.Spot.__init__` をユーザーコードで直接インスタンス化せず、常に `bs.Spot(...)` を使用するよう案内・実装してください。

### 2. 非同期・ノンブロッキング永続化
- キャッシュの保存はデフォルトで呼び出し元のスレッドで行われます (`wait=True`)。
- バックグラウンド保存 (`wait=False`) の場合、`ThreadPoolExecutor` に処理を委譲し、`with spot:` ブロックの終了時にフラッシュします。バックグラウンド保存の失敗はERRORレベルでログ出力し、例外は送出しません。

### 3. キャッシュキーの安定性
- キャッシュキーの生成には `KeyGen` を使用し、非決定的な引数（例: `verbose` フラグなど）は除外する (`keygen=KeyGen.ignore("verbose")`) ことを推奨してください。
- 辞書の順序はハッシュ化の前にソートして正規化します。

### 4. Docstringと型アノテーション
- 新しい関数やクラスを追加する際は、必ず明確なDocstringを記述し、設計の意図や非自明な挙動（なぜその実装になったのか）を記録してください。
- `pyright` による厳密な型チェックに合格するよう、正確な型アノテーションを付与してください。

## テストのガイドライン
テストを追加する際は、適切なレイヤーを選択してください。
- **`tests/unit/`**: I/Oを伴わない純粋なロジック
- **`tests/integration/`**: `Spot` のオプション、DB操作、ストレージバックエンドの統合
- **`tests/scenarios/`**: ユーザーのワークフロー、エッジケース、セキュリティ
- DBの検証には、`tests/conftest.py` で定義されている `inspect_db` フィクスチャを積極的に使用してください。

## アーキテクチャの概要
提案を行う際は、以下の依存関係を念頭に置いてください。
`Spot` -> `TaskDBBase` (メタデータ), `SerializerProtocol`, `BlobStorageBase`, `StoragePolicyProtocol`, `LimiterProtocol`, `LifecyclePolicy`, `ThreadPoolExecutor`.

## AIの振る舞いについて
1. **代替案の提示**: 実装を提案する際は、複数のアプローチとそのトレードオフ（パフォーマンス、メンテナンス性など）を提示してください。
2. **ADRの推奨**: アーキテクチャに関わる重要な変更（新しいバックエンドの追加、デフォルト挙動の変更など）を伴う場合は、Architecture Decision Record (ADR) の作成を提案してください。
3. **日本語でのコミュニケーション**: ユーザーの質問には、専門的かつ協力的、論理的なトーンの日本語で回答してください。
