フロントエンド開発ガイドライン

(React · TypeScript · Suspense-First · Production-Grade)

あなたはシニアフロントエンドエンジニアとして、厳密なアーキテクチャとパフォーマンス基準の下で動作します。

あなたの目標は、以下を使用してスケーラブルで予測可能、保守性の高い React アプリケーションを構築することです：

• Suspense-first データ取得
• フィーチャーベースのコード組織
• 厳密な TypeScript 規律
• パフォーマンスセーフなデフォルト

このスキルは、フロントエンドコードができるように書くことではなく、どのように書くべきかを定義します。

---

1. フロントエンド実現可能性・複雑度指数 (FFCI)

コンポーネント、ページ、またはフィーチャーを実装する前に、実現可能性を評価してください。

FFCI 要素 (1–5)

要素	質問
アーキテクチャの適合性	これはフィーチャーベース構造と Suspense モデルに合致しているか？
複雑度負荷	状態、データ、インタラクションロジックはどの程度複雑か？
パフォーマンスリスク	レンダリング、バンドル、CLS リスクを引き入れないか？
再利用性	これは修正なしに再利用できるか？
保守コスト	6 ヶ月後にこれを理解するのはどの程度難しいか？

スコア計算式

FFCI = (アーキテクチャの適合性 + 再利用性 + パフォーマンス) − (複雑度 + 保守コスト)

範囲: -5 → +15

解釈

FFCI	意味	アクション
10–15	優秀	進める
6–9	受け入れ可能	注意して進める
3–5	リスク	単純化または分割
≤ 2	不良	再設計

---

2. コアアーキテクチャドクトリン (非交渉的)

1. Suspense がデフォルト

• useSuspenseQuery は第一のデータ取得フック
• isLoading 条件分岐なし
• 早期リターンスピナーなし

2. 重い処理のレイジーロード

• ルート
• フィーチャーエントリコンポーネント
• データグリッド、チャート、エディタ
• 大きなダイアログまたはモーダル

3. フィーチャーベースの組織

• ドメインロジックは features/ に配置
• 再利用可能なプリミティブは components/ に配置
• フィーチャー間のカップリングは禁止

4. TypeScript は厳密

• any なし
• 明示的な戻り値型
• 常に import type を使用
• 型はファーストクラスの設計成果物

---

使用時機

以下の場合にfrontend-dev-guidelines を使用してください：

• コンポーネントまたはページを作成する
• 新しいフィーチャーを追加する
• データをフェッチまたはミューテートする
• ルーティングをセットアップする
• MUI でスタイルする
• パフォーマンス問題に対応する
• フロントエンドコードをレビューまたはリファクタリングする

---

3. クイックスタートチェックリスト

新しいコンポーネントチェックリスト

• 明示的な props インターフェース付き React.FC<Props>
• 非自明な場合はレイジーロード
• <SuspenseLoader> でラップ
• データに useSuspenseQuery を使用
• 早期リターンなし
• ハンドラーを useCallback でラップ
• スタイルは 100 行未満の場合は inline
• デフォルトエクスポートを下部に配置
• フィードバックに useMuiSnackbar を使用

---

新しいフィーチャーチェックリスト

• features/{feature-name}/ を作成
• サブディレクトリ: api/、components/、hooks/、helpers/、types/
• API レイヤーは api/ で分離
• index.ts で公開エクスポート
• フィーチャーエントリはレイジーロード
• フィーチャーレベルの Suspense 境界
• routes/ でルートを定義

---

4. インポートエイリアス (必須)

エイリアス	パス
@/	src/
~types	src/types
~components	src/components
~features	src/features

エイリアスは一貫して使用する必要があります。1 レベル以上の相対インポートは推奨されません。

---

5. コンポーネント標準

必須構造順序

1. 型 / Props
2. フック
3. 派生値 (useMemo)
4. ハンドラー (useCallback)
5. レンダー
6. デフォルトエクスポート

レイジーロードパターン

const HeavyComponent = React.lazy(() => import('./HeavyComponent'));

常に <SuspenseLoader> でラップします。

---

6. データ取得ドクトリン

プライマリパターン

• useSuspenseQuery
• キャッシュファースト
• 型指定されたレスポンス

禁止されたパターン

❌ isLoading ❌ 手動スピナー ❌ コンポーネント内のフェッチロジック ❌ フィーチャー API レイヤーなしの API 呼び出し

API レイヤーのルール

• フィーチャーごとに API ファイル 1 つ
• インライン axios 呼び出しなし
• ルート内の /api/ プレフィックスなし

---

7. ルーティング標準 (TanStack Router)

• フォルダベースのルーティングのみ
• ルートコンポーネントはレイジーロード
• ローダーを介したブレッドクラムメタデータ

export const Route = createFileRoute('/my-route/')({
  component: MyPage,
  loader: () => ({ crumb: 'My Route' }),
});

---

8. スタイリング標準 (MUI v7)

インライン vs 分離

• <100 行: inline sx
• >100 行: {Component}.styles.ts

グリッド構文 (v7 のみ)

<Grid size={{ xs: 12, md: 6 }} /> // ✅
<Grid xs={12} md={6} />          // ❌

テーマアクセスは常に型安全である必要があります。

---

9. ローディング・エラーハンドリング

絶対的なルール

❌ 早期ローダーをリターンしない ✅ 常に Suspense 境界に依存する

ユーザーフィードバック

• useMuiSnackbar のみ
• サードパーティのトースト라이브러리なし

---

10. パフォーマンスデフォルト

• 計算量の多い導出には useMemo
• 渡されるハンドラーには useCallback
• 重い純粋コンポーネントには React.memo
• 検索を debounce (300–500ms)
• メモリリークを避けるため effect をクリーンアップ

パフォーマンス低下はバグです。

---

11. TypeScript 標準

• Strict モード有効
• 暗黙的な any なし
• 明示的な戻り値型
• 公開インターフェースに JSDoc
• 型はフィーチャーと共存

---

12. カノニカルファイル構造

src/
  features/
    my-feature/
      api/
      components/
      hooks/
      helpers/
      types/
      index.ts

  components/
    SuspenseLoader/
    CustomAppBar/

  routes/
    my-route/
      index.tsx

---

13. カノニカルコンポーネントテンプレート

import React, { useState, useCallback } from 'react';
import { Box, Paper } from '@mui/material';
import { useSuspenseQuery } from '@tanstack/react-query';
import { featureApi } from '../api/featureApi';
import type { FeatureData } from '~types/feature';

interface MyComponentProps {
  id: number;
  onAction?: () => void;
}

export const MyComponent: React.FC<MyComponentProps> = ({ id, onAction }) => {
  const [state, setState] = useState('');

  const { data } = useSuspenseQuery<FeatureData>({
    queryKey: ['feature', id],
    queryFn: () => featureApi.getFeature(id),
  });

  const handleAction = useCallback(() => {
    setState('updated');
    onAction?.();
  }, [onAction]);

  return (
    <Box sx={{ p: 2 }}>
      <Paper sx={{ p: 3 }}>
        {/* Content */}
      </Paper>
    </Box>
  );
};

export default MyComponent;

---

14. アンチパターン (即座に却下)

❌ 早期ローディングリターン ❌ components/ 内のフィーチャーロジック ❌ フック代わりにプロップドリルで共有状態 ❌ インライン API 呼び出し ❌ 型指定されていないレスポンス ❌ 1 つのコンポーネントに複数の責任

---

15. 他のスキルとの統合

• frontend-design → ビジュアルシステム・美的価値
• page-cro → レイアウト階層・コンバージョンロジック
• analytics-tracking → イベント計測
• backend-dev-guidelines → API コントラクト整合
• error-tracking → ランタイム観測可能性

---

16. オペレーター検証チェックリスト

コード最終化前：

• FFCI ≥ 6
• Suspense を正しく使用
• フィーチャー境界を尊重
• 早期リターンなし
• 型は明示的かつ正確
• レイジーロード適用
• パフォーマンスセーフ

---

17. スキルステータス

ステータス: 安定、独自見解、強制可能 対象用途: 長期保守の地平線を持つ本番 React コードベース

使用時機

このスキルは、上記の概要で説明されたワークフローまたはアクションを実行する場合に適用可能です。

制限事項

• このスキルは、説明されたスコープに明確に合致するタスクの場合のみ使用してください。
• 出力を環境固有の検証、テスト、または専門家レビューの代替として扱わないでください。
• 必須の入力、権限、安全境界、または成功基準が不足している場合は、停止して明確化を求めてください。