---
name: frontend-implement
description: フロントエンドコードの新規作成・改修を行うスキル。実装後に関連する設計書を自動更新する。「画面を実装して」「コンポーネントを追加して」「フロントエンドを改修して」「この設計書を元にフロントエンドを実装して」といった指示で発動する。code-first（要件→コード→設計書更新）とdoc-first（設計書→コード実装）の両方向に対応する。
---

# フロントエンド実装スキル

フロントエンドコードの新規作成・改修を行い、完了後に関連する設計書を自動更新する。

## 事前準備

作業開始前に、以下のファイルを読み込んでください:

- `.claude/project-config.md` — フレームワーク・ディレクトリ構造・APIクライアントの場所・状態管理の方式

`.claude/project-config.md` の先頭に `CONFIG_STATUS: UNCONFIGURED` が含まれている場合は作業を開始せず、
`project-setup` スキルを実行するようユーザーに案内してください。

---

## 動作モード

ユーザーの指示から自動的にモードを判定します。

| モード | 判定条件 | フロー |
|---|---|---|
| **code-first** | 「〇〇画面を作って」「コンポーネントを追加して」「このバグを直して」等、要件・タスクを直接記述 | 要件分析 → 【確認①】実装計画 → コード実装 → 変更ファイル記録 → 設計書更新委譲 |
| **doc-first** | 「この設計書を元に実装して」「仕様書通りに画面を修正して」等、設計書を起点に記述 | 設計書解析 → 差分分析 → 【確認①】実装計画 → コード実装 → 整合確認 |

---

## code-first モード

### Step 1: 要件分析

ユーザーの指示から以下を明確にする:

- 実装対象（新規ページ / 既存ページの改修 / 新規コンポーネント / APIクライアント / 状態管理 等）
- 対象アプリ（`.claude/project-config.md` に記載の複数アプリがある場合）
- APIとの連携が必要かどうか（バックエンド側の変更が伴うか）
- 状態管理の変更が必要かどうか

不明な点があればこの時点でユーザーに確認する。実装を開始してから仕様が変わると手戻りが大きいため、
曖昧な要件は必ず解消してから次のステップへ進む。

### Step 2:【確認①】実装計画の提示

以下の形式で実装計画を提示し、ユーザーの承認を得る。
**ユーザーが承認するまで、いかなるコードの書き込みも行わない。**

```
## 実装計画

### なぜこの実装アプローチか
{設計上の判断・選択肢の比較・トレードオフを自然言語で説明する。
 例: 「既存の CartContext を拡張する方針をとります。新規 Context を作ると
     プロバイダのネストが深くなるため、責務を一箇所に集約します。」}

### 作成・修正するファイル
| 操作 | ファイルパス | 変更内容の概要 |
|---|---|---|
| 新規作成 | {path} | {概要} |
| 修正 | {path} | {概要} |

### API連携
{新規 or 既存のAPIエンドポイントとの連携内容、または「なし」}

### 影響する設計書（実装後に更新予定）
- {doc_path}: {更新内容の概要}

この計画で実装を進めてよいですか？
```

### Step 3: コード実装

承認を得たらコードを実装する。
以下の「コーディング規約」を必ず遵守すること。

### Step 4: 変更ファイルの記録

実装完了後、変更したすべてのファイルを以下の形式で整理する:

```
変更ファイルリスト:
- {path}（新規作成）
- {path}（修正）
```

### Step 5: 設計書の自動更新

`doc-sync` スキルを即時モードで呼び出し、設計書更新を委譲する。
フロントエンドの変更は以下の設計書に影響する可能性があるため、漏れなく含める。

- ページ・コンポーネントの変更 → `frontend-spec-doc`（画面機能仕様書）
- 画面遷移の変更 → `screen-transition-gen`（画面遷移図）

doc-sync への指示テンプレート:

```
以下のファイルが変更されました。関連する設計書を即時同期モードで更新してください。

【変更ファイルリスト】
{変更ファイル一覧}

即時同期モードで実行してください（git履歴ではなくこのリストを参照する）。
更新予定の概要（差分予測）をユーザーに提示し、確認を得てから更新を適用してください。
```

---

## doc-first モード

### Step 1: 設計書の読み込みと解析

指定された設計書を Read し、以下を抽出する:

- 実装すべき画面・コンポーネントの一覧
- UI仕様（表示項目・レイアウト・インタラクション）
- APIとの連携仕様（エンドポイント・リクエスト・レスポンスの使い方）
- バリデーション仕様（クライアント側バリデーション）
- 画面遷移仕様（どの操作でどこに遷移するか）
- 権限・認証ガード（認証が必要な画面かどうか）

### Step 2: 現状コードとの差分分析

対応するソースファイルが存在する場合は読み込み、設計書との差分を分析する:

| 状況 | 対応 |
|---|---|
| 設計書にあるがコードにない | 新規実装が必要 → 実装計画に追加 |
| コードが設計書と異なる振る舞いをしている | 修正が必要 → 実装計画に追加 |
| コードにあるが設計書に記載がない | ユーザーに確認（仕様漏れ or コード側の独自追加） |

### Step 3:【確認①】実装計画の提示

code-first モードと同形式で提示する。加えて、設計書との対応関係を表で明示する:

```
### 設計書 → コード 対応マップ
| 設計書の記述 | 実装ファイル | 変更内容 |
|---|---|---|
| カート一覧表示 | pages/cart/index.tsx | CartList コンポーネントの表示ロジックを追加 |
| 商品削除ボタン | components/CartItem.tsx | onDelete ハンドラを追加 |
```

### Step 4: コード実装

code-first モードと同じ「コーディング規約」で実装する。

### Step 5: 設計書との整合確認

実装完了後、以下の観点で設計書と照合する:

- 設計書に記載されたすべての UI 仕様がコードに反映されているか
- API連携・バリデーション・画面遷移が設計書通りに動作するか

差分が残っている場合はユーザーに以下のいずれかを提案する:

1. コードを設計書に合わせて修正する（設計書が正）
2. 設計書をコードの実装に合わせて更新する（実装都合で仕様変更が発生した場合）

---

## コーディング規約（必須）

すべての実装でこの規約を遵守すること。

### 1. 実装意図のコメント

コンポーネントファイルの先頭、または複雑なロジックの直前に、その実装の意図と設計判断を記述したコメントを追記する。
コードを読むだけでは伝わらない「なぜそうしたか」を必ず残す。

```typescript
/**
 * CartPage
 *
 * カート画面のメインコンポーネント。
 * 商品一覧・合計金額・クーポン適用を一画面で管理する。
 *
 * NOTE: カートの状態は CartContext で管理している。
 *       このコンポーネントはUIの表示とイベントハンドリングのみを担当し、
 *       ビジネスロジックは CartContext 内のメソッドに委譲している。
 *
 * TODO: スマートフォン向けのレスポンシブ対応が未実装
 */
export const CartPage: React.FC = () => {
```

### 2. TODO / NOTE / FIXME / HACK コメント

将来の対応が必要な箇所・既知の制約・暫定対応には、必ずタグ付きコメントを残す。

```typescript
// TODO: エラー発生時のリトライ処理を追加する
// NOTE: このコンポーネントは親から必ず userId が渡される前提。未定義時は表示しない。
// FIXME: API エラー時にフォームのローディング状態が解除されないバグがある
// HACK: ライブラリのバグ回避のための暫定コード。v2.x にアップデート後に削除する
```

### 3. 可読性優先のコーディング

**命名は省略せず、意図が伝わる名前にする**

```typescript
// 良い例
const isCartItemCountOverLimit = cartItems.length > MAX_CART_ITEMS;
const handleDeleteCartItem = (itemId: string) => { ... };

// 悪い例（何を表しているか一読では分からない）
const flag = items.length > 50;
const del = (id: string) => { ... };
```

**マジックナンバーは定数に切り出してコメントを付ける**

```typescript
// 良い例
const MAX_CART_ITEMS = 50;  // カートに追加できる商品の上限（仕様書 §3.2 参照）

// 悪い例
if (items.length > 50) {
}
```

**カスタムフックで複雑なロジックをコンポーネントから分離する**

```typescript
// 良い例: コンポーネントが何をするかが一目で分かる
export const CartPage: React.FC = () => {
  const { cartItems, totalPrice, addItem, removeItem } = useCart();
  const { couponCode, applyCoupon, discountAmount } = useCoupon(cartItems);
  // ...表示ロジックのみ
};

// 悪い例: コンポーネントに API 呼び出し・状態管理・表示ロジックが混在する
export const CartPage: React.FC = () => {
  const [cartItems, setCartItems] = useState([]);
  const [loading, setLoading] = useState(false);
  useEffect(() => {
    fetch('/api/cart').then(res => res.json()).then(data => setCartItems(data));
  }, []);
  // ...長いコンポーネント
};
```

**型定義は明示的に書き、any を避ける**

```typescript
// 良い例
interface CartItem {
  itemId: string;
  itemName: string;
  quantity: number;
  unitPrice: number;
}

// 悪い例
const cartItems: any[] = [];
```

### 4. プロジェクト固有の規約遵守

`.claude/project-config.md` に記載された以下を必ず参照・遵守する:

- フレームワーク固有のルーティング方式（Next.js Pages Router / App Router / Nuxt 等）
- APIクライアントの置き場所とインポート方法
- 状態管理の方式（Context / Zustand / Pinia 等）
- 認証ガードコンポーネントの使い方
- 画面遷移のパターン（`router.push` / `useNavigate` / `navigateTo` 等）

---

## 品質チェック（実装完了前に確認）

`references/implementation-checklist.md` を参照して確認する。

---

## 注意事項

- 既存ファイルを修正する前に必ず Read して現状を把握してから手を入れる
- 認証が必要なページには認証ガードを適用する（`.claude/project-config.md` 参照）
- APIクライアントの呼び出しはエラーハンドリングを含めて実装する
- フォームを実装する場合はバリデーションも合わせて実装する
- テストファイルの作成・更新が必要かどうかはユーザーに確認してから行う
- デザインの詳細（色・フォント・余白等）が不明な場合は既存コンポーネントのスタイルに合わせる