Frontend Technical Spec

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

技術スタックの基本方針

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

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

環境変数管理

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

// ビルドツールの環境変数（公開値のみ。クライアント公開変数は VITE_ 接頭辞が必要）
const config = {
  apiUrl: import.meta.env.VITE_API_URL || 'http://localhost:3000',
  appName: import.meta.env.VITE_APP_NAME || 'My App'
}

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

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

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

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

// セキュリティリスク: 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 は Error Boundary に限り許可（hook の代替が存在しないため）
• 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（型保証済み）

// 型安全なデータフロー
async function fetchUser(id: string): Promise {
  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型として保証
}

ビルドとテスト

package.jsonのpackageManagerフィールドに応じた実行コマンドを使用すること。

ビルドコマンド

• package.jsonから以下に該当するスクリプトを自動検出して実行:
• 開発サーバー
• 本番ビルド
• 型チェック（出力なし）

テストコマンド

• test - テスト実行
• test:coverage - カバレッジ付きテスト実行
• test:coverage:fresh - カバレッジ付きテスト実行（キャッシュクリア）
• test:safe - 安全なテスト実行（自動クリーンアップ付き）
• cleanup:processes - Vitestプロセスのクリーンアップ

品質チェック要件

実装完了時に品質チェックは必須：

Phase 1-3: 基本チェック

• check - Biome（lint + format）
• build - TypeScriptビルド

Phase 4-5: テストと最終確認

• test - テスト実行
• test:coverage:fresh - カバレッジ測定
• check:all - 全体統合チェック

カバレッジ

• カバレッジは目標ではなく未テスト領域を見つける診断シグナルとして扱う（目標化すると自明なテストに歪む — グッドハートの法則）
• 基盤的で再利用度の高いユニット（共有コンポーネント、カスタムフック、utils）にテストの重点を置く。これらはリグレッション時の影響範囲が最も広い。合成度の高い面（organisms、ページ）は統合/E2Eのカバレッジに委ねる
• 強制する数値しきい値はプロジェクトの CI / カバレッジ設定であり、それ自体が目的ではない

非機能要件

• ブラウザ互換性: Chrome/Firefox/Safari/Edge（最新2バージョン）
• レンダリング時間: 主要ページで5秒以内

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: shinpr
• Source: shinpr/ai-coding-project-boilerplate
• License: MIT

Install and usage instructions live in the source repository linked above.