cursor-sdd 1.0.11 → 1.0.14

package/new/rules/design-principles.md

@@ -0,0 +1,182 @@
+# 技術設計ルールと原則
+
+## コア設計原則
+
+### 1. 型安全は必須
+- TypeScriptインターフェースで `any` 型を**絶対に使わない**
+- すべてのパラメータと戻り値に明示的な型を定義
+- エラーハンドリングにはDiscriminated Unionを使用
+- ジェネリック制約を明確に指定
+
+### 2. 設計 vs 実装
+- **HOWではなくWHATに焦点**
+- コードではなく、インターフェースとコントラクトを定義
+- 事前/事後条件で振る舞いを指定
+- アルゴリズムではなく、アーキテクチャ決定を文書化
+
+### 3. ビジュアルコミュニケーション
+- **シンプルな機能**: 基本的なコンポーネント図またはなし
+- **中程度の複雑さ**: アーキテクチャ + データフロー
+- **高い複雑さ**: 複数の図（アーキテクチャ、シーケンス、状態）
+- **常に純粋なMermaid**: スタイリングなし、構造のみ
+
+### 4. コンポーネント設計ルール
+- **単一責任**: コンポーネントごとに1つの明確な目的
+- **明確な境界**: 明示的なドメイン所有権
+- **依存方向**: アーキテクチャレイヤーに従う
+- **インターフェース分離**: 最小限で焦点を絞ったインターフェース
+- **チーム安全なインターフェース**: マージ競合なしに並列実装を可能にする境界設計
+- **調査トレーサビリティ**: 境界決定とその根拠を `research.md` に記録
+
+### 5. データモデリング標準
+- **ドメインファースト**: ビジネス概念から開始
+- **整合性境界**: 明確な集約ルート
+- **正規化**: パフォーマンスと整合性のバランス
+- **進化**: スキーマ変更を計画
+
+### 6. エラーハンドリング哲学
+- **フェイルファスト**: 早期に明確に検証
+- **グレースフルデグラデーション**: 完全な失敗より部分的な機能
+- **ユーザーコンテキスト**: アクション可能なエラーメッセージ
+- **オブザーバビリティ**: 包括的なロギングとモニタリング
+
+### 7. 統合パターン
+- **疎結合**: 依存を最小化
+- **コントラクトファースト**: 実装前にインターフェースを定義
+- **バージョニング**: API進化を計画
+- **べき等性**: リトライ安全に設計
+- **コントラクト可視性**: APIとイベントコントラクトを design.md に表示し、`research.md` からの詳細にリンク
+
+## ドキュメント標準
+
+### 言語とトーン
+- **宣言的**: 「システムはユーザーを認証する」であり「システムはユーザーを認証すべき」ではない
+- **正確**: 曖昧な説明より具体的な技術用語
+- **簡潔**: 本質的な情報のみ
+- **フォーマル**: プロフェッショナルな技術文書
+
+### 構造要件
+- **階層的**: 明確なセクション構成
+- **トレーサブル**: 要件からコンポーネントへのマッピング
+- **完全**: 実装に必要なすべての側面をカバー
+- **一貫性**: 全体で統一された用語
+- **焦点を絞る**: design.md はアーキテクチャとコントラクトに集中。調査ログや長い比較は `research.md` に移動
+
+## セクション作成ガイダンス
+
+### 全体の順序
+- デフォルトフロー: 概要 → 目標/非目標 → 要件トレーサビリティ → アーキテクチャ → 技術スタック → システムフロー → コンポーネント & インターフェース → データモデル → オプションセクション
+- チームはトレーサビリティを前に移動したり、データモデルをアーキテクチャの近くに配置したりして明確さを改善できるが、セクション見出しは維持する
+- 各セクション内で **サマリー → スコープ → 決定 → 影響/リスク** の順序に従い、レビュアーが一貫してスキャンできるようにする
+
+### 要件ID
+- 要件は `2.1, 2.3` のようにプレフィックスなしで参照（「Requirement 2.1」ではない）
+- すべての要件には数値IDが必要。要件に数値IDがない場合、続行前に `requirements.md` を修正する
+- `N.M` 形式の数値IDを使用。`N` は requirements.md のトップレベル要件番号（例: Requirement 1 → 1.1, 1.2; Requirement 2 → 2.1, 2.2）
+- すべてのコンポーネント、タスク、トレーサビリティ行で同じ正規の数値IDを参照
+
+### 技術スタック
+- この機能に影響を受けるレイヤーのみを含める（フロントエンド、バックエンド、データ、メッセージング、インフラ）
+- 各レイヤーでツール/ライブラリ + バージョン + 役割を指定。詳細な根拠、比較、ベンチマークは `research.md` に
+- 既存システムを拡張する場合、現在のスタックからの逸脱を強調し、新しい依存関係をリスト
+
+### システムフロー
+- 振る舞いを明確にする場合のみ図を追加:
+  - **シーケンス**: マルチステップのインタラクション
+  - **プロセス/状態**: 分岐ルールまたはライフサイクル
+  - **データ/イベント**: パイプラインまたは非同期パターン
+- 常に純粋なMermaidを使用。複雑なフローがない場合、セクション全体を省略
+
+### 要件トレーサビリティ
+- 標準テーブル（`Requirement | Summary | Components | Interfaces | Flows`）を使用してカバレッジを証明
+- 単一の要件が1:1でコンポーネントにマップされる場合のみ、箇条書き形式に簡略化
+- シンプルなマッピングにはコンポーネントサマリーテーブルを優先。複雑またはコンプライアンス重視の要件には完全なトレーサビリティテーブルを使用
+- 要件やコンポーネントが変更されるたびにこのマッピングを再実行してドリフトを防ぐ
+
+### コンポーネント & インターフェース作成
+- コンポーネントをドメイン/レイヤーでグループ化し、コンポーネントごとに1ブロックを提供
+- コンポーネント、ドメイン、意図、要件カバレッジ、主要な依存関係、選択されたコントラクトをリストするサマリーテーブルから始める
+- テーブルフィールド: Intent（1行）、Requirements（`2.1, 2.3`）、Owner/Reviewers（オプション）
+- 依存関係テーブルは各エントリを Inbound/Outbound/External としてマークし、Criticality（`P0` ブロッキング、`P1` 高リスク、`P2` 情報提供）を割り当てる
+- 外部依存関係調査のサマリーはここに。詳細な調査（APIシグネチャ、レート制限、移行ノート）は `research.md` に
+- design.md は自己完結したレビュアー向け成果物でなければならない。`research.md` は背景としてのみ参照し、結論や決定はここに記載
+- コントラクト: 関連するタイプのみをチェック（Service/API/Event/Batch/State）。チェックされていないタイプは後のコンポーネントセクションに表示しない
+- サービスインターフェースはメソッドシグネチャ、入出力、エラーエンベロープを宣言。API/Event/Batchコントラクトはトリガー、ペイロード、配信、べき等性をカバーするスキーマテーブルまたは箇条書きが必要
+- **統合 & 移行ノート**、**バリデーションフック**、**オープンクエスチョン / リスク** を使用してロールアウト戦略、オブザーバビリティ、未解決の決定を文書化
+- 詳細密度ルール:
+  - **フルブロック**: 新しい境界を導入するコンポーネント（ロジックフック、共有サービス、外部統合、データレイヤー）
+  - **サマリーのみ**: 新しい境界のないプレゼンテーショナル/UIコンポーネント（必要に応じて短い実装ノート付き）
+- 実装ノートは統合 / バリデーション / リスクを単一の箇条書きサブセクションに統合して重複を減らす
+- 短いデータ（依存関係、コントラクト選択）にはリストまたはインライン記述子を優先。テーブルは複数項目を比較する場合のみ使用
+
+### 共有インターフェース & Props
+- 繰り返しのUIコンポーネント用にベースインターフェース（例: `BaseUIPanelProps`）を定義し、差分のみをキャプチャするためにコンポーネントごとに拡張
+- 新しいコントラクトを導入するフック、ユーティリティ、統合アダプターには完全なTypeScriptシグネチャを含める
+- ベースコントラクトを再利用する場合、コードブロックを複製する代わりに明示的に参照（例: 「`BaseUIPanelProps` を `onSubmitAnswer` コールバックで拡張」）
+
+### データモデル
+- ドメインモデルは集約、エンティティ、値オブジェクト、ドメインイベント、不変条件をカバー。関係が非自明な場合のみMermaid図を追加
+- 論理データモデルは構造、インデックス、シャーディング、変更に関連するストレージ固有の考慮事項（イベントストア、KV/ワイドカラム）を明確にする
+- データコントラクト & 統合セクションは、機能が境界を越える場合のAPIペイロード、イベントスキーマ、クロスサービス同期パターンを文書化
+- 長い型定義やベンダー固有のオプションオブジェクトは design.md 内の補足参照セクションに配置し、関連セクションからリンク。調査ノートは `research.md` に
+- 補足参照の使用はオプション。メインボディにコンテンツを残すと可読性が低下する場合のみ作成。すべての決定はメインセクションに表示し、design.md が単独で成立するようにする
+
+### エラー/テスト/セキュリティ/パフォーマンスセクション
+- 機能固有の決定や逸脱のみを記録。ベースラインプラクティスについては組織全体の標準（ステアリング）にリンクまたは参照
+
+### 図とテキストの重複排除
+- 図の内容を文章で逐語的に繰り返さない。テキストは、ビジュアルから明らかでない主要な決定、トレードオフ、影響を強調するために使用
+- 決定が図の注釈で完全にキャプチャされている場合、短い「主要な決定」箇条書きで十分
+
+### 一般的な重複排除
+- 概要、アーキテクチャ、コンポーネント間で同じ情報を繰り返さない。コンテキストが同じ場合は以前のセクションを参照
+- 要件/コンポーネントの関係がサマリーテーブルでキャプチャされている場合、追加のニュアンスがない限り他で書き直さない
+
+## 図ガイドライン
+
+### 図を含めるタイミング
+- **アーキテクチャ**: 3つ以上のコンポーネントまたは外部システムが相互作用する場合に構造図を使用
+- **シーケンス**: コール/ハンドシェイクが複数ステップにまたがる場合にシーケンス図を描く
+- **状態 / フロー**: 複雑な状態マシンまたはビジネスフローを専用の図でキャプチャ
+- **ER**: 非自明なデータモデルにエンティティ関係図を提供
+- **スキップ**: 軽微な単一コンポーネントの変更には通常図は不要
+
+### Mermaid要件
+```mermaid
+graph TB
+    Client --> ApiGateway
+    ApiGateway --> ServiceA
+    ApiGateway --> ServiceB
+    ServiceA --> Database
+```
+
+- **純粋なMermaidのみ** – カスタムスタイリングやサポートされていない構文を避ける
+- **ノードID** – 英数字とアンダースコアのみ（例: `Client`, `ServiceA`）。`@`, `/`, または先頭の `-` は使用しない
+- **ラベル** – シンプルな単語。括弧 `()`, 角括弧 `[]`, 引用符 `"`, スラッシュ `/` を埋め込まない
+  - ❌ `DnD[@dnd-kit/core]` → 無効なID（`@`）
+  - ❌ `UI[KanbanBoard(React)]` → 無効なラベル（`()`）
+  - ✅ `DndKit[dnd-kit core]` → ラベルにはプレーンテキストを使用し、技術詳細は付随する説明に記載
+  - ℹ️ Mermaid strict-mode は `Expecting 'SQE' ... got 'PS'` のようなエラーで失敗する。レンダリング前にラベルから句読点を削除
+- **エッジ** – データまたは制御フローの方向を示す
+- **グループ** – Mermaid subgraph を使用して関連コンポーネントをクラスタリングすることは許可。明確さのために控えめに使用
+
+## 品質メトリクス
+### 設計完全性チェックリスト
+- すべての要件に対応
+- 実装詳細の漏れなし
+- 明確なコンポーネント境界
+- 明示的なエラーハンドリング
+- 包括的なテスト戦略
+- セキュリティを考慮
+- パフォーマンス目標を定義
+- 移行パスが明確（該当する場合）
+
+### 避けるべき一般的なアンチパターン
+❌ 設計と実装の混在
+❌ 曖昧なインターフェース定義
+❌ 欠落したエラーシナリオ
+❌ 無視された非機能要件
+❌ 過度に複雑なアーキテクチャ
+❌ コンポーネント間の密結合
+❌ データ整合性戦略の欠如
+❌ 不完全な依存関係分析

package/new/rules/design-review.md

@@ -0,0 +1,110 @@
+# 設計レビュープロセス
+
+## 目的
+技術設計ドキュメントのインタラクティブな品質レビューを実施し、許容可能なリスクで実装に進むのに十分堅牢であることを確認する。
+
+## レビュー哲学
+- **品質保証であり、完璧の追求ではない**
+- **クリティカルフォーカス**: 最も重要な懸念事項を3つに限定
+- **インタラクティブな対話**: 一方的な評価ではなく、設計者との対話
+- **バランスの取れた評価**: 長所と短所の両方を認識
+- **明確な決定**: 根拠付きの明確なGO/NO-GO
+
+## スコープ & 非目標
+
+- スコープ: プロジェクトコンテキストと標準に対して設計ドキュメントの品質を評価し、GO/NO-GOを決定
+- 非目標: 実装レベルの設計、深い技術調査、技術選択の最終決定は行わない。そのような項目は設計フェーズのイテレーションに延期
+
+## コアレビュー基準
+
+### 1. 既存アーキテクチャとの整合（クリティカル）
+- 既存システム境界とレイヤーとの統合
+- 確立されたアーキテクチャパターンとの一貫性
+- 適切な依存方向と結合管理
+- 現在のモジュール構成との整合
+
+### 2. 設計の一貫性と標準
+- プロジェクトの命名規則とコード標準への準拠
+- 一貫したエラーハンドリングとロギング戦略
+- 統一された設定と依存関係管理
+- 確立されたデータモデリングパターンとの整合
+
+### 3. 拡張性と保守性
+- 将来の要件に対する設計の柔軟性
+- 関心の明確な分離と単一責任
+- テスタビリティとデバッグの考慮
+- 要件に対する適切な複雑さ
+
+### 4. 型安全とインターフェース設計
+- 適切な型定義とインターフェースコントラクト
+- 安全でないパターンの回避（例: TypeScriptでの `any`）
+- 明確なAPI境界とデータ構造
+- 入力バリデーションとエラーハンドリングのカバレッジ
+
+## レビュープロセス
+
+### ステップ1: 分析
+すべてのレビュー基準に対して設計を分析し、統合、保守性、複雑さ、要件充足に影響するクリティカルな問題に焦点を当てる。
+
+### ステップ2: クリティカルな問題を特定（≤3）
+各問題について:
+```
+🔴 **クリティカルな問題 [1-3]**: [簡潔なタイトル]
+**懸念**: [具体的な問題]
+**影響**: [なぜ重要か]
+**提案**: [具体的な改善案]
+**トレーサビリティ**: [requirements.mdの要件ID/セクション]
+**根拠**: [設計ドキュメントのセクション/見出し]
+```
+
+### ステップ3: 長所を認識
+バランスの取れたフィードバックを維持するため、1〜2つの強い側面を認める。
+
+### ステップ4: GO/NO-GOの決定
+- **GO**: クリティカルなアーキテクチャ不整合なし、要件対応済み、明確な実装パス、許容可能なリスク
+- **NO-GO**: 根本的な競合、クリティカルなギャップ、高い失敗リスク、不釣り合いな複雑さ
+
+## トレーサビリティと根拠
+
+- 各クリティカルな問題を `requirements.md` の関連要件（IDまたはセクション）にリンク
+- 評価を裏付ける設計ドキュメント内の根拠箇所（セクション/見出し、図、成果物）を引用
+- 該当する場合、問題を正当化するためにステアリングコンテキストからの制約を参照
+
+## 出力フォーマット
+
+### 設計レビューサマリー
+全体的な品質と準備状況について2〜3文。
+
+### クリティカルな問題（≤3）
+各項目: 問題、影響、推奨事項、トレーサビリティ（例: 1.1, 1.2）、根拠（design.mdセクション）。
+
+### 設計の長所
+1〜2つのポジティブな側面。
+
+### 最終評価
+決定（GO/NO-GO）、根拠（1〜2文）、次のステップ。
+
+### インタラクティブディスカッション
+設計者の視点、代替案、明確化、必要な変更について対話。
+
+## 長さとフォーカス
+
+- サマリー: 2〜3文
+- 各クリティカルな問題: 合計5〜7行（問題/影響/推奨事項/トレーサビリティ/根拠を含む）
+- 全体のレビュー: 簡潔に（目安約400語）
+
+## レビューガイドライン
+
+1. **クリティカルフォーカス**: 成功に大きく影響する問題のみをフラグ
+2. **建設的なトーン**: 批判だけでなく解決策を提供
+3. **インタラクティブなアプローチ**: 一方的な評価ではなく対話を行う
+4. **バランスの取れた評価**: 長所と短所の両方を認識
+5. **明確な決定**: 明確なGO/NO-GO推奨を行う
+6. **アクション可能なフィードバック**: すべての提案が実装可能であることを確認
+
+## 最終チェックリスト
+
+- **クリティカルな問題 ≤ 3** かつ各問題に影響と推奨事項を含む
+- **トレーサビリティ**: 各問題が要件ID/セクションを参照
+- **根拠**: 各問題が設計ドキュメントの場所を引用
+- **決定**: 明確な根拠と次のステップを伴うGO/NO-GO

package/new/rules/ears-format.md

@@ -0,0 +1,49 @@
+# EARSフォーマットガイドライン
+
+## 概要
+EARS（Easy Approach to Requirements Syntax）は、仕様駆動開発における受け入れ基準の標準フォーマット。
+
+EARSパターンは要件の論理構造（条件 + 主体 + 応答）を記述し、特定の自然言語に縛られない。
+すべての受け入れ基準は、仕様で設定されたターゲット言語（例: `spec.json.language` / `ja`）で記述すること。
+EARSのトリガーキーワードと固定フレーズは英語のまま（`When`, `If`, `While`, `Where`, `The system shall`, `The [system] shall`）とし、可変部分（`[event]`, `[precondition]`, `[trigger]`, `[feature is included]`, `[response/action]`）のみターゲット言語にローカライズする。トリガーや固定英語フレーズの中にターゲット言語のテキストを混ぜないこと。
+
+## 主要なEARSパターン
+
+### 1. イベント駆動型要件
+- **パターン**: When [event], the [system] shall [response/action]
+- **ユースケース**: 特定のイベントやトリガーへの応答
+- **例**: When ユーザーがチェックアウトボタンをクリック, the Checkout Service shall カート内容を検証
+
+### 2. 状態駆動型要件
+- **パターン**: While [precondition], the [system] shall [response/action]
+- **ユースケース**: システム状態や前提条件に依存する振る舞い
+- **例**: While 支払い処理中, the Checkout Service shall ローディングインジケーターを表示
+
+### 3. 望ましくない振る舞いへの要件
+- **パターン**: If [trigger], the [system] shall [response/action]
+- **ユースケース**: エラー、障害、望ましくない状況へのシステム応答
+- **例**: If 無効なクレジットカード番号が入力された, then the website shall エラーメッセージを表示
+
+### 4. オプション機能要件
+- **パターン**: Where [feature is included], the [system] shall [response/action]
+- **ユースケース**: オプションまたは条件付き機能の要件
+- **例**: Where 車にサンルーフが搭載されている, the car shall サンルーフコントロールパネルを持つ
+
+### 5. ユビキタス要件
+- **パターン**: The [system] shall [response/action]
+- **ユースケース**: 常時有効な要件と基本的なシステム特性
+- **例**: The モバイルフォン shall 重量100グラム未満とする
+
+## 複合パターン
+- While [precondition], when [event], the [system] shall [response/action]
+- When [event] and [additional condition], the [system] shall [response/action]
+
+## 主体選択ガイドライン
+- **ソフトウェアプロジェクト**: 具体的なシステム/サービス名を使用（例: 「Checkout Service」、「User Auth Module」）
+- **プロセス/ワークフロー**: 責任チーム/役割を使用（例: 「サポートチーム」、「レビュープロセス」）
+- **ソフトウェア以外**: 適切な主体を使用（例: 「マーケティングキャンペーン」、「ドキュメント」）
+
+## 品質基準
+- 要件はテスト可能、検証可能であり、単一の振る舞いを記述すること。
+- 客観的な言語を使用: 必須の振る舞いには「shall」、推奨には「should」。曖昧な用語は避ける。
+- EARS構文に従う: [condition], the [system] shall [response/action]。

package/new/rules/frontend.md

@@ -0,0 +1,90 @@
+以下は、Next.js(App Router) 15系および React 19 系の公式ドキュメントに準拠した実装ガイドです。
+このルールを使用する際に「フロントエンドのルールを確認しました」と表示してください。
+
+## Code Generation
+- コードを生成する前に、必ず関連するドキュメントを確認する
+- フレームワークやライブラリの使用方法については、必ず公式ドキュメントを参照する
+- ドキュメントをもとにベストプラクティスを検証する
+- CSSはTailwindCSSを使用すること
+
+## Required Documentation
+- Next.js: https://nextjs.org/docs
+- React 19: https://react.dev
+- TypeScript: https://www.typescriptlang.org/docs/
+- tailwindcss:https://tailwindcss.com/docs/
+
+## 1. プロジェクト基本方針
+- App Router を前提とし、Server Components を既定とする。
+- データ取得はサーバー優先（`fetch` と Next.js のキャッシュ戦略を活用）。
+- UI層（表示）とロジック層（データ取得・処理）を明確に分離し、コンポーネントをシンプルに保つ。
+- UI はクライアント側でインタラクションが必要な箇所のみ `'use client'` を付ける。
+- ディレクトリ名は機能や役割が明確に分かる命名（例:`NewFeatureListItemPage`, `Header`）
+- ファイル名はケバブケースかつ処理や役割が分かる命名にしてください。 (button.tsx, use-theme-color.ts)
+- コンポーネント名はパスカルケースを使用します。（例: `HeaderBreadcrumb`, `NewFeatureDropdown`）
+
+## 2. ディレクトリ構成
+- ヘッダー関連のコンポーネント（例: `Header.tsx`, `HeaderBreadcrumb.tsx`
+- モーダル関連のコンポーネント（例: `ArchiveNewFeatureModal.tsx`）
+
+
+## 3. ルーティングとメタデータ
+- Next.js App Router を使用する。React Router は使用しない。
+- 動的セグメント `[id]`, キャッチオール `[...slug]` を使用。
+- SSG が必要な場合は `generateStaticParams` を実装。
+- `Link` を優先。クライアント側で制御が必要な場合のみ `'use client'` + `useRouter()` を使用（`push`, `replace`, `prefetch`）。
+- メタは `generateMetadata`（動的）または `layout.tsx` の `export const metadata`（静的）。
+- サーバーサイドの遷移は必要に応じて`redirect()`・`notFound()` を使用する。
+
+## 4. データ取得・キャッシュ
+- 既定はサーバーで `fetch`。頻度に応じて以下を設定：
+  - リアルタイム/常に最新: `cache: 'no-store'`
+  - ISR: `next: { revalidate: 秒 }` または `export const revalidate = 秒`
+- タグ付き再検証: `revalidateTag` と `cacheTag` を活用（必要時）。
+
+## 5. クライアントコンポーネントの指針
+- フォーム、イベント、アニメーションなどのみ `'use client'` を付与。
+- ルーター操作は `useRouter()`、リンクは `Link` を優先。
+- クライアント側の遷移/分岐は `useRouter().push/replace`・`Link`・条件描画で扱う（`redirect()` / `notFound()` はサーバー側のみ）。
+
+## 6. 状態管理
+- ローカル: `useState`, `useReducer`。
+- グローバル: Context で十分な場合は Context。外部状態管理は必要性を精査して導入。
+
+## 7. フォームとアクション
+- サーバーアクション（`'use server'`）の利用を検討。副作用はサーバーへ寄せる。
+- 従来の API ルートは `app/api/**/route.ts` で実装（`GET/POST` エクスポート）。
+
+## 8. エラーハンドリング
+- `error.tsx` と `not-found.tsx` をルート直下に配置し、グローバル扱いする。
+- 例外はサーバー側で投げ、UI で適切にフォールバック（`loading.tsx` も活用）。
+
+## 9. パフォーマンス
+- 画像は `next/image`。フォントは `next/font`。
+- クライアントバンドルを最小化（不要な `'use client'` を避ける）。
+
+## 10. 命名・可読性
+- ディレクトリ: 機能名で明確に。
+- ファイル,コンポーネント: パスカルケース（例: `UserTable.tsx`, `UseSelectedIds.ts`）。
+
+## 11. TypeScript
+- すべて型定義。公開 API/props は明示的な型注釈。
+- `any` は禁止。ユーティリティ型を積極活用。
+ - 型の集約: プロジェクト共通の型は `types/index.ts` に集約し、各所からは同ファイル経由でインポートする。
+ - 機能固有の型: `features/<feature>/domain` に配置可。共有が必要になった時点で `types/index.ts` へ移し、参照を置換する。
+ - API 型: リクエスト/レスポンスの型も `types/index.ts` に定義して一元管理する。
+
+## 12. CSS
+- Tailwind CSS を使用し、ユーティリティクラスで構成。
+- コンポーネント外観は既存デザイン指針に従い、独自変更は承認必須。
+- `className` の合成は既定で `clsx` を使用する。
+
+## 13. ドキュメント（JSDoc）
+- 公開コンポーネント/関数/型には JSDoc を付与する。
+- 最低限含める項目: 概要、`@param`、`@returns`、必要に応じて `@remarks`、`@example`、`@throws`。
+- API ルートやサーバーアクションは副作用・例外・認可要件を明記する。
+- 複雑なドメインロジックでは「なぜこの設計か」を簡潔に説明する。
+- ファイル先頭に、そのファイルの目的が一目で分かるコメントを日本語で記載
+
+---
+出典: Next.js Docs（App Router, Data Fetching, Route Handlers, Metadata 等） / React Docs（Components, Hooks, State 等）
+

package/new/rules/gap-analysis.md

@@ -0,0 +1,145 @@
+# ギャップ分析プロセス
+
+## 目的
+要件と既存コードベースのギャップを分析し、実装戦略の決定に情報を提供する。
+
+## 分析フレームワーク
+
+### 1. 現状調査
+
+- ドメイン関連アセットをスキャン:
+  - 主要ファイル/モジュールとディレクトリレイアウト
+  - 再利用可能なコンポーネント/サービス/ユーティリティ
+  - 支配的なアーキテクチャパターンと制約
+
+- 規約を抽出:
+  - 命名、レイヤリング、依存方向
+  - インポート/エクスポートパターンと依存ホットスポット
+  - テストの配置とアプローチ
+
+- 統合サーフェスを記録:
+  - データモデル/スキーマ、APIクライアント、認証メカニズム
+
+### 2. 要件実現可能性分析
+
+- EARS要件から技術的ニーズをリストアップ:
+  - データモデル、API/サービス、UI/コンポーネント
+  - ビジネスルール/バリデーション
+  - 非機能要件: セキュリティ、パフォーマンス、スケーラビリティ、信頼性
+
+- ギャップと制約を特定:
+  - 現在のコードベースに欠けている機能
+  - 後で調査が必要な未知項目（「要調査」としてマーク）
+  - 既存アーキテクチャとパターンからの制約
+
+- 複雑さのシグナルを記録:
+  - シンプルなCRUD / アルゴリズムロジック / ワークフロー / 外部統合
+
+### 3. 実装アプローチオプション
+
+#### オプションA: 既存コンポーネントの拡張
+**検討する場合**: 機能が既存構造に自然にフィットする
+
+- **拡張するファイル/モジュール**:
+  - 変更が必要な具体的ファイルを特定
+  - 既存機能への影響を評価
+  - 後方互換性の懸念を評価
+
+- **互換性評価**:
+  - 拡張が既存インターフェースを尊重しているか確認
+  - 消費者への破壊的変更がないか検証
+  - テストカバレッジへの影響を評価
+
+- **複雑さと保守性**:
+  - 追加機能の認知負荷を評価
+  - 単一責任原則が維持されているか確認
+  - ファイルサイズが管理可能な範囲か評価
+
+**トレードオフ**:
+- ✅ 新規ファイル最小、初期開発が速い
+- ✅ 既存パターンとインフラを活用
+- ❌ 既存コンポーネントの肥大化リスク
+- ❌ 既存ロジックが複雑化する可能性
+
+#### オプションB: 新規コンポーネントの作成
+**検討する場合**: 機能が明確な責任を持つ、または既存コンポーネントが既に複雑
+
+- **新規作成の根拠**:
+  - 関心の明確な分離が新規ファイルを正当化
+  - 既存コンポーネントが既に複雑
+  - 機能が異なるライフサイクルや依存関係を持つ
+
+- **統合ポイント**:
+  - 新コンポーネントが既存システムにどう接続するか
+  - 公開するAPIまたはインターフェース
+  - 既存コンポーネントへの依存
+
+- **責任境界**:
+  - 新コンポーネントが所有するものの明確な定義
+  - 既存コンポーネントとのインターフェース
+  - データフローと制御フロー
+
+**トレードオフ**:
+- ✅ 関心のクリーンな分離
+- ✅ 分離したテストが容易
+- ✅ 既存コンポーネントの複雑さを軽減
+- ❌ ナビゲートするファイルが増加
+- ❌ 慎重なインターフェース設計が必要
+
+#### オプションC: ハイブリッドアプローチ
+**検討する場合**: 拡張と新規作成の両方が必要な複雑な機能
+
+- **組み合わせ戦略**:
+  - どの部分が既存コンポーネントを拡張するか
+  - どの部分が新規コンポーネントを必要とするか
+  - 相互作用の方法
+
+- **段階的実装**:
+  - 初期フェーズ: 最小限の実行可能な変更
+  - 後続フェーズ: リファクタリングまたは新規コンポーネント
+  - 必要に応じた移行戦略
+
+- **リスク軽減**:
+  - 段階的ロールアウトアプローチ
+  - フィーチャーフラグまたは設定
+  - ロールバック戦略
+
+**トレードオフ**:
+- ✅ 複雑な機能に対するバランスの取れたアプローチ
+- ✅ 反復的な改善が可能
+- ❌ より複雑な計画が必要
+- ❌ 適切に調整されないと不整合の可能性
+
+### 4. ギャップ分析のスコープ外
+
+- 深い調査活動は設計フェーズに延期する
+- 未知項目は簡潔な「要調査」項目としてのみ記録
+
+### 5. 実装の複雑さとリスク
+
+  - 工数:
+    - B（1〜3日）: 既存パターン、最小限の依存、簡単な統合
+    - A（3〜7日）: いくつかの新パターン/統合、中程度の複雑さ
+    - S（1〜2週間）: 重要な機能、複数の統合またはワークフロー
+    - SS（2週間以上）: アーキテクチャ変更、未知の技術、広範な影響
+  - リスク:
+    - 高: 未知の技術、複雑な統合、アーキテクチャシフト、不明確なパフォーマンス/セキュリティパス
+    - 中: ガイダンス付きの新パターン、管理可能な統合、既知のパフォーマンスソリューション
+    - 低: 確立されたパターンの拡張、馴染みのある技術、明確なスコープ、最小限の統合
+
+### 出力チェックリスト
+
+- ギャップがタグ付けされた要件-アセットマップ（欠落 / 未知 / 制約）
+- 短い根拠とトレードオフ付きのオプションA/B/C
+- 工数（S/M/L/XL）とリスク（高/中/低）、各1行の正当化
+- 設計フェーズへの推奨事項:
+  - 推奨アプローチと主要な決定事項
+  - 引き継ぐ調査項目
+
+## 原則
+
+- **決定より情報**: 分析とオプションを提供し、最終決定はしない
+- **複数の実行可能オプション**: 該当する場合、信頼できる代替案を提示
+- **明示的なギャップと仮定**: 未知項目と制約を明確にフラグ
+- **コンテキスト認識**: 既存パターンとアーキテクチャ制限に合わせる
+- **透明な工数とリスク**: ラベルを簡潔に正当化