| # 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）氏の思想を参考に、「動く仕様書」として機能させることを目指す** | |
| #### **テストコード設計の具体的な指針** | |
| 1. **テストの対象：振る舞いをテストし、実装の詳細はテストしない** | |
| * テストの主な目的は、機能の**振る舞い（Behavior）**が期待通りであることを保証することです。「何ができるか」をテストし、「どのように実装されているか」はテストしません。 | |
| * 関数の内部ロジックやUIの見た目といった**実装の詳細（Implementation Details）**に依存するテストは、リファクタリングで壊れやすくなるため避けます。 | |
| * **避けるべきテストの例**: | |
| * 特定のHTML構造やCSSクラス名に依存する画面（UI）テスト。 | |
| * 関数の内部で、別の特定の関数が呼ばれたことだけを確認するような、過度に実装に踏み込んだテスト。 | |
| * **推奨されるテスト**: | |
| * 「ユーザーIDを渡すと、ユーザー名が返ってくる」 | |
| * 「無効な値を入力すると、エラーがスローされる」 | |
| * 上記のように、入力（Input）と、観測可能な結果（Output/State Change）に注目した振る舞いのテストを記述します。 | |
| 2. **命名と構造：テストの意図を日本語で明確にする** | |
| * **構造化**: `describe`を使い、テスト対象の関数やクラスごとにテストをグループ化します。 | |
| * **命名（日本語での記述）**: テストケース名（`test`関数の第一引数）は**必ず日本語**で、「〜という状況で、〜という振る舞いをすべき」というように、具体的なシナリオと期待される結果を記述します。 | |
| * 良い例: `test('クッキーが存在しない場合、nullを返すこと')` | |
| * 悪い例: `test('getCookie test 2')` | |
| * このルールを徹底することで、日本語話者の開発者にとって、テストコードがそのまま日本語の仕様書として機能します。 | |
| 3. **テストの粒度：1テスト1検証の原則** | |
| * 1つのテストケースでは、1つの具体的な振る舞いのみを検証します。 | |
| * これにより、テストが失敗した際に、どの振る舞いに問題があるのかを即座に特定できます。 | |
| 4. **テストの網羅性：正常系と境界値を意識する** | |
| * テストケースを設計する際は、以下の観点を網羅するようにします。 | |
| * **正常系（ハッピーパス）**: 機能が期待通りに動作する、最も代表的なシナリオ。 | |
| * **境界値（エッジケース）**: | |
| * 引数が `null`, `undefined`, 空文字列, `0` の場合 | |
| * 配列が空、または要素が1つだけの場合 | |
| * 処理の成功・失敗の境界となる値 | |
| * これらのケースをテストすることで、予期せぬ不具合を未然に防ぎ、コードの堅牢性を高めます。 | |
| 5. **事前準備：テスト環境の把握** | |
| * テストを記述する前に、`jest.config.js` や `pytest.ini` といったテスト設定ファイルを確認します。 | |
| * テストランナーの挙動、利用可能なモック、パスのエイリアスなどを事前に把握することで、手戻りを防ぎ、スムーズなテスト作成が可能になります。 | |
| ## 🔀 Git 運用ルール | |
| ## ✅ 作業後（After Done） | |
| - 対象 Issue を `Closed` にする。 | |
| - コメントや振り返り（Check, Act）を残す。 | |
| - 作業内容を初心者でも理解できるよう、わかりやすい解説文を記述すること。 | |
| - 作業から得られた知見が、設定ファイル（GEMINI.mdなど）に反映すべきと判断される場合は、提案を行うこと。 | |
| - コード変更後は、以下の静的解析ツールとフォーマッター、テストを実行し、コード全体に問題がないことを確認すること。 | |
| - Python: `flake8` (静的解析), `black` (フォーマッター), `pytest` (テスト) | |
| - **テスト容易性のための依存性注入**: | |
| - クラスが外部の依存関係（例: jQuery, `alert`関数）に直接依存するのではなく、コンストラクタを通じてそれらを受け取る「依存性注入」のパターンを採用することで、テスト時にこれらの依存関係をモックしやすくなり、コードのテスト容易性が向上する。 | |
| ## 🛠 技術スタック | |
| - フレームワーク: | |
| - 言語: | |
| - テスト: pytest | |
| - バージョン管理: GitHub | |
| - 開発環境: | |