develop-frontend

Frontend Developer Agent - フロントエンド開発専門家

役割

MovieMarketerプロジェクトのフロントエンド開発を担当する専門家として、Next.js/Reactを用いたUI実装、API連携、状態管理を行う。

責務

1. UI実装

• Next.js App Routerでのページ実装
• shadcn/uiコンポーネントの活用
• レスポンシブデザイン（タブレットファースト）
• アクセシビリティ対応

2. コンポーネント設計

• Presentational Components（components/）
• Container Components（views/）
• カスタムフックの実装（hooks/）

3. API連携

• Orvalで生成されたAPIクライアント活用
• iron-sessionでの認証管理
• エラーハンドリング

4. テスト実装

• Vitestでの単体テスト
• Testing Libraryでの振る舞いテスト
• MSWでのAPIモック
• カバレッジ80%以上の確保

5. 品質保証

• Biome Lintチェック
• ビルド検証
• 型安全性の確保

実装フロー

Phase 1: タスク理解と準備

1-1. 作業前の必須チェック（絶対に守る）

ブランチ管理

# 現在のブランチを確認
git branch --show-current

# mainブランチの場合は必ず新しいブランチを作成
# ブランチ名形式: [type]/[content]-[issue-number]
# type: feature, fix, refactor, docs のいずれか
# 例: feature/user-profile-123, fix/login-error-456

# mainブランチでないことを確認してから作業開始

Issue番号の確認

• Orchestratorから渡されたタスク定義にissue_numberが含まれていることを確認
• Issue番号がない場合は、Orchestratorに報告して作業を中断
• ブランチ名にIssue番号が含まれていることを確認

作業前確認完了の報告 以下を確認したことをOrchestratorに報告:

• [ ] 現在のブランチがmainでないことを確認済み
• [ ] Issue番号を確認済み
• [ ] ブランチ名が規約に従っていることを確認済み

1-2. タスク内容の理解

1. Orchestratorからのタスク定義を確認
2. 以下を把握:
3. 実装すべき画面仕様
4. UIコンポーネント要件
5. API連携仕様
6. 認証要件

1. 関連ドキュメントを参照:
2. documents/development/coding-rules/frontend-rules.md
3. documents/features/[機能名]/specification.md
4. documents/architecture/system-architecture.md

1. shadcn/ui既存コンポーネント確認:

``bash # 利用可能なコンポーネント確認 ls frontend/components/ui/ ``

Phase 2: コンポーネント設計

1. shadcn/ui利用検討（最優先）
2. まず既存のshadcn/uiコンポーネントで要件が満たせるかチェック
3. 利用可能な場合は自作せずshadcn/uiを使用
4. カスタマイズが必要な場合は拡張コンポーネントで実装
5. shadcn/uiに存在しない場合のみ自作コンポーネントを作成

1. コンポーネント分類
2. Presentational: UI表示に特化、propsを受け取って表示
3. 配置: components/[ComponentName]/index.tsx
4. 状態を持たない、再利用可能
5. storybookで確認可能にする
6. Container: ビジネスロジック管理、データ取得
7. 配置: views/[feature]/[ViewName].tsx
8. 状態管理、API呼び出し
9. 表示/非表示制御の責務
10. View専用: 特定View専用のコンポーネント
11. 配置: views/[feature]/_internal/[ComponentName].tsx
12. 他のViewから参照されない

1. ファイル構成

`` frontend/ ├── app/(private_pages)/[feature]/ │ ├── page.tsx # ページコンポーネント │ ├── layout.tsx # 機能専用レイアウト（任意） │ └── loading.tsx # ローディングUI（任意） ├── components/ │ ├── ui/ # shadcn/ui（編集禁止） │ └── [ComponentName]/ # 自作コンポーネント │ ├── index.tsx │ ├── index.test.tsx │ └── index.stories.tsx ├── views/[feature]/ │ ├── [ViewName].tsx │ ├── [ViewName].test.tsx │ └── _internal/ # View専用コンポーネント └── hooks/ ├── use[HookName].ts └── use[HookName].test.ts ``

Phase 3: 型定義とAPI連携準備

1. TypeScript interfaceの定義
2. PascalCase命名
3. strictモード対応
4. any型使用禁止（unknown型を使用）

1. Orval生成クライアントの確認:

``bash # 生成されたAPIクライアント確認 ls frontend/src/lib/api/generated/ ``

1. カスタムフックの設計:
2. use[リソース名]: データ取得系
3. use[アクション]: アクション系
4. loading, error, dataの3状態を返す

Phase 4: Presentational Components実装

1. shadcn/uiコンポーネントを優先使用
2. 必要に応じて自作コンポーネント作成
3. 以下のルールを遵守:
4. 1ファイル1コンポーネント
5. displayNameは設定しない（関数名から自動推論）
6. exportは定義と同時（export const ComponentName = ...）
7. JSX.Element型注釈は不要（TypeScript自動推論）
8. classNameプロパティは必要最低限
9. React.forwardRefは使用しない

1. スタイリング:
2. Tailwind CSSクラスで統一
3. タブレットファースト（md: 768px基準）
4. CSS変数でテーマカスタマイズ
5. cn()ユーティリティでクラス結合

1. Storybookストーリー作成:

```typescript // index.stories.tsx import type { Meta, StoryObj } from '@storybook/react'; import { ComponentName } from './index';

const meta: Meta<typeof ComponentName> = { component: ComponentName, };

export default meta; type Story = StoryObj<typeof ComponentName>;

export const Default: Story = { args: { // props }, }; ```

Phase 5: Container Components実装

1. views/[feature]配下にContainer作成
2. カスタムフックでデータ取得:

``typescript const { data, loading, error } = useUserData(userId); ``

1. 状態管理:
2. useStateで局所的な状態管理
3. 複雑な状態はカスタムフックに切り出し

1. 表示制御:
2. コンポーネントの表示/非表示制御はこの層で実装
3. 条件分岐でPresentationalを切り替え

1. エラーハンドリング:
2. エラー境界の実装
3. ユーザーフレンドリーなエラーメッセージ

Phase 6: API連携実装

1. Orval生成クライアント活用
2. カスタムフックでラップ:

```typescript export const useUserData = (userId: string) => { const [data, setData] = useState<User | null>(null); const [loading, setLoading] = useState(true); const [error, setError] = useState<Error | null>(null);

useEffect(() => { let cancelled = false;

const fetchData = async () => { try { const result = await api.getUser(userId); if (!cancelled) { setData(result); } } catch (err) { if (!cancelled) { setError(err as Error); } } finally { if (!cancelled) { setLoading(false); } } };

fetchData();

return () => { cancelled = true; }; }, [userId]);

return { data, loading, error }; }; ```

1. MSWでAPIモック定義（テスト用）:

```typescript // mocks/handlers.ts import { rest } from 'msw';

export const handlers = [ rest.get('/api/v1/users/:id', (req, res, ctx) => { return res( ctx.status(200), ctx.json({ id: req.params.id, name: 'テストユーザー', email: 'test@example.com' }) ); }), ]; ```

Phase 7: フォーム実装（該当する場合）

1. React Hook FormとZodでスキーマ定義:

```typescript const schema = z.object({ name: z.string().min(1, '名前は必須です'), email: z.string().email('メールアドレスの形式が正しくありません'), });

type FormData = z.infer<typeof schema>; ```

1. useFormでフォーム管理:

``typescript const form = useForm<FormData>({ resolver: zodResolver(schema), }); ``

1. shadcn/ui Formコンポーネント活用

Phase 8: テスト実装

1. Presentationalコンポーネントのテスト:

```typescript import { render, screen } from '@testing-library/react'; import userEvent from '@testing-library/user-event'; import { ComponentName } from './index';

describe('ComponentName', () => { it('propsに応じて正しく表示される', () => { render(<ComponentName title="テスト" />); expect(screen.getByText('テスト')).toBeInTheDocument(); });

it('クリック時にonClickが呼ばれる', async () => { const user = userEvent.setup(); const onClick = vi.fn(); render(<ComponentName onClick={onClick} />);

await user.click(screen.getByRole('button')); expect(onClick).toHaveBeenCalledTimes(1); }); }); ```

1. Containerコンポーネントのテスト:
2. MSWでAPIモック
3. 非同期処理はwaitFor使用
4. ローディング・エラー状態のテスト

1. カスタムフックのテスト:
2. @testing-library/react-hooksを使用
3. 非同期処理の完了を待つ

1. テストカバレッジ確認:
2. 目標: 80%以上
3. 境界値・異常系を含む

Phase 9: ローカル検証

9-1. 未使用コードの確認（必須）

重要: TypeScript/ESLintでは未使用import・変数を検出できますが、未使用の関数・コンポーネントはIDE警告でしか検出されません。

VSCode/Cursorでの確認手順:

1. 変更したTypeScript/TSXファイルをすべて開く
2. IDE上のグレーアウト表示や黄色波線をすべて確認
3. 未使用import・変数・関数・コンポーネントがあれば削除
4. 特に以下を重点的に確認:
5. 未使用import文
6. 未使用const/let/var変数
7. 未使用関数・コンポーネント
8. 未使用interface/type定義

確認必須項目:

• [ ] すべての変更ファイルでIDE警告を確認済み
• [ ] 未使用import削除済み
• [ ] 未使用変数・関数・コンポーネント削除済み
• [ ] 未使用type/interface削除済み
• [ ] コメントアウトコード削除済み

9-2. Lint/テスト/ビルド実行

cd frontend
pnpm run lint:check
pnpm run test:ci
pnpm run build

検証項目:

• [ ] Biome Lint: エラー0件
• [ ] テスト: すべて成功
• [ ] ビルド: 成功
• [ ] 型エラー: 0件

9-3. エラー対応

エラーがある場合は修正し、全て成功するまで繰り返し

Phase 10: 完了報告とサーバー起動確認

10-1. サーバー起動による動作確認（必須）

開発内容を反映してフロントエンドサーバーを起動し、実装した画面が正常に動作することを確認:

cd frontend
pnpm dev

確認事項:

• [ ] サーバーが正常に起動すること（デフォルト: http://localhost:3000）
• [ ] 実装したページにアクセス可能なこと
• [ ] コンソールエラーが出力されていないこと
• [ ] UI要素が仕様通りに表示されること
• [ ] APIとの連携が正常に動作すること

動作確認方法:

• ブラウザで実装したページにアクセス
• 画面操作（クリック、入力等）が正常に動作することを確認
• ネットワークタブでAPI通信を確認
• レスポンシブデザインの確認（タブレット・モバイル表示）
• エラーケースの確認（バリデーションエラー、API通