architecture-patterns

アーキテクチャパターン

概要

アーキテクチャは機能を支えるために存在します。すべてのアーキテクチャ上の決定は、機能要件にたどり着ける必要があります。

基本原則： 機能のためにアーキテクチャを設計するのであり、アーキテクチャのために機能を設計するのではありません。

このスキルは v10 では助言的なものです。意思決定とトレードオフを整理するものであり、明示的なユーザー要件、リポジトリの標準、承認済みの計画／設計ドキュメントより優先されるものではありません。

注力領域（参照パターン）

• 適切なバージョニングとエラー処理を備えた RESTful API 設計
• サービス境界の定義とサービス間通信
• データベーススキーマ設計（正規化、インデックス、シャーディング）
• キャッシュ戦略とパフォーマンスの最適化
• 基本的なセキュリティパターン（認証、レート制限）

絶対原則

NO ARCHITECTURE DESIGN BEFORE FUNCTIONALITY FLOWS ARE MAPPED

ユーザーフロー、管理者フロー、システムフローを文書化していないなら、アーキテクチャを設計することはできません。

受付時の振り分け

まず、必要なアーキテクチャ作業の種類を判断します。

リクエストの種類	振り分け先
「API エンドポイントを設計する」	API 設計のセクション
「システムアーキテクチャを計画する」	アーキテクチャ設計全体
「データモデルを設計する」	データモデルのセクション
「統合を計画する」	統合パターンのセクション
「意思決定を行う」	意思決定フレームワークのセクション

共通の質問（最初に回答）

設計の前に必ず回答します。

1. どのような機能を構築するのか？ - 技術的な機能ではなく、ユーザーストーリー
2. アクターは誰か？ - ユーザー、管理者、外部システム
3. ユーザーフローは何か？ - ユーザーの操作を順を追って示したもの
4. システムフローは何か？ - 内部処理の手順
5. どのような統合があるか？ - 外部依存関係
6. 制約は何か？ - パフォーマンス、セキュリティ、コンプライアンス
7. どのような可観測性が必要か？ - ログ、メトリクス、監視、アラート

機能優先の設計プロセス

フェーズ 1：機能フローを整理する

アーキテクチャを検討する前に：

User Flow (example):
1. User opens upload page
2. User selects file
3. System validates file type/size
4. System uploads to storage
5. System shows success message

Admin Flow (example):
1. Admin opens dashboard
2. Admin views all uploads
3. Admin can delete uploads
4. System logs admin action

System Flow (example):
1. Request received at API
2. Auth middleware validates token
3. Service processes request
4. Database stores data
5. Response returned

フェーズ 2：アーキテクチャに対応付ける

各フローをコンポーネントに対応付けます。

フローステップ	アーキテクチャコンポーネント
ユーザーがページを開く	フロントエンドのルート＋コンポーネント
ユーザーがデータを送信する	API エンドポイント
システムが検証する	検証サービス
システムが処理する	ビジネスロジックサービス
システムが保存する	データベース＋リポジトリ
システムが連携する	外部クライアント／アダプター

フェーズ 3：コンポーネントを設計する

各コンポーネントについて、次を定義します。

• 目的：どの機能を支えるか
• 入力：どのようなデータを受け取るか
• 出力：どのようなデータを返すか
• 依存関係：何が必要か
• エラー処理：何が失敗する可能性があるか

アーキテクチャビュー

システムコンテキスト（C4 レベル 1）

┌─────────────────────────────────────────────┐
│                 SYSTEM                       │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐     │
│  │   Web   │  │   API   │  │Database │     │
│  │   App   │──│ Service │──│         │     │
│  └─────────┘  └─────────┘  └─────────┘     │
└─────────────────────────────────────────────┘
       │              │              │
    ┌──┴──┐        ┌──┴──┐        ┌──┴──┐
    │User │        │Admin│        │ Ext │
    └─────┘        └─────┘        └─────┘

コンテナビュー（C4 レベル 2）

• Web アプリ：React/Vue/Angular のフロントエンド
• API サービス：REST/GraphQL のバックエンド
• データベース：PostgreSQL/MongoDB など
• キャッシュ：Redis/Memcached
• キュー：非同期処理用の RabbitMQ/SQS

コンポーネントビュー（C4 レベル 3）

• コントローラー：HTTP リクエストを処理する
• サービス：ビジネスロジック
• リポジトリ：データアクセス
• クライアント：外部連携
• モデル：データ構造

LSP を活用したアーキテクチャ分析

LSP を使って実際のコード依存関係を把握します。

アーキテクチャタスク	LSP ツール	出力
コンポーネントの依存関係を把握する	lspCallHierarchy(outgoing)	各コンポーネントが使用するもの
サービスの全利用箇所を見つける	lspCallHierarchy(incoming)	影響分析
インターフェースの実装を確認する	lspFindReferences	すべての実装箇所
データフローを追跡する	lspCallHierarchy の呼び出しを連鎖させる	フロー全体のマップ

実際のアーキテクチャを把握する：

1. localSearchCode("ServiceName") → find entry points
2. lspCallHierarchy(outgoing) → map dependencies
3. For each dependency: repeat step 2
4. Build dependency graph from results

アーキテクチャ図を描く前に LSP を使用します - コードで前提を検証してください。

重要： まず localSearchCode から lineHint を取得してください。行番号を推測してはいけません。

API 設計（機能に沿った設計）

ユーザーフローをエンドポイントに対応付けます：

User Flow: Upload file
→ POST /api/files
  Request: { file: binary, metadata: {...} }
  Response: { id: string, url: string }
  Errors: 400 (invalid), 413 (too large), 500 (storage failed)

User Flow: View file
→ GET /api/files/:id
  Response: { id, url, metadata, createdAt }
  Errors: 404 (not found), 403 (not authorized)

Admin Flow: Delete file
→ DELETE /api/files/:id
  Response: { success: true }
  Errors: 404, 403

API 設計チェックリスト：

• 各エンドポイントがユーザー／管理者フローに対応している
• リクエストスキーマがフローの入力と一致している
• レスポンススキーマがフローの出力と一致している
• すべての失敗ケースをエラーで網羅している
• 認証／認可要件が文書化されている

統合パターン

統合要件をパターンに対応付けます：

要件	パターン
不安定な外部サービス	指数バックオフによる再試行
応答の遅い外部サービス	サーキットブレーカー＋タイムアウト
非同期処理が必要	メッセージキュー
リアルタイム更新が必要	WebSocket/SSE
データ同期が必要	イベントソーシング

各統合について：

### [Integration Name]

**Functionality**: What user flow depends on this?
**Pattern**: [Retry/Circuit breaker/Queue/etc]
**Error handling**: What happens when it fails?
**Fallback**: What's the degraded experience?

依存関係の分類

パターンを選ぶ前に、依存関係を分類します：

カテゴリ	例	テスト戦略
プロセス内	純粋な計算、メモリ内状態	直接テストする — モジュールを統合して検証する
ローカルで代替可能	データベース（PGLite）、ファイルシステム（メモリ内 FS）	テストスイートでローカルの代替物を使ってテストする
リモートだが自社所有	自社のマイクロサービス、内部 API	ポート（インターフェース）を定義し、トランスポートを注入する。メモリ内アダプターでテストする
真の外部依存	Stripe、Twilio、サードパーティ API	境界でモック化する。依存関係をポートとして注入する

カテゴリによってパターンが決まります。プロセス内には何も必要ありません。真の外部依存にはモックが必要です。中間の 2 つにはポートとアダプターが必要です。

実装の順序 — 葉から内側に向かって構築します：

Level 0 (no deps):      [Pure utils] [Config]
        ↓
Level 1 (Level 0 only): [Repositories] [External clients]
        ↓
Level 2 (Level 0-1):    [Services]
        ↓
Level 3 (Level 0-2):    [Controllers] [API routes]

レベル 0 のコンポーネントはすぐにテストできます。その後の各レベルは、先行するレベルだけに依存します。この順序により、初期段階でモックに頼るテストをなくし、プランナーの DAG 制約（フェーズは先行フェーズのみに依存し、後続フェーズには依存しない）にも沿います。

可観測性の設計

各コンポーネントについて、次を定義します：

項目	質問
ロギング	どのイベントを記録しますか？どのレベルですか？構造化形式ですか？
メトリクス	何を測定しますか？カウンター、ゲージ、ヒストグラムですか？
アラート	しきい値は何ですか？誰に通知しますか？
トレーシング	スパンの境界はどこですか？相関 ID は何ですか？

最低限の可観測性：

• 境界でのリクエスト／レスポンスのロギング
• エラー率とレイテンシ
• ヘルスチェックエンドポイント
• 相関 ID の伝播

意思決定フレームワーク

各アーキテクチャ上の決定について：

### Decision: [Title]

**Context**: What functionality requirement drives this?

**Options**:
1. [Option A] - [Brief description]
2. [Option B] - [Brief description]
3. [Option C] - [Brief description]

**Trade-offs**:
| Criterion | Option A | Option B | Option C |
|-----------|----------|----------|----------|
| Performance | Good | Better | Best |
| Complexity | Low | Medium | High |
| Cost | Low | Medium | High |

**Decision**: [Option chosen]

**Rationale**: [Why this option best supports functionality]

危険信号 — 停止して再設計してください

次のような状況に陥った場合：

• フローを整理する前にアーキテクチャを設計している
• 明確な機能上の理由なくコンポーネントを追加している
• 「ベストプラクティスだから」という理由でパターンを選んでいる
• 想定上のスケールに対して過剰に設計している
• 既存のアーキテクチャパターンを無視している
• トレードオフを文書化せずに決定している

停止してください。機能フローに戻ってください。

シンプルに保つ（参考パターン）

バックエンドアーキテクチャのアプローチ：

1. 明確なサービス境界から始めます
2. API をコントラクトファーストで設計します
3. データの整合性要件を考慮します
4. 初日から水平スケーリングを計画します
5. シンプルに保ちます — 早すぎる最適化を避けます

アーキテクチャ成果物のチェックリスト：

• リクエスト／レスポンスの例を含む API エンドポイント定義
• サービスアーキテクチャ図（mermaid または ASCII）
• 主要な関係を含むデータベーススキーマ
• 簡潔な根拠を添えた技術選定の推奨事項
• 潜在的なボトルネックとスケーリング上の考慮事項

必ず具体例を示してください。理論よりも実践的な実装に重点を置いてください。

正当化の防止

言い訳	実情
「このパターンは業界標準です」	この機能を支えていますか？
「後で必要になるかもしれません」	YAGNI。今必要なものを設計します。
「マイクロサービスのほうが優れています」	この機能にとってですか？その理由を示してください。
「誰もが使っています」	それはトレードオフの分析ではありません。
「より柔軟です」	必要のない柔軟性は、複雑さにつながります。

出力形式

# Architecture Design: [Feature/System Name]

## Functionality Summary
[What this architecture supports - trace to user value]

## Flows Mapped

### User Flows
1. [Flow 1 steps]
2. [Flow 2 steps]

### System Flows
1. [Flow 1 steps]
2. [Flow 2 steps]

## Architecture

### System Context
[Diagram or description of actors and system boundaries]

### Components
| Component | Purpose (Functionality) | Dependencies |
|-----------|------------------------|--------------|
| [Name] | [What flow it supports] | [What it needs] |

### API Endpoints
| Endpoint | Flow | Request | Response |
|----------|------|---------|----------|
| POST /api/x | User uploads | {...} | {...} |

## Key Decisions

### Decision 1: [Title]
- Context: [Functionality driver]
- Options: [List]
- Trade-offs: [Table]
- Decision: [Choice]
- Rationale: [Why]

## Implementation Roadmap

### Critical (Must have for core flow)
1. [Component/feature]

### Important (Completes flows)
1. [Component/feature]

### Enhancement (Improves experience)
1. [Component/feature]

最終確認

アーキテクチャ設計を完了する前に：

• すべてのユーザーフローがマッピングされている
• すべてのシステムフローがマッピングされている
• 各コンポーネントが機能にひも付いている
• 各 API エンドポイントがフローにひも付いている
• トレードオフを含めて意思決定が文書化されている
• 実装ロードマップに優先順位が付けられている