detailed-design-templates

# 詳細設計テンプレート集 > **参照元**: detailed-design-workflow コマンド --- ## フロントエンド設計書テンプレート 画面を持つ機能には以下の構成で `フロントエンド設計書.md` を作成する。 ```markdown # {機能名} フロントエンド設計書 ## メタ情報 | 項目 | 内容 | |------|------| | ドキュメントID | DETAIL-{機能ID}-FRONTEND-001 | | 親設計書 | [詳細設計書.md](./詳細設計書.md) | --- ## 1. コンポーネント構成 ### 1.1 コンポーネント階層図 ```mermaid graph TD Page["{PageName}Page"] Page --> Container["{Feature}Container"] Container --> Component1["{Component1}"] Container --> Component2["{Component2}"] ``` ### 1.2 コンポーネント一覧 | コンポーネント名 | 種類 | 責務 | Props | |----------------|------|------|-------| | `{Feature}Page` | Page | ルーティング、レイアウト | - | | `{Feature}Container` | Container | 状態管理、API呼び出し | - | | `{Component}` | Presentational | UI表示 | `data`, `onAction` | --- ## 2. 状態管理設計 ### 2.1 状態の種類と管理方針 | 状態 | スコープ | 管理方法 | 永続化 | |------|---------|---------|--------| | ユーザー認証 | グローバル | Zustand/Context | LocalStorage | | フォーム入力 | ローカル | useState/useForm | - | | サーバーデータ | キャッシュ | React Query/SWR | - | ### 2.2 グローバル状態 ```typescript interface {Feature}State { // 状態の型定義 } ``` --- ## 3. カスタムフック設計 | フック名 | 責務 | 引数 | 戻り値 | |---------|------|------|--------| | `use{Feature}` | {機能}のロジック | - | `{ data, isLoading, error }` | | `use{Feature}Mutation` | データ更新 | - | `{ mutate, isPending }` | --- ## 4. API連携設計 ### 4.1 使用エンドポイント | API | メソッド | 用途 | フック | |-----|---------|------|--------| | `/api/xxx` | GET | データ取得 | `use{Feature}Query` | | `/api/xxx` | POST | データ作成 | `use{Feature}Mutation` | ### 4.2 エラーハンドリング | エラーコード | 画面表示 | リカバリ方法 | |------------|---------|-------------| | 400 | バリデーションエラー表示 | フォーム修正を促す | | 401 | ログイン画面へリダイレクト | - | | 500 | エラーメッセージ表示 | リトライボタン | --- ## 5. フォームバリデーション | フィールド | ルール | ライブラリ | エラーメッセージ | |-----------|--------|-----------|-----------------| | email | 必須, メール形式 | zod/yup | メールアドレスを入力してください | --- ## 6. ルーティング設計 | パス | コンポーネント | 認証 | ガード | |-----|--------------|:----:|--------| | `/xxx` | `{Feature}Page` | O | `AuthGuard` | --- ## 7. パフォーマンス考慮 | 最適化項目 | 実装方法 | |-----------|---------| | 不要な再レンダリング防止 | `React.memo`, `useMemo`, `useCallback` | | 遅延読み込み | `React.lazy`, `Suspense` | | 仮想スクロール | `react-virtuoso` (大量データ時) | --- ## 8. テスト方針 | テスト種別 | 対象 | ツール | |-----------|------|--------| | Unit | カスタムフック | Jest, React Testing Library | | Integration | Container + API | MSW | | E2E | ユーザーフロー | Playwright | --- ## 9. 呼び出し元（Integration Points）⚠️ 必須 > **重要**: このセクションがないと Phase 6.6（設計書整合性チェック）で統合漏れを検出できません。 ### 9.1 このコンポーネントを使用する場所 | 呼び出し元 | 使用方法 | 統合Issue | |-----------|---------|----------| | `app/{path}/page.tsx` | `<{FeatureName} />` をレンダリング | #{issue_number} | | `components/layout.tsx` | Navigationから `/{path}` へリンク | #{issue_number} | ### 9.2 ルーティング統合 | パス | ページコンポーネント | 統合確認コマンド | |-----|-------------------|----------------| | `/{path}` | `{Feature}Page` | `grep -r '{Feature}' app/` | ### 9.3 統合確認手順 ```bash # 1. ページが正しく配置されているか ls app/{path}/page.tsx # 2. ナビゲーションからリンクされているか grep -r '/{path}' components/ # 3. 実際にブラウザで動作確認 npm run dev # → http://localhost:3000/{path} にアクセス ``` --- ## 変更履歴 | 日付 | バージョン | 変更内容 | 担当者 | |:---|:---|:---|:---| | YYYY-MM-DD | 1.0.0 | 初版作成 | - | ``` --- ## Issue作成テンプレート ### Epic Issue構成 - 概要 - 関連ドキュメント - スコープ（機能一覧） - 技術スタック - 工数見積もり - 子Issue一覧（**各200行以下**） - ドキュメント更新Issue - 依存関係（Mermaid形式） ### 子Issueテンプレート ```markdown ## 概要 {1-2文で機能を説明} ## 親Issue - Epic: #{epic_issue_number} ## 設計書 - [{設計書名}]({path_to_design_doc}) ## 推定規模 | 項目 | 値 | |------|-----| | コード量 | {XX}行 | | ファイル数 | {N}件 | ## 対象ファイル - `{path/to/file1.rs}` (新規 / 変更) ## 実装内容 - [ ] {実装項目1} - [ ] {実装項目2} ## 呼び出し元（Integration Points）⚠️ 必須 > **重要**: このセクションがないと Phase 6.6（設計書整合性チェック）で統合漏れを検出できません。 ### このモジュールを使用する場所 | 呼び出し元ファイル | 使用方法 | 統合Issue | |------------------|---------|----------| | `{path/to/caller.rs}` | `{ClassName}::{method}()` を呼び出す | #{issue_number} | | `{path/to/cli.rs}` | `{command}` コマンドで使用 | #{issue_number} | ### 統合確認コマンド ```bash # 呼び出し元から実際に参照されているか確認 grep -r '{ModuleName}\|{ClassName}' {caller_path} # CLIコマンドの動作確認（該当する場合） {cli_command} --help {cli_command} {test_args} ``` ### この機能を使用する他のIssue - #{related_issue} - {概要} ## 完了条件 - [ ] 実装完了（200行以下） - [ ] テスト通過 - [ ] レビュー9点以上 - [ ] **呼び出し元からの統合確認** ⚠️ 新規追加 ## 依存 - #{依存するIssue番号} ``` ### ドキュメント更新Issueテンプレート ```markdown ## 概要 {機能名}の実装完了に伴い、関連ドキュメントを更新する。 ## 親Issue - Epic: #{epic_issue_number} ## 対象ドキュメント | ファイル | 更新内容 | 必須/任意 | |----------|---------|----------| | `README.md` | 機能概要、使用例の追記 | 必須 | | `CHANGELOG.md` | 変更履歴の追記 | 必須 | ## 更新内容 - [ ] README.md: 機能概要セクションに{機能名}を追加 - [ ] CHANGELOG.md: バージョン・変更内容・日付を追記 ## 完了条件 - [ ] 全対象ドキュメントが更新されている - [ ] マークダウンの構文エラーがない - [ ] リンク切れがない ## 依存 - 全実装Issue完了後に着手可能 ``` --- ## 依存関係の記述方法 **禁止: ASCII形式** ``` #47 (DB) ─┬─> #48 (Security) ``` **必須: Mermaid形式** ````markdown ```mermaid flowchart LR subgraph 共通基盤 DB["#47 DB (80行)"] SEC["#48 Security (150行)"] end subgraph 機能A A_BE["#49 BE (120行)"] A_FE["#50 FE (100行)"] end DB --> SEC --> A_BE --> A_FE ``` ```` --- ## 画面設計書の記述ルール ### 禁止事項 - ASCII art / テキストベースのワイヤーフレーム - 罫線文字（`┌─┐│└┘`等）を使った図表現 - コードブロック内のUI表現 ### 必須事項 - 視覚表現は**HTMLモックアップ + スクリーンショット画像のみ** - 状態の説明は**表形式**または**箇条書き**で記述 - ワイヤーフレーム定義は **Wireframe DSL（YAML形式）** で記述 --- ## Wireframe DSL スキーマ > **詳細リファレンス**: `wireframe-generator` skill を参照 画面設計書内に ` ```yaml wireframe ` ブロックでYAML定義を記述する。 ### 対応タイプ（概要） | カテゴリ | タイプ例 | |---------|---------| | フォーム系 | `form`, `auth`, `wizard`, `settings` | | 一覧系 | `table`, `card-grid`, `gallery`, `kanban`, `calendar`, `timeline` | | 詳細・ダッシュボード | `detail`, `profile`, `dashboard`, `stats` | | 複合・オーバーレイ | `crud`, `tabs`, `layout`, `modal`, `drawer`, `confirm`, `alert` | | その他 | `empty-state`, `hero`, `pricing`, `faq`, `chat` | ### 生成コマンド ```bash cd .opencode/skill/wireframe-generator/scripts bun install bun run generate.ts <markdown-file> [output-dir] ``` --- ## リバースエンジニアリング設計書テンプレート 既存コードから自動生成する設計書の構成。