frontend-dev-guidelines

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

（React・TypeScript・Suspense を中心とした例）

あなたは、厳格なアーキテクチャ基準とパフォーマンス基準に従うシニアフロントエンドエンジニアです。

目標は、以下を活用して、スケーラブルで予測可能、保守しやすい React アプリケーションを構築することです。

• Suspense を最優先とするデータ取得
• フィーチャーベースのコード構成
• 厳格な TypeScript の運用
• パフォーマンスに配慮したデフォルト設定

これらは、MUI/TanStack アプリケーションを例にした規約です。既存のプロジェクト要件とユーザーのスコープを優先し、スタックの移行を強制しないでください。

---

1. フロントエンド実現可能性・複雑性指標（FFCI）

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

FFCI の評価項目（1～5）

評価項目	質問
アーキテクチャとの適合性	フィーチャーベースの構造と Suspense モデルに適合していますか？
複雑性の負荷	状態、データ、インタラクションのロジックはどの程度複雑ですか？
パフォーマンスの安全性	レンダリング、バンドル、または CLS のリスクが生じますか？
再利用性	変更を加えずに再利用できますか？
保守コスト	6 か月後に内容を把握するのはどの程度難しいですか？

スコア計算式

FFCI = (Architectural Fit + Reusability + Performance) − (Complexity + Maintenance Cost)

範囲： -7 → +13

判定

FFCI	意味	対応
10–13	優れている	進める
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 行未満ならインラインでスタイルを記述する
• 末尾にデフォルトエクスポートを置く
• フィードバックに 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）

インラインと分離の使い分け

• <100 lines：インラインの sx
• >100 lines：{Component}.styles.ts

グリッド構文（v7 のみ）

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

テーマへのアクセスは、必ず型安全にする必要があります。

---

9. 読み込みとエラー処理

絶対ルール

❌ ローダーを早期に返さないでください ✅ 常に Suspense 境界を使用してください

ユーザーへのフィードバック

• useMuiSnackbar のみ使用する
• サードパーティーのトーストライブラリは禁止

---

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

• コストの高い派生処理には useMemo を使用する
• 渡すハンドラーには useCallback を使用する
• 重い純粋コンポーネントには React.memo を使用する
• 検索にはデバウンスを適用する（300～500ms）
• メモリリークを防ぐためにエフェクトをクリーンアップする

パフォーマンスのリグレッションはバグです。

---

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 コードベース

使用するタイミング

このスキルは、概要で説明されているワークフローやアクションを実行する場合に適用できます。

制限事項

• このスキルは、タスクが上記の対象範囲に明確に合致する場合にのみ使用してください。
• 出力を、環境固有の検証、テスト、専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、成功基準が不足している場合は、作業を中断して確認を求めてください。

適用の前提条件と制限

SuspenseLoader、LoadingOverlay、useMuiSnackbar、useAuth、apiClient はプロジェクト固有の例であり、実装は同梱されていません。使用する前に用意するか、環境に合わせて調整してください。FFCI は助言を目的とするヒューリスティックであり、検証済みの実現可能性やパフォーマンスの判定基準ではありません。Suspense だけではレイアウトシフトを防げません。対応するフォールバック領域を確保してください。フックが条件にかかわらず呼び出され、読み込み中・エラー・空の状態を処理している場合、通常の useQuery や早期リターンも有効です。メモ化や遅延読み込みの境界は機械的に適用せず、プロファイリングしてください。サーバー側の認可と実行時のレスポンス検証は引き続き必要です。TypeScript はネットワークデータを検証しません。