From b8fbb96b01827fb091bdc5ae9e72294bf152c534 Mon Sep 17 00:00:00 2001 From: shinpr Date: Thu, 11 Sep 2025 13:31:41 +0900 Subject: [PATCH 1/2] feat: Add integration point analysis and fail-fast principles to improve E2E testing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add integration point mapping to technical-designer.md for identifying cross-feature impacts - Enhance E2E testing with cross-functional validation requirements in typescript-testing.md - Introduce fail-fast principles and fallback design guidelines in ai-development-guide.md - Add explicit error handling without fallback in typescript.md - Update rules-index.yaml with AWS Builders' Library reference for distributed systems These changes ensure better detection of integration issues early in development and prevent error masking through inappropriate fallback implementations. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .claude/agents-ja/technical-designer.md | 23 +++++++++++++++++++++++ docs/rules-ja/ai-development-guide.md | 17 +++++++++++++++++ docs/rules-ja/rules-index.yaml | 3 +++ docs/rules-ja/typescript-testing.md | 7 +++++++ docs/rules-ja/typescript.md | 14 ++++++++++++++ 5 files changed, 64 insertions(+) diff --git a/.claude/agents-ja/technical-designer.md b/.claude/agents-ja/technical-designer.md index 46676d1..851f46f 100644 --- a/.claude/agents-ja/technical-designer.md +++ b/.claude/agents-ja/technical-designer.md @@ -74,6 +74,29 @@ Design Doc作成前に必ず実施： - 類似機能の検索結果（発見した実装、または「なし」）を明記 - 採用した判断（既存使用/改善提案/新規実装）とその根拠を記録 +### 統合ポイント分析【重要】 +新機能や既存機能の変更時に、既存システムとの統合ポイントを明確化： + +1. **統合ポイントの特定と記載** + ```yaml + ## 統合ポイントマップ + 統合点1: + 既存コンポーネント: [サービス名・メソッド名] + 統合方法: [フック追加/呼び出し追加/データ参照等] + 影響度: 高（処理フロー変更）/中（データ利用）/低（読み取りのみ） + 必要なテスト観点: [既存機能の継続性確認内容] + ``` + +2. **影響度による分類** + - **高**: 既存処理フローを変更・拡張する場合 + - **中**: 既存データを利用・更新する場合 + - **低**: 読み取りのみ・ログ追加等の場合 + +3. **Design Docへの反映** + - 「## 統合ポイントマップ」セクションを作成 + - 各統合点での責務と境界を明確化 + - エラー時の振る舞いを設計段階で決定 + ### 合意事項チェックリスト【最重要】 Design Doc作成の最初に必ず実施： diff --git a/docs/rules-ja/ai-development-guide.md b/docs/rules-ja/ai-development-guide.md index d31fedb..4f76279 100644 --- a/docs/rules-ja/ai-development-guide.md +++ b/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」に基づく重複コードの扱い方： diff --git a/docs/rules-ja/rules-index.yaml b/docs/rules-ja/rules-index.yaml index 95169e5..8aa3299 100644 --- a/docs/rules-ja/rules-index.yaml +++ b/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 - コード重複の判断基準" - "よくある失敗パターンと回避方法" - "デバッグ手法" diff --git a/docs/rules-ja/typescript-testing.md b/docs/rules-ja/typescript-testing.md index 6fb3a9a..041b2ab 100644 --- a/docs/rules-ja/typescript-testing.md +++ b/docs/rules-ja/typescript-testing.md @@ -28,6 +28,13 @@ - 実際の依存関係を使用（DBやAPI等） - 主要な機能フローの検証 +3. **E2Eテストでの機能横断検証** + - 新機能追加時、既存機能への影響を必ず検証 + - Design Docの「統合ポイントマップ」で影響度「高」「中」の箇所をカバー + - 検証パターン: 既存機能動作 → 新機能有効化 → 既存機能の継続性確認 + - 判定基準: レスポンス内容の変化なし、処理時間5秒以内 + - CI/CDでの自動実行を前提とした設計 + ## Red-Green-Refactorプロセス（テストファースト開発） **推奨原則**: コード変更は必ずテストから始める diff --git a/docs/rules-ja/typescript.md b/docs/rules-ja/typescript.md index dd92334..6783482 100644 --- a/docs/rules-ja/typescript.md +++ b/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 = { ok: true; value: T } | { ok: false; error: E } From 129a8f646fcf46962d75df96ed8bc4c280c5b8a9 Mon Sep 17 00:00:00 2001 From: shinpr Date: Thu, 11 Sep 2025 13:37:40 +0900 Subject: [PATCH 2/2] feat: Add English translations for integration point analysis and fail-fast principles MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Mirror Japanese changes to English rule files for consistency - Add integration point mapping to technical-designer.md (EN) - Enhance E2E testing with cross-functional verification in typescript-testing.md (EN) - Include fail-fast principles in ai-development-guide.md and typescript.md (EN) - Update rules-index.yaml (EN) with AWS Builders' Library references Ensures AI execution precision maximization across both language environments with clear, concise English expressions optimized for LLM understanding. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .claude/agents-en/technical-designer.md | 23 +++++++++++++++++++++++ docs/rules-en/ai-development-guide.md | 17 +++++++++++++++++ docs/rules-en/rules-index.yaml | 3 +++ docs/rules-en/typescript-testing.md | 7 +++++++ docs/rules-en/typescript.md | 14 ++++++++++++++ 5 files changed, 64 insertions(+) diff --git a/.claude/agents-en/technical-designer.md b/.claude/agents-en/technical-designer.md index c4326c4..a72f341 100644 --- a/.claude/agents-en/technical-designer.md +++ b/.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: diff --git a/docs/rules-en/ai-development-guide.md b/docs/rules-en/ai-development-guide.md index c247219..12561c9 100644 --- a/docs/rules-en/ai-development-guide.md +++ b/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": diff --git a/docs/rules-en/rules-index.yaml b/docs/rules-en/rules-index.yaml index 9ed21a7..4093a74 100644 --- a/docs/rules-en/rules-index.yaml +++ b/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" diff --git a/docs/rules-en/typescript-testing.md b/docs/rules-en/typescript-testing.md index 6b8dc59..96822c1 100644 --- a/docs/rules-en/typescript-testing.md +++ b/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 diff --git a/docs/rules-en/typescript.md b/docs/rules-en/typescript.md index 5d8c8c7..2f50f1a 100644 --- a/docs/rules-en/typescript.md +++ b/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 = { ok: true; value: T } | { ok: false; error: E }