cursor-sdd 1.0.10 → 1.0.12

package/new/commands/requirements.md

@@ -0,0 +1,91 @@
+<meta>
+description: 仕様の包括的な要件を生成
+argument-hint: <feature-name:$1>
+</meta>
+
+# 要件生成
+
+<background_information>
+- **ミッション**: spec初期化からのプロジェクト説明に基づいて、EARSフォーマットで包括的でテスト可能な要件を生成
+- **成功基準**:
+  - 完全な要件ドキュメントを作成
+  - すべての受け入れ基準にプロジェクトのEARSパターンと制約を適用
+  - 実装詳細なしでコア機能にフォーカス
+  - メタデータを更新して生成状況を追跡
+</background_information>
+
+<instructions>
+## コアタスク
+requirements.md のプロジェクト説明に基づいて、機能 **$1** の完全な要件を生成する。
+
+## 実行ステップ
+
+1. **コンテキストの読み込み**:
+   - `.cursor/$1/spec.json` から言語とメタデータを読み込み
+   - `.cursor/$1/requirements.md` からプロジェクト説明を読み込み
+
+2. **ガイドラインの読み込み**:
+   - `.cursor/rules/ears-format.md` から EARS 構文ルールを読み込み
+   - `.cursor/templates/specs/requirements.md` からドキュメント構造を読み込み
+
+3. **要件の生成**:
+   - プロジェクト説明に基づいて初期要件を作成
+   - 関連機能を論理的な要件領域にグループ化
+   - すべての受け入れ基準に EARS フォーマットを適用
+   - spec.json で指定された言語を使用
+
+4. **メタデータの更新**:
+   - `phase: "requirements-generated"` を設定
+   - `approvals.requirements.generated: true` を設定
+   - `updated_at` タイムスタンプを更新
+
+## 重要な制約
+- 何を（WHAT）にフォーカスし、どのように（HOW）は含めない（実装詳細なし）
+- 要件はテスト可能で検証可能でなければならない
+- EARS文の適切な主語を選択（ソフトウェアにはシステム/サービス名）
+- 最初に初期バージョンを生成し、その後ユーザーフィードバックで反復（事前の連続質問なし）
+- requirements.md の要件見出しには先頭に数値IDのみを含めること（例: "Requirement 1"、"1."、"2 Feature ..."）、"Requirement A" のようなアルファベットIDは使用しない
+</instructions>
+
+## ツールガイダンス
+- **最初に読み込み**: 生成前にすべてのコンテキスト（spec、rules、templates）を読み込み
+- **最後に書き込み**: 完全な生成後にのみ requirements.md を更新
+- 外部ドメイン知識が必要な場合のみ **WebSearch/WebFetch** を使用
+
+## 出力説明
+spec.json で指定された言語で以下を出力:
+
+1. **生成された要件サマリー**: 主要な要件領域の簡潔な概要（3-5項目）
+2. **ドキュメントステータス**: requirements.md の更新と spec.json メタデータの更新を確認
+3. **次のステップ**: 進め方をガイド（承認して続行、または修正）
+
+**フォーマット要件**:
+- 明確さのためMarkdown見出しを使用
+- ファイルパスはコードブロックに含める
+- サマリーは簡潔に（300語以内）
+
+## 安全性とフォールバック
+
+### エラーシナリオ
+- **プロジェクト説明が見つからない**: requirements.md にプロジェクト説明がない場合、ユーザーに機能詳細を確認
+- **曖昧な要件**: 多くの事前質問ではなく、初期バージョンを提案してユーザーと反復
+- **テンプレートが見つからない**: テンプレートファイルが存在しない場合、警告付きでインラインフォールバック構造を使用
+- **言語が未定義**: spec.json で言語が指定されていない場合、日本語（`ja`）をデフォルトに
+- **不完全な要件**: 生成後、要件が期待されるすべての機能をカバーしているか明示的にユーザーに確認
+- **非数値の要件見出し**: 既存の見出しに先頭の数値IDがない場合（例: "Requirement A"）、数値IDに正規化し、マッピングの一貫性を維持（数値とアルファベットのラベルを混在させない）
+
+### 次のフェーズ: 設計生成
+
+**要件が承認された場合**:
+- `.cursor/$1/requirements.md` で生成された要件をレビュー
+- **オプションのギャップ分析**（既存コードベース用）:
+  - `/validate-gap $1` を実行して現在のコードとの実装ギャップを分析
+  - 既存コンポーネント、統合ポイント、実装戦略を特定
+  - ブラウンフィールドプロジェクトには推奨、グリーンフィールドにはスキップ
+- その後 `/design $1 -y` で設計フェーズに進む
+
+**修正が必要な場合**:
+- フィードバックを提供し `/requirements $1` を再実行
+
+**注記**: 設計フェーズに進む前に承認が必須。
+</output>

package/new/commands/status.md

@@ -0,0 +1,86 @@
+<meta>
+description: 仕様のステータスと進捗を表示
+argument-hint: <feature-name:$1>
+</meta>
+
+# 仕様ステータス
+
+<background_information>
+- **ミッション**: 仕様の包括的なステータスと進捗を表示
+- **成功基準**:
+  - 現在のフェーズと完了状況を表示
+  - 次のアクションとブロッカーを特定
+  - 進捗の明確な可視性を提供
+</background_information>
+
+<instructions>
+## コアタスク
+機能 **$1** のステータスレポートを生成し、すべてのフェーズの進捗を表示する。
+
+## 実行ステップ
+
+### ステップ1: Specコンテキストの読み込み
+- `.cursor/$1/spec.json` からメタデータとフェーズステータスを読み込み
+- 既存ファイルを読み込み: `requirements.md`、`design.md`、`tasks.md`（存在する場合）
+- `.cursor/$1/` ディレクトリで利用可能なファイルを確認
+
+### ステップ2: ステータスの分析
+
+**各フェーズを解析**:
+- **Requirements**: 要件と受け入れ基準の数をカウント
+- **Design**: アーキテクチャ、コンポーネント、ダイアグラムを確認
+- **Tasks**: 完了タスク vs 全タスクをカウント（`- [x]` vs `- [ ]` を解析）
+- **Approvals**: spec.json で承認状況を確認
+
+### ステップ3: レポートの生成
+
+spec.json で指定された言語でレポートを作成し、以下をカバー:
+1. **現在のフェーズと進捗**: ワークフローにおけるspecの位置
+2. **完了状況**: 各フェーズの完了率
+3. **タスク内訳**: タスクが存在する場合、完了/残りの数を表示
+4. **次のアクション**: 次に何をすべきか
+5. **ブロッカー**: 進捗を妨げる問題
+
+## 重要な制約
+- spec.json の言語を使用
+- 正確な完了率を計算
+- 具体的な次のアクションコマンドを特定
+</instructions>
+
+## ツールガイダンス
+- **Read**: 最初に spec.json を読み込み、次に必要に応じて他のspecファイルを読み込み
+- **慎重に解析**: tasks.md のチェックボックスから完了データを抽出
+- **Glob** を使用してどのspecファイルが存在するか確認
+
+## 出力説明
+
+spec.json で指定された言語でステータスレポートを提供:
+
+**レポート構造**:
+1. **機能概要**: 名前、フェーズ、最終更新
+2. **フェーズステータス**: Requirements、Design、Tasks と完了率
+3. **タスク進捗**: タスクが存在する場合、X/Y 完了を表示
+4. **次のアクション**: 次に実行する具体的なコマンド
+5. **問題**: ブロッカーや不足要素
+
+**フォーマット**: ステータス用の絵文字（✅/⏳/❌）で明確でスキャンしやすいフォーマット
+
+## 安全性とフォールバック
+
+### エラーシナリオ
+
+**Specが見つからない**:
+- **メッセージ**: "`$1` のspecが見つかりません。`.cursor/` で利用可能なspecを確認してください"
+- **アクション**: `.cursor/` 内の利用可能な機能ディレクトリをリスト
+
+**不完全なSpec**:
+- **警告**: どのファイルが不足しているか特定
+- **提案アクション**: 次のフェーズコマンドを指示
+
+### すべてのSpecをリスト
+
+すべての利用可能なspecを見るには:
+- 引数なしで実行またはワイルドカードを使用
+- `.cursor/` 内のすべてのspecをステータスとともに表示
+
+</output>

package/new/commands/tasks.md

@@ -0,0 +1,155 @@
+<meta>
+description: 仕様の実装タスクを生成
+argument-hint: <feature-name:$1> [-y:$2] [--sequential:$3]
+</meta>
+
+# 実装タスクジェネレーター
+
+<background_information>
+- **ミッション**: 技術設計を実行可能な作業項目に変換する、詳細で実行可能な実装タスクを生成
+- **成功基準**:
+  - すべての要件が特定のタスクにマッピング
+  - タスクが適切なサイズ（各1-3時間）
+  - 適切な階層で明確なタスク進行
+  - 機能に焦点を当てた自然言語の説明
+</background_information>
+
+<instructions>
+## コアタスク
+承認済み要件と設計に基づいて、機能 **$1** の実装タスクを生成する。
+
+## 実行ステップ
+
+### ステップ1: コンテキストの読み込み
+
+**必要なすべてのコンテキストを読み込み**:
+- `.cursor/$1/spec.json`、`requirements.md`、`design.md`
+- `.cursor/$1/tasks.md`（存在する場合、マージモード用）
+- `.cursor/rules/frontend.md`（フロントエンド実装制約）
+
+**承認の検証**:
+- `-y` フラグが提供された場合（$2 == "-y"）: spec.json で要件と設計を自動承認
+- それ以外: 両方が承認されていることを確認（されていない場合は停止、安全性とフォールバック参照）
+- シーケンシャルモードの判定: `sequential = ($3 == "--sequential")`
+
+機能: $1
+機能ディレクトリ: .cursor/$1/
+自動承認: {$2 == "-y" なら true、それ以外 false}
+シーケンシャルモード: {sequential なら true、それ以外 false}
+
+読み込むファイルパターン:
+- .cursor/$1/*.{json,md}
+- .cursor/rules/tasks-generation.md
+- .cursor/rules/tasks-parallel-analysis.md（シーケンシャルモードが false の場合のみ含める）
+- .cursor/templates/specs/tasks.md
+
+モード: {tasks.md の存在に基づいて generate または merge}
+命令ハイライト:
+- すべての要件をタスクにマップし、要件IDのみをリスト（カンマ区切り）、追加の説明なし
+- 単一の実行可能なサブタスクはメジャータスクに昇格させ、コンテナのサマリーは簡潔に
+- 並列基準を満たす場合のみ `(P)` マーカーを適用（シーケンシャルモードでは省略）
+- 延期可能なMVP後の受け入れ基準フォーカスのテストカバレッジサブタスクには `- [ ]*` でマーク
+
+### ステップ2: 実装タスクの生成
+
+**生成ルールとテンプレートの読み込み**:
+- `.cursor/rules/tasks-generation.md` から原則を読み込み
+- `sequential == false` の場合: `.cursor/rules/tasks-parallel-analysis.md` から並列判定基準を読み込み
+- `.cursor/templates/specs/tasks.md` からフォーマットを読み込み（`(P)` マーカーをサポート）
+
+**すべてのルールに従ってタスクリストを生成**:
+- spec.json で指定された言語を使用
+- すべての要件をタスクにマップ
+- 要件カバレッジを文書化する際は、数値の要件IDのみをリスト（カンマ区切り）、説明的な接尾辞、括弧、翻訳、自由形式のラベルなし
+- すべての設計コンポーネントが含まれていることを確認
+- タスク進行が論理的で段階的であることを検証
+- 単一サブタスク構造はメジャータスクに昇格させて折りたたみ、コンテナのみのメジャータスクで詳細を重複させない（テンプレートパターンに従う）
+- 並列基準を満たすタスクに `(P)` マーカーを適用（`sequential == true` の場合はマーカーをスキップ）
+- 延期可能なMVP後の受け入れ基準フォーカスのテストカバレッジサブタスクには `- [ ]*` でマーク
+- 既存の tasks.md が見つかった場合、新しいコンテンツとマージ
+
+### ステップ3: 最終化
+
+**書き込みと更新**:
+- `.cursor/$1/tasks.md` を作成/更新
+- spec.json メタデータを更新:
+  - `phase: "tasks-generated"` を設定
+  - `approvals.tasks.generated: true, approved: false` を設定
+  - `approvals.requirements.approved: true` を設定
+  - `approvals.design.approved: true` を設定
+  - `updated_at` タイムスタンプを更新
+
+## 重要な制約
+- **ルールを厳密に遵守**: tasks-generation.md のすべての原則は必須
+- **自然言語**: コード構造の詳細ではなく、何をするかを説明
+- **完全なカバレッジ**: すべての要件がタスクにマップされなければならない
+- **最大2レベル**: メジャータスクとサブタスクのみ（より深いネストなし）
+- **連番**: メジャータスクは増分（1, 2, 3...）、重複なし
+- **タスク統合**: すべてのタスクがシステムに接続（孤立した作業なし）
+</instructions>
+
+## ツールガイダンス
+- **最初に読み込み**: 生成前にすべてのコンテキスト、ルール、テンプレートを読み込み
+- **最後に書き込み**: 完全な分析と検証後にのみ tasks.md を生成
+
+## 出力説明
+
+spec.json で指定された言語で簡潔なサマリーを提供:
+
+1. **ステータス**: `.cursor/$1/tasks.md` にタスク生成完了を確認
+2. **タスクサマリー**: 
+   - 合計: メジャータスク X 個、サブタスク Y 個
+   - Z 個のすべての要件をカバー
+   - 平均タスクサイズ: サブタスクあたり1-3時間
+3. **品質検証**:
+   - ✅ すべての要件がタスクにマップ
+   - ✅ タスク依存関係を検証済み
+   - ✅ テストタスクを含む
+4. **次のアクション**: タスクをレビューし、準備ができたら進行
+
+**フォーマット**: 簡潔（200語以内）
+
+## 安全性とフォールバック
+
+### エラーシナリオ
+
+**要件または設計が未承認**:
+- **実行停止**: 承認済みの要件と設計なしでは続行不可
+- **ユーザーメッセージ**: "タスク生成前に要件と設計の承認が必要です"
+- **提案アクション**: "`/spec-tasks $1 -y` を実行して両方を自動承認して進行"
+
+**要件または設計が見つからない**:
+- **実行停止**: 両方のドキュメントが存在しなければならない
+- **ユーザーメッセージ**: "`.cursor/$1/` に requirements.md または design.md がありません"
+- **提案アクション**: "要件と設計フェーズを先に完了してください"
+
+**不完全な要件カバレッジ**:
+- **警告**: "すべての要件がタスクにマップされていません。カバレッジを確認してください。"
+- **ユーザーアクション必要**: 意図的なギャップを確認するか、タスクを再生成
+
+**テンプレート/ルールが見つからない**:
+- **ユーザーメッセージ**: "`.cursor/rules/` または `.cursor/templates/` にテンプレートまたはルールファイルがありません"
+- **フォールバック**: 警告付きでインライン基本構造を使用
+- **提案アクション**: "リポジトリのセットアップを確認するか、テンプレートファイルを復元"
+- **数値要件IDが見つからない**:
+  - **実行停止**: requirements.md のすべての要件には数値IDが必要。いずれかの要件に数値IDがない場合、停止してタスク生成前に requirements.md の修正を要求。
+
+### 次のフェーズ: 実装
+
+**実装開始前**:
+- **重要**: `/spec-impl` 実行前に会話履歴をクリアしてコンテキストを解放
+- これは最初のタスク開始時またはタスク切り替え時に適用
+- 新鮮なコンテキストでクリーンな状態と適切なタスクフォーカスを確保
+
+**タスク承認後**:
+- 特定のタスクを実行: `/spec-impl $1 1.1`（推奨: 各タスク間でコンテキストをクリア）
+- 複数タスクを実行: `/spec-impl $1 1.1,1.2`（注意して使用、タスク間でコンテキストをクリア）
+- 引数なし: `/spec-impl $1`（すべての保留タスクを実行 - コンテキスト膨張のため非推奨）
+
+**修正が必要な場合**:
+- フィードバックを提供し `/spec-tasks $1` を再実行
+- 既存タスクは参照として使用（マージモード）
+
+**注記**: 実装フェーズでは、適切なコンテキストと検証でタスク実行をガイド。
+
+</output>

package/new/rules/design-discovery-full.md

@@ -0,0 +1,93 @@
+# 技術設計向けフルディスカバリープロセス
+
+## 目的
+技術設計が完全で正確かつ最新の情報に基づいていることを確保するため、包括的な調査と分析を実施する。
+
+## ディスカバリーステップ
+
+### 1. 要件分析
+**要件を技術的ニーズにマッピング**
+- EARSフォーマットからすべての機能要件を抽出
+- 非機能要件を特定（パフォーマンス、セキュリティ、スケーラビリティ）
+- 技術的制約と依存関係を決定
+- コア技術課題をリスト
+
+### 2. 既存実装分析
+**現在のシステムを理解**（修正/拡張する場合）:
+- コードベース構造とアーキテクチャパターンを分析
+- 再利用可能なコンポーネント、サービス、ユーティリティをマッピング
+- ドメイン境界とデータフローを特定
+- 統合ポイントと依存関係を文書化
+- アプローチを決定: 拡張 vs リファクタ vs ラップ
+
+### 3. 技術調査
+**ベストプラクティスとソリューションを調査**:
+- **WebSearchを使用**して以下を検索:
+  - 類似問題に対する最新のアーキテクチャパターン
+  - 技術スタックに対する業界のベストプラクティス
+  - 関連技術の最近の更新や変更
+  - よくある落とし穴と解決策
+
+- **WebFetchを使用**して以下を分析:
+  - フレームワーク/ライブラリの公式ドキュメント
+  - APIリファレンスと使用例
+  - 移行ガイドと破壊的変更
+  - パフォーマンスベンチマークと比較
+
+### 4. 外部依存関係調査
+**各外部サービス/ライブラリについて**:
+- 公式ドキュメントとGitHubリポジトリを検索
+- APIシグネチャと認証方法を検証
+- 既存スタックとのバージョン互換性を確認
+- レート制限と使用制限を調査
+- コミュニティリソースと既知の問題を検索
+- セキュリティの考慮事項を文書化
+- 実装調査が必要なギャップを記録
+
+### 5. アーキテクチャパターンと境界分析
+**アーキテクチャオプションを評価**:
+- 関連パターンを比較（MVC、Clean、Hexagonal、Event-driven）
+- 既存アーキテクチャとステアリング原則との適合性を評価
+- チーム間の競合を回避するために必要なドメイン境界と所有権の継ぎ目を特定
+- スケーラビリティへの影響と運用上の懸念を考慮
+- 保守性とチームの専門知識を評価
+- 推奨パターンと却下した代替案を `research.md` に文書化
+
+### 6. リスク評価
+**技術的リスクを特定**:
+- パフォーマンスボトルネックとスケーリング限界
+- セキュリティ脆弱性と攻撃ベクトル
+- 統合の複雑さと結合
+- 技術的負債の生成 vs 解消
+- 知識ギャップとトレーニングニーズ
+
+## 調査ガイドライン
+
+### 検索するタイミング
+**常に検索するもの**:
+- 外部APIドキュメントと更新
+- 認証/認可のセキュリティベストプラクティス
+- 特定されたボトルネックに対するパフォーマンス最適化テクニック
+- 依存関係の最新バージョンと移行パス
+
+**不確かな場合に検索するもの**:
+- 特定のユースケースに対するアーキテクチャパターン
+- データフォーマット/プロトコルの業界標準
+- コンプライアンス要件（GDPR、HIPAAなど）
+- 予想負荷に対するスケーラビリティアプローチ
+
+### 検索戦略
+1. 公式ソース（ドキュメント、GitHub）から開始
+2. 最近のブログ記事や記事をチェック（過去6ヶ月）
+3. 一般的な問題についてStack Overflowを確認
+4. 類似のオープンソース実装を調査
+
+## 出力要件
+設計決定に影響するすべての発見を共有テンプレートを使用して `research.md` にキャプチャ:
+- アーキテクチャ、技術整合、コントラクトに影響する主要なインサイト
+- 調査中に発見された制約
+- 推奨アプローチと選択したアーキテクチャパターン（根拠付き）
+- 却下した代替案とトレードオフ（設計決定セクションに文書化）
+- コンポーネント & インターフェースコントラクトに情報を提供する更新されたドメイン境界
+- リスクと軽減戦略
+- 実装中にさらなる調査が必要なギャップ

package/new/rules/design-discovery-light.md

@@ -0,0 +1,49 @@
+# 拡張向け軽量ディスカバリープロセス
+
+## 目的
+機能拡張のための既存システムと統合要件を迅速に分析する。
+
+## 焦点を絞ったディスカバリーステップ
+
+### 1. 拡張ポイント分析
+**統合アプローチを特定**:
+- 既存の拡張ポイントまたはインターフェースを特定
+- 変更スコープを決定（ファイル、コンポーネント）
+- 従うべき既存パターンを確認
+- 後方互換性の要件を特定
+
+### 2. 依存関係チェック
+**互換性を検証**:
+- 新しい依存関係のバージョン互換性を確認
+- APIコントラクトが変更されていないことを検証
+- パイプラインに破壊的変更がないことを確認
+
+### 3. クイック技術検証
+**新しいライブラリの場合のみ**:
+- WebSearchで公式ドキュメントを使用
+- 基本的な使用パターンを検証
+- 既知の互換性問題を確認
+- ライセンス互換性を確認
+- 主要な発見を `research.md` に記録（技術整合セクション）
+
+### 4. 統合リスク評価
+**クイックリスクチェック**:
+- 既存機能への影響
+- パフォーマンスへの影響
+- セキュリティの考慮事項
+- テスト要件
+
+## フルディスカバリーにエスカレーションするタイミング
+以下を発見した場合、フルディスカバリーに切り替える:
+- 重大なアーキテクチャ変更が必要
+- 複雑な外部サービス統合
+- セキュリティ上センシティブな実装
+- パフォーマンスクリティカルなコンポーネント
+- 未知またはドキュメントが不十分な依存関係
+
+## 出力要件
+- 明確な統合アプローチ（境界への影響を `research.md` に記録）
+- 変更するファイル/コンポーネントのリスト
+- バージョン付きの新しい依存関係
+- 統合リスクと軽減策
+- テストの焦点領域

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 を使用して関連コンポーネントをクラスタリングすることは許可。明確さのために控えめに使用
+
+## 品質メトリクス
+### 設計完全性チェックリスト
+- すべての要件に対応
+- 実装詳細の漏れなし
+- 明確なコンポーネント境界
+- 明示的なエラーハンドリング
+- 包括的なテスト戦略
+- セキュリティを考慮
+- パフォーマンス目標を定義
+- 移行パスが明確（該当する場合）
+
+### 避けるべき一般的なアンチパターン
+❌ 設計と実装の混在
+❌ 曖昧なインターフェース定義
+❌ 欠落したエラーシナリオ
+❌ 無視された非機能要件
+❌ 過度に複雑なアーキテクチャ
+❌ コンポーネント間の密結合
+❌ データ整合性戦略の欠如
+❌ 不完全な依存関係分析