frontend-technical-spec

フロントエンドの環境変数、コンポーネント設計、データフローを定義。React環境設定時に使用。

Stars 195

Forks 19

Install this agent skill to your Project

npx add-skill https://github.com/shinpr/ai-coding-project-boilerplate/tree/main/.claude/skills-ja/frontend-technical-spec

SKILL.md

技術設計ルール（フロントエンド）

技術スタックの基本方針

TypeScriptベースのReactアプリケーション実装。アーキテクチャパターンはプロジェクトの要件と規模に応じて選択する。

環境変数管理とセキュリティ

環境変数管理

ビルドツールの環境変数システムを使用: process.envはブラウザ環境で動作しない
設定レイヤーを通じて環境変数を一元管理
TypeScriptによる適切な型安全性の実装
デフォルト値設定と必須チェックの適切な実装

typescript

// ビルドツールの環境変数（公開値のみ）
const config = {
  apiUrl: import.meta.env.API_URL || 'http://localhost:3000',
  appName: import.meta.env.APP_NAME || 'My App'
}

// フロントエンドでは動作しない
const apiUrl = process.env.API_URL // NG

セキュリティ（クライアントサイド制約）

重要: すべてのフロントエンドコードは公開され、ブラウザで見える
クライアントサイドに秘密情報を保存しない: APIキー、トークン、シークレットを環境変数に含めない
.envファイルをGitに含めない（バックエンドと同様）
機密情報のログ出力を禁止（パスワード、トークン、個人情報）
エラーメッセージに機密情報を含めない

秘密情報の正しい取り扱い:

typescript

// セキュリティリスク: APIキーがブラウザで露出
const apiKey = import.meta.env.VITE_API_KEY
const response = await fetch(`https://api.example.com/data?key=${apiKey}`)

// 正しい: バックエンドが秘密情報を管理、フロントエンドはプロキシ経由でアクセス
const response = await fetch('/api/data') // バックエンドがAPIキー認証を処理

アーキテクチャ設計

フロントエンドアーキテクチャパターン

Reactコンポーネントアーキテクチャ:

Function Components: 必須、class componentsは非推奨
Custom Hooks: ロジック再利用と依存性注入のため
コンポーネント階層: Atoms → Molecules → Organisms → Templates → Pages
Props-driven: コンポーネントは必要なすべてのデータをPropsで受け取る
Co-location: テスト、スタイル、関連ファイルをコンポーネントと同じ場所に配置

状態管理パターン:

Local State: コンポーネント固有の状態にはuseState
Context API: コンポーネントツリー全体で状態を共有（テーマ、認証等）
Custom Hooks: 状態ロジックと副作用をカプセル化
Server State: APIデータのキャッシュにはReact QueryまたはSWR

データフロー統一原則

クライアントサイドのデータフロー

Reactアプリケーション全体で一貫したデータフローを維持：

Single Source of Truth: 各状態には1つの権威あるソースがある
- UI状態: コンポーネントStateまたはContext
- サーバーデータ: React Query/SWRでキャッシュされたAPIレスポンス
- フォームデータ: React Hook Formを使ったControlled Components

単方向フロー: データはPropsを通じて上から下へ流れる

APIレスポンス → State → Props → Render → UI
ユーザー入力 → イベントハンドラ → State更新 → 再レンダリング

Immutable Updates: State更新には不変パターンを使用

typescript

// 不変なState更新
setUsers(prev => [...prev, newUser])

// 可変なState更新（禁止）
users.push(newUser)
setUsers(users)

データフローにおける型安全性

Frontend → Backend: Props/State（型保証済み） → APIリクエスト（シリアライゼーション）
Backend → Frontend: APIレスポンス（unknown） → 型ガード → State（型保証済み）

typescript

// 型安全なデータフロー
async function fetchUser(id: string): Promise<User> {
  const response = await fetch(`/api/users/${id}`)
  const data: unknown = await response.json()

  if (!isUser(data)) {
    throw new Error('Invalid user data')
  }

  return data // User型として保証
}