| name | develop-frontend |
| description | Next.js/Reactによるフロントエンド実装スキル（UI、API連携、状態管理、テスト） |
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
Issue番号の確認
- Orchestratorから渡されたタスク定義にissue_numberが含まれていることを確認
- Issue番号がない場合は、Orchestratorに報告して作業を中断
- ブランチ名にIssue番号が含まれていることを確認
作業前確認完了の報告
以下を確認したことをOrchestratorに報告:
1-2. タスク内容の理解
-
Orchestratorからのタスク定義を確認
-
以下を把握:
- 実装すべき画面仕様
- UIコンポーネント要件
- API連携仕様
- 認証要件
-
関連ドキュメントを参照:
documents/development/coding-rules/frontend-rules.mddocuments/features/[機能名]/specification.mddocuments/architecture/system-architecture.md
-
shadcn/ui既存コンポーネント確認:
ls frontend/components/ui/
Phase 2: コンポーネント設計
-
shadcn/ui利用検討（最優先）
- まず既存のshadcn/uiコンポーネントで要件が満たせるかチェック
- 利用可能な場合は自作せずshadcn/uiを使用
- カスタマイズが必要な場合は拡張コンポーネントで実装
- shadcn/uiに存在しない場合のみ自作コンポーネントを作成
-
コンポーネント分類
- Presentational: UI表示に特化、propsを受け取って表示
- 配置:
components/[ComponentName]/index.tsx
- 状態を持たない、再利用可能
- storybookで確認可能にする
- Container: ビジネスロジック管理、データ取得
- 配置:
views/[feature]/[ViewName].tsx
- 状態管理、API呼び出し
- 表示/非表示制御の責務
- View専用: 特定View専用のコンポーネント
- 配置:
views/[feature]/_internal/[ComponentName].tsx
- 他のViewから参照されない
-
ファイル構成
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連携準備
-
TypeScript interfaceの定義
- PascalCase命名
- strictモード対応
- any型使用禁止（unknown型を使用）
-
Orval生成クライアントの確認:
ls frontend/src/lib/api/generated/
-
カスタムフックの設計:
use[リソース名]: データ取得系use[アクション]: アクション系- loading, error, dataの3状態を返す
Phase 4: Presentational Components実装
-
shadcn/uiコンポーネントを優先使用
-
必要に応じて自作コンポーネント作成
-
以下のルールを遵守:
- 1ファイル1コンポーネント
- displayNameは設定しない（関数名から自動推論）
- exportは定義と同時（
export const ComponentName = ...）
- JSX.Element型注釈は不要（TypeScript自動推論）
- classNameプロパティは必要最低限
- React.forwardRefは使用しない
-
スタイリング:
- Tailwind CSSクラスで統一
- タブレットファースト（md: 768px基準）
- CSS変数でテーマカスタマイズ
- cn()ユーティリティでクラス結合
-
Storybookストーリー作成:
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: {
},
};
Phase 5: Container Components実装
-
views/[feature]配下にContainer作成
-
カスタムフックでデータ取得:
const { data, loading, error } = useUserData(userId);
-
状態管理:
- useStateで局所的な状態管理
- 複雑な状態はカスタムフックに切り出し
-
表示制御:
- コンポーネントの表示/非表示制御はこの層で実装
- 条件分岐でPresentationalを切り替え
-
エラーハンドリング:
- エラー境界の実装
- ユーザーフレンドリーなエラーメッセージ
Phase 6: API連携実装
-
Orval生成クライアント活用
-
カスタムフックでラップ:
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 };
};
-
MSWでAPIモック定義（テスト用）:
Phase 7: フォーム実装（該当する場合）
-
React Hook FormとZodでスキーマ定義:
const schema = z.object({
name: z.string().min(1, '名前は必須です'),
email: z.string().email('メールアドレスの形式が正しくありません'),
});
type FormData = z.infer<typeof schema>;
-
useFormでフォーム管理:
const form = useForm<FormData>({
resolver: zodResolver(schema),
});
-
shadcn/ui Formコンポーネント活用
Phase 8: テスト実装
-
Presentationalコンポーネントのテスト:
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);
});
});
-
Containerコンポーネントのテスト:
- MSWでAPIモック
- 非同期処理はwaitFor使用
- ローディング・エラー状態のテスト
-
Phase 9: ローカル検証
9-1. 未使用コードの確認（必須）
重要: TypeScript/ESLintでは未使用import・変数を検出できますが、未使用の関数・コンポーネントはIDE警告でしか検出されません。
VSCode/Cursorでの確認手順:
- 変更したTypeScript/TSXファイルをすべて開く
- IDE上のグレーアウト表示や黄色波線をすべて確認
- 未使用import・変数・関数・コンポーネントがあれば削除
- 特に以下を重点的に確認:
- 未使用import文
- 未使用const/let/var変数
- 未使用関数・コンポーネント
- 未使用interface/type定義
確認必須項目:
9-2. Lint/テスト/ビルド実行
cd frontend
pnpm run lint:check
pnpm run test:ci
pnpm run build
検証項目:
9-3. エラー対応
エラーがある場合は修正し、全て成功するまで繰り返し
Phase 10: 完了報告とサーバー起動確認
10-1. サーバー起動による動作確認（必須）
開発内容を反映してフロントエンドサーバーを起動し、実装した画面が正常に動作することを確認:
cd frontend
pnpm dev
確認事項:
動作確認方法:
- ブラウザで実装したページにアクセス
- 画面操作（クリック、入力等）が正常に動作することを確認
- ネットワークタブでAPI通信を確認
- レスポンシブデザインの確認（タブレット・モバイル表示）
- エラーケースの確認（バリデーションエラー、API通信エラー等）
10-2. 完了報告
Orchestratorに以下の内容を報告:
## Frontend Developer 完了報告
### 実装内容
- **ページ**: [実装したページ一覧]
- **コンポーネント**: [作成したコンポーネント一覧]
- **カスタムフック**: [実装したフック一覧]
### 変更ファイル
- Page: [ファイルパス]
- Components: [ファイルパス一覧]
- Views: [ファイルパス一覧]
- Hooks: [ファイルパス一覧]
### テスト結果
- 単体テスト: [テストファイル数] ファイル、[テストケース数] ケース
- カバレッジ: [数値]%
- Lint: [結果]
- ビルド: [結果]
### サーバー起動確認
- [ ] `pnpm dev` でサーバー起動成功
- [ ] 実装したページの動作確認済み
- [ ] コンソールエラーなし
- [ ] UI要素の表示確認済み
- [ ] API連携動作確認済み
- [ ] レスポンシブデザイン確認済み
### 確認事項
- [ ] 作業前にブランチ確認済み（mainブランチでない）
- [ ] Issue番号確認済み
- [ ] shadcn/ui既存コンポーネント活用検討済み
- [ ] TypeScript strictモードエラーなし
- [ ] any型不使用（unknown型使用）
- [ ] 1ファイル1コンポーネント
- [ ] displayName未設定（自動推論）
- [ ] React.forwardRef不使用
- [ ] タブレットファースト設計
- [ ] **未使用コード削除済み（IDE警告で確認）**
- [ ] **未使用import削除済み**
- [ ] **未使用変数・関数・コンポーネント削除済み**
- [ ] **未使用type/interface削除済み**
- [ ] **コメントアウトコード削除済み**
- [ ] テストカバレッジ80%以上
- [ ] Lint/ビルド成功
- [ ] Storybookストーリー作成済み（Presentationalコンポーネント）
[ ] サーバー起動・動作確認済み
使用ツール
必須ツール
- Read: ドキュメント参照、既存コード確認
- Write: 新規ファイル作成
- Edit: 既存ファイル編集
- Bash: Lint/テスト/ビルド実行
推奨ツール
- Grep: 類似実装検索
- Glob: コンポーネント検索
MCP（Model Context Protocol）ツール
Context7 MCP（技術ドキュメント参照）
最新の技術ドキュメント・ベストプラクティス確認:
-
Next.js関連
resolve-library-id: "next.js"
get-library-docs: "/vercel/next.js"
topic: "app router server components"
-
React関連
resolve-library-id: "react"
get-library-docs: "/facebook/react"
topic: "hooks best practices"
-
shadcn/ui関連
resolve-library-id: "shadcn/ui"
get-library-docs: "/shadcn/ui"
topic: "component customization"
-
YouTube API関連（フロントエンド）
resolve-library-id: "youtube iframe api"
get-library-docs: "/youtube/iframe_api_reference"
topic: "player events"
活用場面:
- App Routerのベストプラクティス確認
- Hooksルールの確認
- パフォーマンス最適化（useMemo/useCallback）
- アクセシビリティ対応
Chrome DevTools MCP（実動作確認）
実際のブラウザでの動作・パフォーマンス確認:
-
navigate_page: ページ遷移
url: "http://localhost:3000/dashboard"
-
take_snapshot: ページの状態確認
# 実装したUIの構造確認
-
list_network_requests: API呼び出し確認
# ダッシュボードのAPI呼び出しを監視
resourceTypes: ["fetch", "xhr"]
-
performance_start_trace: パフォーマンス測定
reload: true
autoStop: true
# Core Web Vitalsの測定
-
take_screenshot: 視覚的な確認
format: "png"
# レスポンシブデザインの確認
活用場面:
- 実装した画面の動作確認
- API通信の検証
- レンダリングパフォーマンス測定
- レスポンシブデザイン確認
- Core Web Vitals測定
コーディング規約チェックリスト
TypeScript/基本設計
React Hooks
Next.js App Router
shadcn/ui/スタイリング
コンポーネント設計
フォーム実装
パフォーマンス
テスト
品質/セキュリティ
参照ドキュメント
必須参照
documents/development/coding-rules/frontend-rules.md: フロントエンドコーディング規約documents/development/development-policy.md: 開発ガイドラインdocuments/features/[機能名]/specification.md: 機能仕様書
必要に応じて参照
documents/architecture/tech-stack.md: 技術スタックdocuments/architecture/system-architecture.md: システムアーキテクチャfrontend/components/ui/: shadcn/uiコンポーネントfrontend/src/lib/api/generated/: Orval生成APIクライアント
トラブルシューティング
Lint/ビルドエラー
- エラーメッセージを確認
- Biome設定（biome.json）確認
- TypeScript設定（tsconfig.json）確認
- コーディング規約に照らして修正
テストエラー
- エラーメッセージを確認
- MSWハンドラー設定確認
- 非同期処理の待機確認（waitFor）
- モック設定の確認
カバレッジ不足
- カバレッジレポート確認
- 未テストの分岐を特定
- 境界値・異常系のテスト追加
shadcn/uiコンポーネントのカスタマイズ
- ui/配下は直接編集禁止
- 拡張コンポーネントで実装
- cva（class-variance-authority）でvariant追加
