feat: Add integration point analysis and fail-fast principles to improve E2E testing

.claude/agents-en/technical-designer.md

@@ -74,6 +74,29 @@ Must be performed before Design Doc creation:
    - Clearly document similar functionality search results (found implementations or "none")
    - Record adopted decision (use existing/improvement proposal/new implementation) and rationale
 
+### Integration Point Analysis【Important】
+Clarify integration points with existing systems when adding new features or modifying existing ones:
+
+1. **Identify and Document Integration Points**
+   ```yaml
+   ## Integration Point Map
+   Integration Point 1:
+     Existing Component: [Service Name/Method Name]
+     Integration Method: [Hook Addition/Call Addition/Data Reference/etc]
+     Impact Level: High (Process Flow Change) / Medium (Data Usage) / Low (Read-Only)
+     Required Test Coverage: [Continuity Verification of Existing Features]
+   ```
+
+2. **Classification by Impact Level**
+   - **High**: Modifying or extending existing process flows
+   - **Medium**: Using or updating existing data
+   - **Low**: Read-only operations, log additions, etc.
+
+3. **Reflection in Design Doc**
+   - Create "## Integration Point Map" section
+   - Clarify responsibilities and boundaries at each integration point
+   - Define error behavior at design phase
+
 ### Agreement Checklist【Most Important】
 Must be performed at the beginning of Design Doc creation:
 

.claude/agents-ja/technical-designer.md

@@ -74,6 +74,29 @@ Design Doc作成前に必ず実施：
    - 類似機能の検索結果（発見した実装、または「なし」）を明記
    - 採用した判断（既存使用/改善提案/新規実装）とその根拠を記録
 
+### 統合ポイント分析【重要】
+新機能や既存機能の変更時に、既存システムとの統合ポイントを明確化：
+
+1. **統合ポイントの特定と記載**
+   ```yaml
+   ## 統合ポイントマップ
+   統合点1:
+     既存コンポーネント: [サービス名・メソッド名]
+     統合方法: [フック追加/呼び出し追加/データ参照等]
+     影響度: 高（処理フロー変更）/中（データ利用）/低（読み取りのみ）
+     必要なテスト観点: [既存機能の継続性確認内容]
+   ```
+
+2. **影響度による分類**
+   - **高**: 既存処理フローを変更・拡張する場合
+   - **中**: 既存データを利用・更新する場合
+   - **低**: 読み取りのみ・ログ追加等の場合
+
+3. **Design Docへの反映**
+   - 「## 統合ポイントマップ」セクションを作成
+   - 各統合点での責務と境界を明確化
+   - エラー時の振る舞いを設計段階で決定
+
 ### 合意事項チェックリスト【最重要】
 Design Doc作成の最初に必ず実施：
 

docs/rules-en/ai-development-guide.md

@@ -22,6 +22,23 @@ Immediately stop and reconsider design when detecting the following patterns:
 - **Symptomatic fixes** - Surface-level fixes that don't solve root causes
 - **Unplanned large-scale changes** - Lack of incremental approach
 
+## Fallback Design Principles
+
+### Core Principle: Fail-Fast
+Design philosophy that prioritizes improving primary code reliability over fallback implementations in distributed systems.
+
+### Criteria for Fallback Implementation
+- **Default Prohibition**: Do not implement unconditional fallbacks on errors
+- **Exception Approval**: Implement only when explicitly defined in Design Doc
+- **Layer Responsibilities**:
+  - Infrastructure Layer: Always throw errors upward (no fallback decisions)
+  - Application Layer: Implement decisions based on business requirements
+
+### Detection of Excessive Fallbacks
+- Require design review when writing the 3rd catch statement in the same feature
+- Verify Design Doc definition before implementing fallbacks
+- Properly log errors and make failures explicit
+
 ## Rule of Three - Criteria for Code Duplication
 
 How to handle duplicate code based on Martin Fowler's "Refactoring":

docs/rules-en/rules-index.yaml

@@ -16,6 +16,7 @@ rules:
       - "Branded Types - TypeScript Community"
       - "Effect-TS / fp-ts - Functional Programming"
       - "Dependency Injection - Martin Fowler"
+      - "Avoiding fallback in distributed systems - AWS Builders' Library"
     sections:
       - "Basic Principles"
       - "Comment Writing Rules"
@@ -57,8 +58,10 @@ rules:
       - "DRY Principle - The Pragmatic Programmer"
       - "Single Responsibility Principle (SRP) - Clean Code"
       - "YAGNI Principle - Extreme Programming"
+      - "Avoiding fallback in distributed systems - AWS Builders' Library"
     sections:
       - "Technical Anti-patterns (Red Flag Patterns)"
+      - "Fallback Design Principles"
       - "Rule of Three - Criteria for Code Duplication"
       - "Common Failure Patterns and Avoidance Methods"
       - "Debugging Techniques"

docs/rules-en/typescript-testing.md

@@ -28,6 +28,13 @@
    - Use actual dependencies (DB, API, etc.)
    - Verify major functional flows
 
+3. **Cross-functional Verification in E2E Tests**
+   - Mandatory verification of impact on existing features when adding new features
+   - Cover integration points with "High" and "Medium" impact levels from Design Doc's "Integration Point Map"
+   - Verification pattern: Existing feature operation → Enable new feature → Verify continuity of existing features
+   - Success criteria: No change in response content, processing time within 5 seconds
+   - Designed for automatic execution in CI/CD pipelines
+
 ## Red-Green-Refactor Process (Test-First Development)
 
 **Recommended Principle**: Always start code changes with tests

docs/rules-en/typescript.md

@@ -126,6 +126,20 @@ Input Layer (`unknown`) → Type Guard → Business Layer (Type Guaranteed) →
 
 **Absolute Rule**: Error suppression prohibited. All errors must have log output and appropriate handling.
 
+**Fail-Fast Principle**: Fail quickly on errors to prevent continued processing in invalid states
+```typescript
+// ❌ Prohibited: Unconditional fallback
+catch (error) {
+  return defaultValue // Hides error
+}
+
+// ✅ Required: Explicit failure
+catch (error) {
+  logger.error('Processing failed', error)
+  throw error // Handle appropriately at higher layer
+}
+```
+
 **Result Type Pattern**: Express errors with types for explicit handling
 ```typescript
 type Result<T, E> = { ok: true; value: T } | { ok: false; error: E }

docs/rules-ja/ai-development-guide.md

@@ -22,6 +22,23 @@
 - **対処療法的修正** - 根本原因を解決しない表面的な修正
 - **無計画な大規模変更** - 段階的アプローチの欠如
 
+## フォールバック処理に関する設計原則
+
+### 基本原則：Fail-Fast
+分散システムにおいて、フォールバック処理よりもプライマリコードの信頼性向上を優先する設計思想。
+
+### フォールバック実装の判断基準
+- **原則禁止**: エラー時の無条件フォールバックは実装しない
+- **例外的許可**: Design Docで明示的に定義された場合のみ実装
+- **レイヤー責務**:
+  - インフラ層: エラーを必ず上位に投げる（フォールバック判断なし）
+  - アプリケーション層: ビジネス要件に基づく判断を実装
+
+### フォールバック過多の検出
+- 同一機能で3つ目のcatch文を書く時点で設計見直しを必須とする
+- フォールバックを実装する前にDesign Docでの定義を確認
+- エラーは適切にログ出力し、失敗を明確にする
+
 ## Rule of Three - コード重複の判断基準
 
 Martin Fowler「Refactoring」に基づく重複コードの扱い方：

docs/rules-ja/rules-index.yaml

@@ -16,6 +16,7 @@ rules:
       - "Branded Types - TypeScript Community"
       - "Effect-TS / fp-ts - 関数型プログラミング"
       - "Dependency Injection - Martin Fowler"
+      - "Avoiding fallback in distributed systems - AWS Builders' Library"
     sections:
       - "基本原則"
       - "コメント記述ルール"
@@ -57,8 +58,10 @@ rules:
       - "DRY原則 - The Pragmatic Programmer"
       - "単一責任原則（SRP） - Clean Code"
       - "YAGNI原則 - Extreme Programming"
+      - "Avoiding fallback in distributed systems - AWS Builders' Library"
     sections:
       - "技術的アンチパターン（赤信号パターン）"
+      - "フォールバック処理に関する設計原則"
       - "Rule of Three - コード重複の判断基準"
       - "よくある失敗パターンと回避方法"
       - "デバッグ手法"

docs/rules-ja/typescript-testing.md

@@ -28,6 +28,13 @@
    - 実際の依存関係を使用（DBやAPI等）
    - 主要な機能フローの検証
 
+3. **E2Eテストでの機能横断検証**
+   - 新機能追加時、既存機能への影響を必ず検証
+   - Design Docの「統合ポイントマップ」で影響度「高」「中」の箇所をカバー
+   - 検証パターン: 既存機能動作 → 新機能有効化 → 既存機能の継続性確認
+   - 判定基準: レスポンス内容の変化なし、処理時間5秒以内
+   - CI/CDでの自動実行を前提とした設計
+
 ## Red-Green-Refactorプロセス（テストファースト開発）
 
 **推奨原則**: コード変更は必ずテストから始める

docs/rules-ja/typescript.md

@@ -126,6 +126,20 @@ function isUser(value: unknown): value is User {
 
 **絶対ルール**: エラーの握りつぶし禁止。すべてのエラーは必ずログ出力と適切な処理を行う。
 
+**Fail-Fast原則**: エラー時は速やかに失敗させ、不正な状態での処理継続を防ぐ
+```typescript
+// ❌ 禁止: 無条件フォールバック
+catch (error) {
+  return defaultValue // エラーを隠蔽
+}
+
+// ✅ 必須: 明示的な失敗
+catch (error) {
+  logger.error('処理失敗', error)
+  throw error // 上位層で適切に処理
+}
+```
+
 **Result型パターン**: エラーを型で表現し、明示的に処理
 ```typescript
 type Result<T, E> = { ok: true; value: T } | { ok: false; error: E }