Project directives for jam006097/kids-playground-ai-api

🎯 作業前（Before Start）

必ず GitHub リポジトリ jam006097/kidsPlayGround に Issue を新規登録。
Issueには、目的・完了条件・範囲を明記してください。

🧪 開発方針

twadaさんスタイルの TDD をベースに進行。
PDCA サイクル（Plan, Do, Check, Act）を繰り返しながら作業。
コードは保守性・可読性を最優先に設計し、SOLID原則（単一責任・オープン/クローズ・リスコフ・インターフェース分離・依存性逆転）を意識して実装すること。
クラスや関数は、責務ごとに適切に分離し、再利用・テストしやすい構造とすること。
クラス設計では「1クラス1責務」を基本とし、処理の流れや依存関係が見通しやすいようにする。
必要に応じてデザインパターン（Strategy, Factoryなど）を活用し、柔軟で拡張可能な構成を心がける。

🧪 TDDスタイルの基本ルール

Red → Green → Refactor の順に進める
最小のテスト → 最小の実装 → リファクタリング
1ステップごとにコミット、最小粒度を保つ
テストは、和田卓人（@t_wada）氏の思想を参考に、「動く仕様書」として機能させることを目指す

テストコード設計の具体的な指針

テストの対象：振る舞いをテストし、実装の詳細はテストしない
- テストの主な目的は、機能の振る舞い（Behavior）が期待通りであることを保証することです。「何ができるか」をテストし、「どのように実装されているか」はテストしません。
- 関数の内部ロジックやUIの見た目といった実装の詳細（Implementation Details）に依存するテストは、リファクタリングで壊れやすくなるため避けます。
- 避けるべきテストの例:
  - 特定のHTML構造やCSSクラス名に依存する画面（UI）テスト。
  - 関数の内部で、別の特定の関数が呼ばれたことだけを確認するような、過度に実装に踏み込んだテスト。
- 推奨されるテスト:
  - 「ユーザーIDを渡すと、ユーザー名が返ってくる」
  - 「無効な値を入力すると、エラーがスローされる」
  - 上記のように、入力（Input）と、観測可能な結果（Output/State Change）に注目した振る舞いのテストを記述します。
命名と構造：テストの意図を日本語で明確にする
- 構造化: describeを使い、テスト対象の関数やクラスごとにテストをグループ化します。
- 命名（日本語での記述）: テストケース名（test関数の第一引数）は必ず日本語で、「〜という状況で、〜という振る舞いをすべき」というように、具体的なシナリオと期待される結果を記述します。
  - 良い例: test('クッキーが存在しない場合、nullを返すこと')
  - 悪い例: test('getCookie test 2')
- このルールを徹底することで、日本語話者の開発者にとって、テストコードがそのまま日本語の仕様書として機能します。
テストの粒度：1テスト1検証の原則
- 1つのテストケースでは、1つの具体的な振る舞いのみを検証します。
- これにより、テストが失敗した際に、どの振る舞いに問題があるのかを即座に特定できます。
テストの網羅性：正常系と境界値を意識する
- テストケースを設計する際は、以下の観点を網羅するようにします。
- 正常系（ハッピーパス）: 機能が期待通りに動作する、最も代表的なシナリオ。
- 境界値（エッジケース）:
  - 引数が null, undefined, 空文字列, 0 の場合
  - 配列が空、または要素が1つだけの場合
  - 処理の成功・失敗の境界となる値
- これらのケースをテストすることで、予期せぬ不具合を未然に防ぎ、コードの堅牢性を高めます。
事前準備：テスト環境の把握
- テストを記述する前に、jest.config.js や pytest.ini といったテスト設定ファイルを確認します。
- テストランナーの挙動、利用可能なモック、パスのエイリアスなどを事前に把握することで、手戻りを防ぎ、スムーズなテスト作成が可能になります。

🔀 Git 運用ルール

✅ 作業後（After Done）

対象 Issue を Closed にする。
コメントや振り返り（Check, Act）を残す。
作業内容を初心者でも理解できるよう、わかりやすい解説文を記述すること。
作業から得られた知見が、設定ファイル（GEMINI.mdなど）に反映すべきと判断される場合は、提案を行うこと。
コード変更後は、以下の静的解析ツールとフォーマッター、テストを実行し、コード全体に問題がないことを確認すること。
- Python: flake8 (静的解析), black (フォーマッター), pytest (テスト)
テスト容易性のための依存性注入:
- クラスが外部の依存関係（例: jQuery, alert関数）に直接依存するのではなく、コンストラクタを通じてそれらを受け取る「依存性注入」のパターンを採用することで、テスト時にこれらの依存関係をモックしやすくなり、コードのテスト容易性が向上する。

🛠 技術スタック

フレームワーク:
言語:
テスト: pytest
バージョン管理: GitHub
開発環境: