effect-patterns-hub

Effect パターンハブ

目的：EffectPatterns リポジトリから厳選した 130 以上の Effect-TS パターンにすばやくアクセスできます。このスキルを使って、特定の実装パターンを探したり、アプローチを比較したり、ベストプラクティスを参照したりできます。

トリガー

• 特定の Effect パターンやイディオムを探している
• Effect の概念を実際の例で確認したい
• 同じ問題に対する複数のアプローチを見たい
• 実装戦略を比較したい
• Effect の新機能を学びたい

パターンライブラリの場所

ローカルパターン：.claude/skills/effect-patterns-hub/patterns/
ドキュメント：docs/effect-patterns/
件数：MDX 形式のパターンが 130 件以上

すばやく確認できる判断ツリー

必要な作業...

Effect の作成

• 値から作成 → constructor-succeed-some-right.mdx
• 同期コードから作成 → constructor-sync-async.mdx
• Promise から作成 → constructor-try-trypromise.mdx
• null 許容値から作成 → constructor-from-nullable-option-either.mdx
• 事前に解決済みの Effect → create-pre-resolved-effect.mdx

変換と合成

• 値をマップする → combinator-map.mdx
• Effect をチェーンする → combinator-flatmap.mdx
• 操作を順に実行する → combinator-sequencing.mdx
• 値を組み合わせる → combinator-zip.mdx
• フィルタリングする → combinator-filter.mdx
• 条件分岐を行う → combinator-conditional.mdx
• コレクションを処理する → combinator-foreach-all.mdx

制御フロー

• 順次実行するロジック → write-sequential-code-with-gen.mdx
• ビジネスロジック → use-gen-for-business-logic.mdx
• Pipe による合成 → use-pipe-for-composition.mdx
• 分岐するワークフロー → conditionally-branching-workflows.mdx
• コンビネーター → control-flow-with-combinators.mdx
• 繰り返し処理 → control-repetition-with-schedule.mdx

エラー処理

• エラーを定義する → define-tagged-errors.mdx
• 特定のエラーをキャッチする → pattern-catchtag.mdx
• すべてのエラーを処理する → handle-errors-with-catch.mdx
• 操作を再試行する → retry-based-on-specific-errors.mdx
• 不安定な操作を処理する → handle-flaky-operations-with-retry-timeout.mdx
• エラーをマップする → mapping-errors-to-fit-your-domain.mdx
• 予期しないエラーを処理する → handle-unexpected-errors-with-cause.mdx
• API エラー → handle-api-errors.mdx

Concurrency

• Parallel execution → run-effects-in-parallel-with-all.mdx
• Background tasks → run-background-tasks-with-fork.mdx
• Process collections → process-collection-in-parallel-with-foreach.mdx
• Race effects → race-concurrent-effects.mdx
• Fibers explained → understand-fibers-as-lightweight-threads.mdx
• Decouple with queues → decouple-fibers-with-queue-pubsub.mdx
• Polling → poll-for-status-until-task-completes.mdx
• Graceful shutdown → implement-graceful-shutdown.mdx

Services & Dependency Injection

• Model dependencies → model-dependencies-as-services.mdx
• Understand layers → understand-layers-for-dependency-injection.mdx
• Scoped services → scoped-service-layer.mdx
• Composable modules → organize-layers-into-composable-modules.mdx
• Compose scoped layers → compose-scoped-layers.mdx
• Provide config → provide-config-layer.mdx
• Caching wrapper → add-caching-by-wrapping-a-layer.mdx

Resource Management

• Bracket pattern → safely-bracket-resource-usage.mdx
• Scope management → manage-resource-lifecycles-with-scope.mdx
• Manual scope → manual-scope-management.mdx
• Scoped resources runtime → create-managed-runtime-for-scoped-resources.mdx

Streaming

• Process streaming data → process-streaming-data-with-stream.mdx
• From iterable → stream-from-iterable.mdx
• From file → stream-from-file.mdx
• From paginated API → stream-from-paginated-api.mdx
• Concurrent processing → stream-process-concurrently.mdx
• Batch processing → stream-process-in-batches.mdx
• Collect results → stream-collect-results.mdx
• Run for effects → stream-run-for-effects.mdx
• Manage resources → stream-manage-resources.mdx
• Retry on failure → stream-retry-on-failure.mdx

Schema & Validation

• Define contracts → define-contracts-with-schema.mdx
• Parse/decode → parse-with-schema-decode.mdx
• Transform data → transform-data-with-schema.mdx
• Validate body → validate-request-body.mdx
• Brand types → brand-model-domain-type.mdx
• Brand validation → brand-validate-parse.mdx
• Config schema → define-config-schema.mdx

データ型

• Option → data-option.mdx, model-optional-values-with-option.mdx
• Either → data-either.mdx, accumulate-multiple-errors-with-either.mdx
• Chunk → data-chunk.mdx, use-chunk-for-high-performance-collections.mdx
• Array → data-array.mdx
• HashSet → data-hashset.mdx
• Duration → data-duration.mdx, representing-time-spans-with-duration.mdx
• DateTime → data-datetime.mdx, beyond-the-date-type.mdx
• BigDecimal → data-bigdecimal.mdx
• Cause → data-cause.mdx
• Exit → data-exit.mdx
• Ref → data-ref.mdx, manage-shared-state-with-ref.mdx
• Redacted → data-redacted.mdx
• Case → data-case.mdx
• Class → data-class.mdx
• Struct → data-struct.mdx
• Tuple → data-tuple.mdx

パターンマッチング

• Match API → pattern-match.mdx
• Effectful match → pattern-matcheffect.mdx
• Tag matching → pattern-matchtag.mdx
• Option/Either checks → pattern-option-either-checks.mdx

HTTP と Web

• 基本的な HTTP サーバー → build-a-basic-http-server.mdx
• サーバーの起動 → launch-http-server.mdx
• GET の処理 → handle-get-request.mdx
• HTTP クライアントリクエスト → make-http-client-request.mdx
• テスト可能な HTTP クライアント → create-a-testable-http-client-service.mdx
• JSON レスポンス → send-json-response.mdx
• パスパラメーター → extract-path-parameters.mdx
• ルートへの依存関係の提供 → provide-dependencies-to-routes.mdx

テスト

• 依存関係のモック化 → mocking-dependencies-in-tests.mdx
• テストで Default レイヤーを使用する → use-default-layer-for-tests.mdx
• アプリケーションコードに適応するテストを書く → write-tests-that-adapt-to-application-code.mdx

オブザーバビリティ

• 構造化ロギング → leverage-structured-logging.mdx, observability-structured-logging.mdx
• トレーススパン → trace-operations-with-spans.mdx, observability-tracing-spans.mdx
• カスタムメトリクス → add-custom-metrics.mdx, observability-custom-metrics.mdx
• OpenTelemetry → observability-opentelemetry.mdx
• Effect.fn の計装 → observability-effect-fn.mdx

ランタイムと実行

• runPromise → execute-with-runpromise.mdx
• runSync → execute-with-runsync.mdx
• runFork → execute-long-running-apps-with-runfork.mdx
• 再利用可能なランタイム → create-reusable-runtime-from-layers.mdx

設定

• 設定へのアクセス → access-config-in-context.mdx
• スキーマの定義 → define-config-schema.mdx
• レイヤーの提供 → provide-config-layer.mdx

時間とスケジューリング

• 現在時刻 → accessing-current-time-with-clock.mdx
• 時間の長さ → representing-time-spans-with-duration.mdx
• DateTime → beyond-the-date-type.mdx
• スケジュールの繰り返し → control-repetition-with-schedule.mdx

プロジェクトのセットアップ

• 新規プロジェクト → setup-new-project.mdx
• エディター LSP → supercharge-your-editor-with-the-effect-lsp.mdx
• AI エージェント向け MCP → teach-your-ai-agents-effect-with-the-mcp-server.mdx

高度な概念

• 構造的等価性 → comparing-data-by-value-with-structural-equality.mdx
• Effect チャネル → understand-effect-channels.mdx
• Effect は遅延実行されます → effects-are-lazy.mdx
• 見つからない場合とエラーの区別 → distinguish-not-found-from-errors.mdx
• Promise の問題 → solve-promise-problems-with-effect.mdx
• 長いチェーンを避ける → avoid-long-andthen-chains.mdx

パターンのカテゴリー

スキルレベル別

初級（入門）

• コンストラクターパターン（succeed、fail、sync、async）
• 基本的なコンビネーター（map、flatMap、tap）
• シンプルなエラー処理（catch、catchTag）
• Effect.gen の基本
• runPromise/runSync

中級（アプリケーションの構築）

• サービスとレイヤー
• スキーマ検証
• HTTP サーバーとクライアント
• リソース管理
• 並行処理の基本（Effect.all、fork）
• モックを使ったテスト

上級（本番システム）

• 複雑なレイヤー合成
• カスタムランタイム
• ストリーミングパイプライン
• グレースフルシャットダウン
• OpenTelemetry との統合
• パフォーマンスの最適化（Chunk、Ref）

ユースケース別

ドメインモデリング

• スキーマ定義
• ブランド型
• タグ付きエラー
• オプション値や失敗する可能性のある値に対する Option/Either

API 開発

• HTTP サーバーのセットアップ
• ルート処理
• リクエストの検証
• エラー処理
• レスポンスのフォーマット

データ処理

• ストリーム処理
• バッチ処理
• 並列処理
• リソースセーフなパイプライン

アプリケーションアーキテクチャ

• サービスレイヤーの設計
• 依存性注入
• モジュール合成
• 設定管理

テスト

• モックレイヤー
• テストユーティリティ
• テスト可能なサービス

可観測性

• 構造化ログ
• 分散トレーシング
• カスタムメトリクス
• パフォーマンス監視

パターンの検索

キーワード別

Grep を使ってキーワードでパターンを検索します。

# Find patterns about error handling
grep -l "error" patterns/*.mdx

# Find patterns about concurrency
grep -l "concurrent\|parallel\|fiber" patterns/*.mdx

# Find patterns about HTTP
grep -l "http\|server\|client" patterns/*.mdx

# Find patterns about testing
grep -l "test\|mock" patterns/*.mdx

フロントマタータグ別

すべてのパターンにはメタデータが含まれています。

• title：人が読みやすい名前
• id：一意の識別子（拡張子を除いたファイル名）
• skillLevel：beginner、intermediate、advanced
• useCase：domain-modeling、error-handling、concurrency など
• summary：簡潔な説明
• tags：検索用キーワード
• related：関連パターンへのリンク

よくある検索

「...から Effect を作成するにはどうすればよいですか？」

• → コンストラクタのパターンを検索します：grep -l "constructor" patterns/*.mdx
• → constructor-*.mdx ファイルを確認します

「...の際にエラーを処理するにはどうすればよいですか？」

• → エラー処理を検索します：grep -l "error\|catch\|retry" patterns/*.mdx
• → handle-*.mdx と pattern-catchtag.mdx を確認します

「複数の処理を並行して実行するにはどうすればよいですか？」

• → 並行処理を検索します：grep -l "concurrent\|parallel\|all\|fork" patterns/*.mdx
• → run-effects-in-parallel-with-all.mdx を確認します

「サービスを扱うにはどうすればよいですか？」

• → サービスを検索します：grep -l "service\|layer\|dependency" patterns/*.mdx
• → model-dependencies-as-services.mdx と understand-layers-for-dependency-injection.mdx を確認します

「データを検証するにはどうすればよいですか？」

• → スキーマを検索します：grep -l "schema\|validate\|parse" patterns/*.mdx
• → define-contracts-with-schema.mdx と parse-with-schema-decode.mdx を確認します

他のスキルとの連携

Foundations → Patterns Hub

基礎概念の具体例が必要な場合は、パターンを確認します：

• effect-foundations では概念を学び、パターンでは実装方法を確認できます

Architect → Patterns Hub

システムを設計する際は、アーキテクチャパターンを参照します：

• レイヤーの合成 → organize-layers-into-composable-modules.mdx
• サービス設計 → model-dependencies-as-services.mdx
• スコープ付きリソース → scoped-service-layer.mdx

Engineer → Patterns Hub

機能を実装する際は、関連するパターンを探します：

• HTTP エンドポイント → handle-get-request.mdx、validate-request-body.mdx
• エラー処理 → retry-based-on-specific-errors.mdx
• 並行処理 → run-effects-in-parallel-with-all.mdx

Tester → Patterns Hub

テストを作成する際は、テストパターンを参照します：

• モックサービス → mocking-dependencies-in-tests.mdx
• テストレイヤー → use-default-layer-for-tests.mdx
• テスト可能な設計 → write-tests-that-adapt-to-application-code.mdx

使用ワークフロー

1. ニーズを特定する：「Effect で［何か］をしたい」
2. 判断ツリーを確認する：上記から該当するセクションを探します
3. パターンを読む：パターンファイルに対して Read ツールを使用します
4. 状況に合わせる：具体的なユースケースにパターンを適用します
5. 関連項目を確認する：パターンのフロントマターにある related リンクをたどります
6. エージェントに相談する：不明な点があれば、@effect-engineer または @effect-architect を使用します

アンチパターンの検出

次のような状況に気づいた場合：

• 命令型ループを使用している → process-collection-in-parallel-with-foreach.mdx を確認します
• Promise と Effects を混在させている → constructor-try-trypromise.mdx、solve-promise-problems-with-effect.mdx を確認します
• 長い andThen チェーンがある → avoid-long-andthen-chains.mdx、use-gen-for-business-logic.mdx を確認します
• 要件が漏れている → model-dependencies-as-services.mdx を確認します
• リソースを手動でクリーンアップしている → safely-bracket-resource-usage.mdx を確認します

パターンファイルの構造

各パターンファイルは次の構造に従います：

---
title: Human-readable title
id: kebab-case-id
skillLevel: beginner | intermediate | advanced
useCase: primary-use-case
summary: Brief description
tags:
  - keyword1
  - keyword2
related:
  - related-pattern-id-1
  - related-pattern-id-2
author: Author name
---

# Title

## Guideline
What to do

## Rationale
Why do it this way

## Good Example
✅ Recommended approach

## Bad Example
❌ What to avoid

## Related Patterns
Links to related patterns

メンテナンス

パターンは EffectPatterns リポジトリ から同期されます。

パターンを更新するには：

cd /tmp
git clone --depth=1 https://github.com/PaulJPhilp/EffectPatterns.git
cp -r EffectPatterns/content/published/* /Users/pooks/Dev/crate/.claude/skills/effect-patterns-hub/patterns/
cp -r EffectPatterns/content/published/* /Users/pooks/Dev/crate/docs/effect-patterns/

まとめ

• 130 以上のパターンで、Effect-TS のすべての概念を網羅
• 判断ツリーでパターンをすばやく検索
• 既存のスキルやエージェントとの連携
• キーワード、ユースケース、スキルレベルで検索可能
• 良い例と悪い例を示すサンプル
• より深く調べるための関連パターン

「Effect で...するにはどうすればよいですか？」という疑問が生じたら、このスキルをいつでも参照してください。