---
name: developing-frontend
description: フロントエンド開発の TDD ワークフローを支援。Red-Green-Refactor サイクルとアウトサイドインアプローチで品質の高い UI を実装する。「フロントエンドを実装したい」「画面を作りたい」「コンポーネントを追加したい」「フロントエンドのテストを書きたい」「画面遷移やコンポーネントの一覧をコードと同期させたい」「API の型をバックエンドと揃えたい」といった場面で発動する。画面とシナリオの知識を Living Documentation としてコードに持たせる実践も案内する。TDD で開発することで、UI の振る舞いを自動テストで保証し、安全なリファクタリングを可能にする。
---

# フロントエンド開発

TDD サイクルに従いフロントエンドを開発する。アウトサイドインアプローチ（UI 層→ロジック層→データ層）で、ユーザー視点から内側へ段階的に構築する。

アウトサイドインの利点は、ユーザーが実際に操作する画面から始めるため、不要な機能を作らずに済むこと。テストがユーザーの振る舞いに基づくため、実装の詳細に依存しにくい。

## 参照ドキュメント

| 種類 | パス |
|------|------|
| ワークフロー | @docs/reference/コーディングとテストガイド.md |
| アーキテクチャ | @docs/design/architecture_frontend.md |
| UI 設計 | @docs/design/ui-design.md |
| 技術スタック | @docs/design/tech_stack.md |
| テスト戦略 | @docs/design/test_strategy.md |
| 開発戦略 | @docs/development/development_strategy.md（Living Documentation の採用可否・語彙・局面ごとの重点） |
| Living Documentation | @docs/reference/LivingDocumentation導入ガイド.md、@docs/reference/ダイナミックキュレーション導入ガイド.md |
| 受け入れシナリオ（BDD 採用時） | @docs/reference/BDD導入ガイド.md |

## TDD サイクル

10-15 分で 1 サイクルを完了させる。サイクルが長引くなら、タスクの粒度が大きすぎる。

1. **Red**: 失敗するテストを最初に書く
2. **Green**: テストを通す最小限のコードを実装する
3. **Refactor**: 重複を除去し設計を改善する

## アプローチ

- **アウトサイドイン**（推奨）: UI から開始しロジックを段階的に実装する
- **インサイドアウト**: ユーティリティ/hooks から開始し上位層へ展開する

## Living Documentation の実践

フロントエンドの知識は、ルート定義・コンポーネント・API の型・E2E テストの中にある。画面一覧や遷移図、API の型を別文書に書き写すと、画面を 1 つ足すたびに古くなる。**権威ある情報源をコードに置き、そこから生成し、足りない意図だけを補う**。採用するかどうかと語彙は開発戦略に従う。

### 層ごとの知識の持たせ方

アウトサイドインで外側から下りる順に並べる。

| 層 | 権威ある情報源 | 生成・検証するもの | 補う知識 |
| :--- | :--- | :--- | :--- |
| 受け入れ（最外殻） | E2E テスト・BDD シナリオ | デモ項目をシナリオとして実行し、そのまま振る舞いの仕様として公開する | シナリオの意図（誰が何のために操作するか）をシナリオの冒頭に書く |
| 画面・ルーティング | ルート定義 | 画面一覧と画面遷移図をルート定義から生成する。`docs/design/` の UI 設計にルート一覧を手で複製しない | 遷移の理由やロールによる制御の意図を UI 設計に残す |
| コンポーネント | コンポーネントとその使用例 | コンポーネントカタログ（Storybook など、採用している場合）を使用例から生成する | 模範とするコンポーネントを JSDoc タグ（例: `@exemplar`）や命名規約で示す |
| ロジック・データ | API クライアントと型 | API の型はバックエンドが公開する OpenAPI から生成し、手で書かない。生成した型とのずれは型チェックで検出する | 画面固有の状態の持ち方など、型に表れない判断を ADR に残す |

### フロントエンドで守ること

- **ユビキタス言語を画面に通す**: コンポーネント名・画面の文言・テスト名をバックエンドのドメイン用語と揃える。同じ概念を画面ごとに別の名前で呼ばない
- **テストを利用者の言葉で書く**: テスト名とテスト内の操作は「ユーザーが何をするか」で書く。実装の詳細（DOM 構造やクラス名）に依存したテストは、仕様として読めない
- **注釈は軽く保つ**: TypeScript/JavaScript は実行時に読めるアノテーションが一般にないため、JSDoc のタグ・フォルダ構成・命名規約で役割を表す。付けるのは例外と本質的な知識だけにする
- **重複させた知識には検証を付ける**: バックエンドと共有する型・定数・ルートの権限設定は、生成するか、不一致を検出するテストで守る
- **画面キャプチャは生成する**: マニュアル用の画面キャプチャは E2E ツールで再生成する（`creating-manual`）。手で撮り直す運用にすると画面の変更に追従しなくなる

### TDD サイクルでのタイミング

- **Red**: 最外殻のテスト（E2E・シナリオ）を業務の言葉で書き、そこから内側のテストへ下りる
- **Refactor**: コンポーネント名と文言を用語に揃える。模範例や見どころの印は、付ける数を最小にする
- **コミット**: 変更の意図を書く（`git-commit`）。状態管理やルーティングの方式など、代替案を比べて選んだ判断は ADR に残す（`creating-adr`）

## テストコマンド

```bash
# 全テスト実行
cd apps/frontend && npm run test

# ウォッチモードでテスト実行
cd apps/frontend && npm run test:watch

# テストカバレッジ確認
cd apps/frontend && npm run test:coverage

# E2E テスト実行
cd apps/frontend && npm run test:e2e
```

## 品質チェックリスト

コミット前に必ず確認する。

- [ ] すべてのテストがパス
- [ ] ESLint の警告がゼロ
- [ ] テストカバレッジが目標を満たしている
- [ ] 単一の論理的作業単位を表現
- [ ] コミットメッセージが変更内容を明確に説明
- [ ] （Living Documentation 採用時）コンポーネント名・文言・テスト名がドメインの用語に揃っている
- [ ] （Living Documentation 採用時）API の型が生成物と一致し、画面一覧・遷移図などの生成物がビルドで生成できる

## 途中から再開

開発セッションの途中から再開する場合は、まず現在のテスト状態を確認する。

**Example:**

```
ユーザー: 「ログイン画面のコンポーネントは作った。バリデーションを追加したい」
回答: 既存テストを実行して Green 状態を確認する。
      バリデーションの失敗するテスト（Red）を書いてから実装に進む。
      ユーザーが不正な入力をした場合のエラー表示をテストする。
```

## コンテキスト管理

タスクの区切りごとに `/compact` を実施して Context limit reached エラーを回避する。

- TDD サイクルを数回繰り返した後、コンポーネント完了時、コミット完了後に実施する
- `/compact` 前に現在の作業状態と次のタスクをメモとして出力する

## 注意事項

- Node.js/npm のテスト環境が設定済みであること（前提条件）
- TDD の三原則を厳密に守る。テストなしでプロダクションコードを書かない
- コミット前に必ず品質チェックリストを実行する
- 作業完了後に対象の @docs/development/iteration_plan-N.md の進捗を更新する
- コンポーネントは単一責任の原則に従い小さく保つ。TODO 駆動で分割し、Rule of Three でリファクタリングする
- ルート一覧・コンポーネント一覧・API の型など、コードから取り出せる知識を `docs/design/` に手で書き写さない。書くのはコードに無い意図と根拠だけにする

## 関連スキル

- `developing-backend` — バックエンド TDD 開発
- `orchestrating-development` — 開発フェーズ全体のワークフロー
- `git-commit` — Conventional Commits 準拠のコミット
- `creating-adr` — 設計判断の根拠の記録
- `creating-manual` — E2E ツールによる画面キャプチャの再生成
- `creating-development-strategy` — Living Documentation の採用可否・語彙・局面ごとの重点