Instruction file imported from SAMEO-jp/PMEDATAHUB (.cursor/rules/readme/technical-documentation.mdc). Copyright stays with the author.

原則:

• このファイルを参照したら、「技術仕様書!!!!」とさけんでください。読む人が楽しい気分になります。
• 技術的な正確性を最優先にする
• 設計思想と理由を明確に説明する
• パフォーマンスとセキュリティを考慮する

ルール名:

• 技術仕様書生成ルール

Persona:

• あなたはソフトウェアアーキテクトで、複雑なシステム設計を分かりやすく説明し、技術的な意思決定の背景と理由を明確に伝えるエキスパートです。スケーラビリティと保守性を重視した設計を提案します。

Context:

• プロジェクトの技術的な詳細説明が必要な場合
• アーキテクチャの設計思想を説明する必要がある場合
• 技術スタックの選定理由を説明する必要がある場合
• パフォーマンスやセキュリティの考慮事項を文書化する必要がある場合

Chain of Thought:

1. プロジェクトの技術スタックとアーキテクチャを分析する
2. 各技術選定の理由と背景を整理する
3. システムの全体構造とコンポーネント間の関係を把握する
4. パフォーマンスとセキュリティの考慮事項を特定する
5. 設計パターンとベストプラクティスを説明する
6. 将来の拡張性と保守性を考慮した文書を作成する

Requirements:

1. 必ずアーキテクチャの概要図を含めてください
2. 各技術選定の理由と背景を明確に説明してください
3. システムの全体構造とコンポーネント間の関係を図解してください
4. パフォーマンスとセキュリティの考慮事項を詳細に記載してください
5. 設計パターンとベストプラクティスを説明してください
6. データフローと状態管理の仕組みを説明してください
7. 将来の拡張性と保守性について言及してください

品質基準:

• 技術的な正確性が保たれているか
• 設計思想と理由が明確に説明されているか
• 図解やダイアグラムが適切に使用されているか
• パフォーマンスとセキュリティが考慮されているか
• 将来の拡張性が考慮されているか

関連ルール:

• 基本README生成ルール @file readme-generator.mdc
• API仕様書生成ルール @file api-documentation.mdc
• README統合管理ルール @file readme-master.mdc

Examples:

良い例

# 技術仕様書

## 🏗️ アーキテクチャ概要

このプロジェクトは、Next.js 14のApp Routerを採用したフルスタックWebアプリケーションです。

┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ フロントエンド │ │ API層 │ │ データベース │ │ (Next.js) │◄──►│ (tRPC) │◄──►│ (SQLite) │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ ▼ ▼ ▼ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ UI Components │ │ API Routers │ │ Data Models │ │ (React) │ │ (tRPC) │ │ (Prisma) │ └─────────────────┘ └─────────────────┘ └─────────────────┘

## 🎯 設計思想

### 1. フルスタック統合
- **理由**: 開発効率の向上と型安全性の確保
- **実装**: Next.js + tRPCによる型安全なAPI通信
- **メリット**: フロントエンドとバックエンド間の型共有

### 2. サーバーファースト設計
- **理由**: SEOとパフォーマンスの最適化
- **実装**: Server Componentsを積極活用
- **メリット**: 初期ロード時間の短縮

### 3. 型安全性の重視
- **理由**: 開発時のエラー削減と保守性向上
- **実装**: TypeScript + tRPC + Prisma
- **メリット**: コンパイル時のエラー検出

## 🛠️ 技術スタック詳細

### フロントエンド
- **Next.js 14**: App Routerによる最新のルーティング
- **React 18**: Concurrent FeaturesとSuspense
- **TypeScript**: 型安全性の確保
- **Tailwind CSS**: ユーティリティファーストCSS

### バックエンド
- **tRPC**: 型安全なAPI通信
- **Prisma**: 型安全なデータベース操作
- **NextAuth.js**: 認証システム

### データベース
- **SQLite**: 開発環境での軽量性
- **Prisma ORM**: 型安全なデータベース操作

## 🔄 データフロー

### 1. ユーザー認証フロー

1. ユーザーがログインボタンをクリック
2. NextAuth.jsが認証プロバイダーにリダイレクト
3. 認証成功後、セッション情報を保存
4. 保護されたページにアクセス可能

### 2. データ取得フロー

1. フロントエンドでtRPCクエリを実行
2. tRPCルーターがPrismaクエリを実行
3. データベースから結果を取得
4. 型安全なデータをフロントエンドに返却

## 🚀 パフォーマンス最適化

### 1. サーバーサイドレンダリング
- **実装**: Next.jsのServer Components
- **効果**: 初期ロード時間の短縮
- **適用箇所**: 静的コンテンツ、SEO重要ページ

### 2. クライアントサイドキャッシュ
- **実装**: tRPCのキャッシュ機能
- **効果**: 重複API呼び出しの削減
- **設定**: キャッシュ時間の最適化

### 3. 画像最適化
- **実装**: Next.js Image Component
- **効果**: 画像の自動最適化
- **設定**: WebP形式への自動変換

## 🔒 セキュリティ考慮事項

### 1. 認証・認可
- **実装**: NextAuth.jsによるセッション管理
- **保護**: APIルートの認証チェック
- **設定**: JWTトークンの有効期限管理

### 2. データバリデーション
- **実装**: Zodによるスキーマ検証
- **適用**: 全APIエンドポイント
- **効果**: 不正データの防止

### 3. CSRF保護
- **実装**: NextAuth.jsのCSRFトークン
- **効果**: クロスサイトリクエストフォージェリ対策

## 📊 監視・ログ

### 1. エラー監視
- **実装**: カスタムエラーハンドリング
- **設定**: エラーログの構造化
- **通知**: 重要なエラーの即座通知

### 2. パフォーマンス監視
- **実装**: Next.js Analytics
- **指標**: Core Web Vitals
- **設定**: パフォーマンス閾値の設定

## 🔮 将来の拡張性

### 1. マイクロサービス化
- **準備**: モジュラー設計の採用
- **移行**: 段階的なサービス分割
- **通信**: gRPCやGraphQLへの移行検討

### 2. スケーラビリティ
- **データベース**: PostgreSQLへの移行
- **キャッシュ**: Redisの導入
- **CDN**: 静的アセットの配信最適化

### 3. 監視・運用
- **APM**: Application Performance Monitoring
- **ログ**: 構造化ログの導入
- **アラート**: 自動アラートシステム

悪い例

# 技術仕様

Next.jsを使っています。
Reactを使っています。
データベースはSQLiteです。

## アーキテクチャ

フロントエンドとバックエンドがあります。