Reactコンポーネントの設計指針：AI活用プロンプトの整備

// components/ui/button.tsx の拡張例
const buttonVariants = cva(
  'inline-flex items-center justify-center rounded-md text-sm font-medium',
  {
    variants: {
      variant: {
        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
        destructive: 'bg-destructive text-destructive-foreground',
        // カスタムvariant追加
        success: 'bg-green-600 text-white hover:bg-green-700',
      },
      size: {
        default: 'h-9 px-4 py-2',
        sm: 'h-8 px-3 text-xs',
        lg: 'h-10 px-8',
      },
    },
  }
)

// components/forms/form-field.tsx の例
interface FormFieldProps {
  name: string
  label: string
  error?: string
  children: React.ReactNode
}

export function FormField({ name, label, error, children }: FormFieldProps) {
  const id = `field-${name}`
  const errorId = `${id}-error`

  return (
    <div className="space-y-2">
      <label htmlFor={id} className="text-sm font-medium">
        {label}
      </label>
      {children}
      {error && (
        <p id={errorId} className="text-sm text-destructive">
          {error}
        </p>
      )}
    </div>
  )
}

4.3 Layout Components

責務: ページのレイアウト構造を定義します。ビジネスロジックを持たず、配置のみを担当します。

設計ポイント:

• 基本的にServer Componentとして実装します
• childrenを活用してClient Componentを受け入れます
• レスポンシブデザインに対応してください
• 適切な位置にSuspense境界を配置してください

// components/layouts/sidebar.tsx の例
interface SidebarProps {
  children: React.ReactNode
}

export function Sidebar({ children }: SidebarProps) {
  return (
    <aside className="w-64 border-r bg-muted/40 p-4">
      <nav className="space-y-2">
        {children}
      </nav>
    </aside>
  )
}

4.4 Shared Components

責務: アプリ全体で再利用される共通コンポーネントです。軽いロジックは含めますが、特定機能に依存しません。

設計ポイント:

• 特定のfeatureに依存しないようにしてください
• Propsで必要なデータを受け取る設計にしてください
• Server/Client境界は用途に応じて判断してください

// components/shared/user-avatar.tsx の例
interface UserAvatarProps {
  name: string
  imageUrl?: string
  size?: 'sm' | 'md' | 'lg'
}

export function UserAvatar({ name, imageUrl, size = 'md' }: UserAvatarProps) {
  const sizeClasses = {
    sm: 'h-8 w-8',
    md: 'h-10 w-10',
    lg: 'h-12 w-12',
  }

  return (
    <div className={cn('rounded-full bg-muted', sizeClasses[size])}>
      {imageUrl ? (
        <img src={imageUrl} alt={name} className="rounded-full" />
      ) : (
        <span>{name.charAt(0).toUpperCase()}</span>
      )}
    </div>
  )
}

4.5 Feature Components

責務: 特定機能のビジネスロジックを含むコンポーネントです。API呼び出し、状態管理、業務処理を担当します。

設計ポイント:

• features/{機能名}/components/に配置してください
• 状態管理戦略を明確に決定してください
• Server Actionsを活用してミューテーションを実装してください
• エラーハンドリングを適切に行ってください

// features/users/components/user-profile.tsx の例
'use client'

import { useSuspenseQuery } from '@tanstack/react-query'
import { useUser } from '../hooks/use-user'

export function UserProfile({ userId }: { userId: string }) {
  const { user } = useUser(userId)

  return (
    <div className="space-y-4">
      <h2 className="text-xl font-bold">{user.name}</h2>
      <p className="text-muted-foreground">{user.email}</p>
    </div>
  )
}

4.6 Route Components

責務: Next.js App Routerのルーティングに対応するコンポーネントです。ページの構成とデータフェッチを担当します。

設計ポイント:

• 基本的にServer Componentとして実装してください
• async/awaitで直接データフェッチを行ってください
• loading.tsxとerror.tsxを配置してください
• generateMetadataでSEO対応してください

// app/users/[id]/page.tsx の例
import { Suspense } from 'react'
import { UserProfile } from '@/features/users/components/user-profile'
import { UserProfileSkeleton } from '@/features/users/components/user-profile-skeleton'

interface Props {
  params: { id: string }
}

export default function UserPage({ params }: Props) {
  return (
    <main className="container py-8">
      <Suspense fallback={<UserProfileSkeleton />}>
        <UserProfile userId={params.id} />
      </Suspense>
    </main>
  )
}

export async function generateMetadata({ params }: Props) {
  const user = await fetchUser(params.id)
  return { title: `${user.name}のプロフィール` }
}

5. Server/Client Component判定

コンポーネント作成時は、必ずServer/Client境界を判定してください。

判定基準

境界設計のベストプラクティス

Client Componentは最小の葉に限定し、Server Componentで可能な限りラップしてください。

// ✅ 良い例：Server ComponentでClient Componentをラップ
// app/dashboard/page.tsx (Server Component)
async function DashboardPage() {
  const data = await fetchDashboardData()

  return (
    <div className="grid gap-4">
      {/* 静的な部分はServer Componentで */}
      <StatsCards data={data.stats} />

      {/* インタラクティブな部分のみClient Component */}
      <InteractiveChart data={data.chartData} />
    </div>
  )
}

6. 状態管理戦略

状態の種類に応じて適切なツールを選択してください。

7. View層とFoundation層の関係

コンポーネントは大きくView層とFoundation層に分かれます。データフローは一方向（View → Foundation）を維持してください。

8. コンポーネントの分離設計：AIへの依頼プロンプト

要件をもとに、コンポーネント分類を自動で行うAIプロンプトを整備しています。

AIは、必要となる各コンポーネントの一覧と、さらにその後続のコンポーネント作成に必要となるAIへの依頼プロンプトを出力します。

プロンプト使用時は、「## インプット情報」の{}で囲まれた箇所を具体的な要件に置換してからAIに投入します。コンポーネントの分離設計は複雑タスクですので、使用できる最上級の高級LLMモデルの使用を推奨します。

AI_request_prompt

9. AIの応答サンプル

ECサイト管理画面の注文管理機能について、ワイヤーフレームと機能要件からReact/Next.js App Router向けのコンポーネント分離設計をAIに依頼したサンプルです。Claude Codeでの試行結果を添付しています。

AI_request_sample1_ClaudeCode

AI_response_sample

まとめ

本ガイドラインの核心は「責務に基づく6カテゴリ分類」と「Server/Client境界の最小化」です。画面仕様書を受け取ったら、まず全コンポーネントを洗い出して分類し、View層（Feature/Route）にビジネスロジックを集約、Foundation層（UI/Form/Layout/Shared）はProps経由の純粋な表示に徹することで、保守性と再利用性を両立させましょう。迷ったときは判定フローに立ち返り、チェックリストで漏れを防ぐことが品質担保の鍵となります。

Appendix：前提技術スタック