# design.md
## 1. アーキテクチャ概要
Agent向けSpec-Driven Development支援MCPサーバー
このシステムはプロンプト生成エンジンとして動作し、Agentが高品質なSpec文書を段階的に作成できるよう支援する。直接的なファイル生成は行わず、各段階でAgentに適切な作業指示プロンプトを提供し、生成されたファイルの品質検証とフィードバックを行う。
[Requirements: REQ-01, REQ-02, REQ-03, REQ-04, REQ-05, REQ-06, REQ-07, REQ-08, REQ-09, REQ-10]
## 2. コンポーネント設計
- **prompt-generator**: Agent向け作業指示プロンプト生成エンジン [REQ-02, REQ-04, REQ-06, REQ-08]
- **question-generator**: 情報不足時のユーザー向け質問生成エンジン [REQ-01]
- **validator**: 生成物品質検証とフィードバック生成エンジン [REQ-03, REQ-05, REQ-07]
- **traceability-manager**: 要件-設計-タスク間対応関係管理 [REQ-09, REQ-10]
- **change-analyzer**: 変更影響分析と修正プロンプト生成 [REQ-09]
- **template-manager**: プロンプトテンプレート管理とバージョニング
## 3. データモデル
```python
from typing import Optional, Literal, Dict, List
from dataclasses import dataclass
from datetime import datetime
@dataclass
class PromptRequest:
type: Literal[
'requirements',
'design',
'tasks',
'code',
'question',
'validation'
]
context: Dict[str, Optional[str]]
options: Dict[str, bool]
@dataclass
class PromptResponse:
type: Literal['instruction', 'question', 'validation_result', 'fix_instruction']
content: str
metadata: Dict[str, str]
@dataclass
class ValidationResult:
is_valid: bool
errors: List[str]
warnings: List[str]
suggestions: List[str]
fix_prompt: Optional[str] = None
@dataclass
class TraceabilityMap:
req_to_design: Dict[str, List[str]]
design_to_tasks: Dict[str, List[str]]
task_to_req: Dict[str, List[str]]
```
## 4. API（MCPツール）
- **prompt_requirements** → Agentにrequirements.md生成プロンプトを返す
- **prompt_design** → Agentにdesign.md生成プロンプトを返す
- **prompt_tasks** → Agentにtasks.md生成プロンプトを返す
- **prompt_code** → Agentにコード実装プロンプト（注意事項付き）を返す
- **validate_requirements** → requirements.md検証結果と修正プロンプトを返す
- **validate_design** → design.md検証結果と修正プロンプトを返す
- **validate_tasks** → tasks.md検証結果と修正プロンプトを返す
- **analyze_changes** → 変更影響分析と修正プロンプトを返す
- **get_traceability** → 現在のtraceability状況レポートを返す
- **check_completeness** → 情報充足性確認と質問プロンプトを返す
## 5. 非機能・品質
- **パフォーマンス**: 各プロンプト生成 < 1秒 [NFR-01]
- **一貫性**: プロンプト品質統一（EARS/WBS準拠） [NFR-02]
- **完全性**: Traceability100%保持 [NFR-03]
- **明確性**: Agent向けガイダンス充実 [NFR-04]
- **堅牢性**: エラーハンドリング完備 [NFR-05]
## 6. テスト戦略
- **単体/結合/E2E の役割分担**: プロンプト生成は単体、連鎖処理は結合、Agent応答は E2E で検証
- **test-prompt-generation**: プロンプト生成機能の重要なテストケース
- **テストデータ方針**: 正常系・異常系・境界値を含む入力パターン
- **観測可能な合否基準**: 10,000文字以内、必須要素含有、実行可能性
- **test-validation-accuracy**: バリデーション精度の重要なテストケース
- **テストデータ方針**: 正常/異常なspec文書パターン
- **観測可能な合否基準**: 偽陽性/偽陰性率5%以下
- **test-question-generation**: 質問生成機能の重要なテストケース
- **テストデータ方針**: 情報不足パターンの網羅
- **観測可能な合否基準**: 適切な質問文生成と情報不足検出90%以上
- **test-traceability-management**: トレーサビリティ管理の重要なテストケース
- **テストデータ方針**: 複雑な要件-設計-タスク関係パターン
- **観測可能な合否基準**: 対応関係完全性100%、変更影響分析精度95%以上
- **test-change-analysis**: 変更影響分析の重要なテストケース
- **テストデータ方針**: 単一/複数ファイル変更パターン
- **観測可能な合否基準**: 影響範囲特定精度95%以上、修正プロンプト適切性
- **test-performance**: パフォーマンス要件の重要なテストケース
- **テストデータ方針**: 大規模プロジェクト想定データ
- **観測可能な合否基準**: 各処理1秒未満、メモリ使用量制限内
## 7. トレーサビリティ (必須)
- REQ-01 ⇔ **question-generator**
- REQ-02 ⇔ **prompt-generator**
- REQ-03 ⇔ **validator**
- REQ-04 ⇔ **prompt-generator**
- REQ-05 ⇔ **validator**
- REQ-06 ⇔ **prompt-generator**
- REQ-07 ⇔ **validator**
- REQ-08 ⇔ **prompt-generator**
- REQ-09 ⇔ **change-analyzer**
- REQ-10 ⇔ **traceability-manager**
- TR-01 ⇔ **test-prompt-generation**
- TR-02 ⇔ **test-validation-accuracy**
- TR-03 ⇔ **test-question-generation**
- TR-04 ⇔ **test-traceability-management**
- TR-05 ⇔ **test-performance**
- TR-06 ⇔ **test-prompt-generation**
- TR-07 ⇔ **test-change-analysis**
## 8. リスクと対応
- **リスク1**: プロンプト品質不安定 → テンプレート標準化・バージョン管理で対応
- **リスク2**: Agent応答品質低下 → プロンプト明確性向上・例示充実で対応
- **リスク3**: Traceability破綻 → 自動検証・修復機能で対応
- **リスク4**: パフォーマンス劣化 → プロンプト最適化・キャッシュで対応
