+-------------------------------------------------------------+
| 1. RED: 失敗するテスト作成                                      |
|    - SPEC の AC(Acceptance Criteria) をテストケースに変換       |
|    - SPEC の EC(Edge Cases) を追加テストに変換                 |
|    - `npm test <test_file>` → 失敗確認                       |
+-------------------------------------------------------------+
| 2. GREEN: テストを通過する最小コード実装                         |
|    - SPEC の "AI 実装ヒント" 参照                              |
|    - 既存パターン準拠 (プロジェクトコンベンション)                 |
|    - `npm test <test_file>` → 通過確認                       |
+-------------------------------------------------------------+
| 3. REFACTOR: コード品質改善                                    |
|    - 重複排除、ネーミング改善                                   |
|    - `npm run lint` → 警告なし確認                            |
|    - テスト依然として通過確認                                   |
+-------------------------------------------------------------+

## FR-NNNNN 実装

### テスト作成 (Red)

- [ ] Unit Test: `tests/unit/features/<feature>/<name>.test.ts(x)` 作成
- [ ] AC 別テストケース作成
- [ ] EC 別エッジケーステスト作成
- [ ] `npm test <path>` → 失敗確認

### コード実装 (Green)

- [ ] Type + Zod Schema 実装 (必要時)
- [ ] API Layer 実装 (必要時)
- [ ] Custom Hook 実装 (必要時)
- [ ] Component/Page 実装 (必要時)
- [ ] `npm test <path>` → 通過確認

### 品質検証 (Refactor)

- [ ] `npm run lint` 通過
- [ ] コード重複排除
- [ ] SPEC の Error Handling Policy 準拠確認

Read(".claude/wisdom/project-patterns.md")   # プロジェクトパターン確認
Read(".claude/wisdom/common-errors.md")       # エラー解決策参照

bash -c "echo '
## {パターン名}

**状況**: {どの状況で使用するか}
**実装**: \`\`\`typescript
// コード例
\`\`\`
**根拠**: {なぜこの方法が良いか}

---
' >> .claude/wisdom/project-patterns.md"

bash -c "echo '
### {エラー概要}

**原因**: {根本原因}
**解決**: {適用した解決策}
**再発防止**: {同一問題防止方法}

---
' >> .claude/wisdom/common-errors.md"

# 正しい使用
bash -c "echo 'content' >> .claude/wisdom/file.md"

# 誤った使用 (上書き)
bash -c "echo 'content' > .claude/wisdom/file.md"

## 違反時は即座に中断してユーザーに報告

例:

- "DB スキーマ変更禁止" → 新テーブル必要時 → 中断 & 報告
- "外部パッケージ追加禁止" → 新パッケージ必要時 → 中断 & 報告

BAD:  全ファイルを一括作成
GOOD: 一つのFR → テスト → 実装 → 検証 → 次のFR

// src/features/<feature>/types/index.ts

import { z } from 'zod';

/** [機能名] データモデルスキーマ */
export const xxxSchema = z.object({
  id: z.string(),
  name: z.string(),
  // ... フィールド
});

/** [機能名] データモデル型 */
export type XxxModel = z.infer<typeof xxxSchema>;

// src/features/<feature>/api/<feature>-api.ts

import { xxxSchema, type XxxModel } from '../types';
import { logger } from '@/shared/lib/logger';

const TAG = 'XxxApi';

/**
 * [機能名] データ取得
 *
 * @param id - 対象ID
 * @returns データ (失敗時は null)
 */
export async function fetchXxx(id: string): Promise<XxxModel | null> {
  try {
    const response = await fetch(`/api/xxx/${id}`);
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }
    const data = await response.json();
    return xxxSchema.parse(data);
  } catch (error) {
    logger.error(TAG, 'Error fetching xxx', error);
    return null;
  }
}

// src/features/<feature>/hooks/use-<feature>.ts

'use client';

import { useState, useEffect, useCallback } from 'react';
import { fetchXxx } from '../api/<feature>-api';
import { type XxxModel } from '../types';
import { MESSAGES } from '@/shared/constants/messages';
import { logger } from '@/shared/lib/logger';

const TAG = 'useXxx';

/** [機能名] フック状態 */
interface XxxState {
  data: XxxModel | null;
  isLoading: boolean;
  error: string | null;
}

/**
 * [機能名] カスタムフック
 *
 * @param id - 対象ID
 * @returns 状態とアクション
 */
export function useXxx(id: string) {
  const [state, setState] = useState<XxxState>({
    data: null,
    isLoading: true,
    error: null,
  });

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

    async function load() {
      try {
        logger.debug(TAG, `Loading xxx: ${id}`);
        const data = await fetchXxx(id);

        if (cancelled) return;

        if (data === null) {
          setState({ data: null, isLoading: false, error: MESSAGES.errors.dataNotFound });
          return;
        }

        setState({ data, isLoading: false, error: null });
      } catch (error) {
        if (cancelled) return;
        logger.error(TAG, 'Error loading xxx', error);
        setState({ data: null, isLoading: false, error: MESSAGES.errors.loadFailed });
      }
    }

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

  const doSomething = useCallback(async () => {
    setState((prev) => ({ ...prev, isLoading: true }));

    try {
      // ビジネスロジック
      setState((prev) => ({ ...prev, isLoading: false }));
    } catch (error) {
      logger.error(TAG, 'Error doing something', error);
      setState((prev) => ({
        ...prev,
        isLoading: false,
        error: MESSAGES.errors.operationFailed,
      }));
    }
  }, []);

  return { ...state, doSomething };
}

// tests/unit/features/<feature>/hooks/use-<feature>.test.ts

import { renderHook, waitFor } from '@testing-library/react';
import { vi, describe, it, expect, beforeEach } from 'vitest';
import { useXxx } from '@/features/<feature>/hooks/use-<feature>';
import * as xxxApi from '@/features/<feature>/api/<feature>-api';
import type { XxxModel } from '@/features/<feature>/types';

// モック設定
vi.mock('@/features/<feature>/api/<feature>-api');

describe('useXxx', () => {
  const mockData: XxxModel = { id: 'test-id', name: 'Test' };

  beforeEach(() => {
    vi.resetAllMocks();
  });

  // AC ベーステスト
  describe('AC1: データロード成功', () => {
    it('サービスがデータを返した場合、正常にロードされること', async () => {
      // Arrange
      vi.mocked(xxxApi.fetchXxx).mockResolvedValue(mockData);

      // Act
      const { result } = renderHook(() => useXxx('test-id'));

      // Assert
      await waitFor(() => {
        expect(result.current.isLoading).toBe(false);
      });
      expect(result.current.data).toEqual(mockData);
      expect(result.current.error).toBeNull();
    });
  });

  // EC ベーステスト
  describe('EC1: データなし', () => {
    it('サービスがnullを返した場合、エラーが設定されること', async () => {
      // Arrange
      vi.mocked(xxxApi.fetchXxx).mockResolvedValue(null);

      // Act
      const { result } = renderHook(() => useXxx('test-id'));

      // Assert
      await waitFor(() => {
        expect(result.current.isLoading).toBe(false);
      });
      expect(result.current.data).toBeNull();
      expect(result.current.error).toBeTruthy();
    });
  });

  describe('EC2: ネットワークエラー', () => {
    it('サービスが例外を投げた場合、エラーが設定されること', async () => {
      // Arrange
      vi.mocked(xxxApi.fetchXxx).mockRejectedValue(new Error('Network error'));

      // Act
      const { result } = renderHook(() => useXxx('test-id'));

      // Assert
      await waitFor(() => {
        expect(result.current.isLoading).toBe(false);
      });
      expect(result.current.data).toBeNull();
      expect(result.current.error).toBeTruthy();
    });
  });
});

{
  "quick_resume": {
    "current_state": "Implementing",
    "current_task": "FR-02901 実装中 - 機能名",
    "next_actions": ["FR-02901 テスト作成", "FR-02902 実装"],
    "last_updated_at": "2026-02-11T12:00:00+09:00"
  }
}

{
  "progress": {
    "percentage": 40,
    "fr_total": 5,
    "fr_completed": 2,
    "fr_in_progress": 1,
    "details": {
      "FR-02901": { "status": "completed", "files": ["src/features/xxx/types/index.ts"] },
      "FR-02902": { "status": "completed", "files": ["src/features/xxx/api/xxx-api.ts"] },
      "FR-02903": { "status": "in_progress", "files": [] }
    }
  }
}

{
  "quick_resume": {
    "current_state": "Implementing",
    "current_task": "全体実装完了、状態同期待機",
    "next_actions": ["feature-wiring 実行", "feature-status-sync 実行"]
  },
  "progress": {
    "percentage": 100,
    "fr_completed": 5,
    "fr_in_progress": 0
  }
}

# 基本使用 - 機能IDで呼出
/feature-implementer 001

# SPEC パス直接指定
/feature-implementer docs/features/001-code-analysis/SPEC-001-code-analysis.md

# 特定 FR のみ実装
/feature-implementer 001 --fr FR-00101

# テストのみ生成 (実装なし)
/feature-implementer 001 --tests-only

[アイデア]
     |
[feature-architect] → CONTEXT.json 生成
     |
[feature-spec-generator] → SPEC/Screen 生成
     |
[ui-approval-gate] → UI 承認
     |
[feature-implementer] → TDD 実装  ← ここ!
     |
[feature-wiring] → 統合検証
     |
[完了] → コミット & PR

src/features/<feature>/
├── components/          # 機能固有 UI コンポーネント
│   └── <Feature>Panel.tsx
├── hooks/               # 機能固有カスタムフック
│   └── use-<feature>.ts
├── api/                 # API 呼出/データフェッチ
│   └── <feature>-api.ts
├── types/               # 機能固有型定義
│   └── index.ts         # Zod schema + 型
└── index.ts             # バレルファイル (公開 API)

tests/unit/features/<feature>/
├── hooks/
│   └── use-<feature>.test.ts
└── api/
    └── <feature>-api.test.ts