Effect-TS エキスパート

Effect ライブラリを使用した関数型プログラミングに関する専門的なガイダンス。エラーハンドリング、依存性の注入、 合成可能性、テストパターンをカバーします。

前提条件チェック

Effect 関連の作業を開始する前に、Effect-TS のソースコードが ~/.effect に存在することを確認してください。

もし見つからない場合は、直ちに停止してユーザーに通知してください。 以下を実行してクローンしてください:

git clone https://github.com/Effect-TS/effect.git ~/.effect

リサーチ戦略

Effect-TS には同じタスクを実現する多くの方法があります。特に中程度から高い複雑性のタスクで Effect パターンを使用する際は、Task ツールを使用してリサーチエージェントをプロアクティブに起動して、ベストプラクティスをリサーチしてください。

リサーチ対象 (優先順位順)

1. コードベースパターンを最初に確認 — 実装前に現在のプロジェクトにおける類似パターンを調査してください。Effect パターンがコードベースに存在する場合、一貫性のためにそれに従ってください。パターンが存在しない場合は、このステップをスキップしてください。

2. Effect ソースコード — 複雑な型エラー、不明な動作、または実装の詳細については、~/.effect/packages/effect/src/ の Effect ソースを確認してください。これは Effect の核となるロジックとモジュールを含みます。

リサーチが必要な場合

高優先度 (常にリサーチ):

• サービス、レイヤー、または複雑な依存性注入の実装
• 複数のエラータイプまたは複雑なエラー階層を使用したエラーハンドリング
• ストリームベースの操作とリアクティブパターン
• スコープ付きエフェクトとクリーンアップを使用したリソース管理
• 並行・並列操作とパフォーマンスクリティカルなコード
• テストパターン、特に不慣れなテストシナリオ

中優先度 (複雑な場合はリサーチ):

• 命令型コード (try-catch、Promise) を Effect パターンへリファクタリング
• 新しいサービス依存関係の追加またはサービスレイヤーの再構築
• カスタムエラータイプまたは既存のエラー階層の拡張
• 外部システム (データベース、API、サードパーティサービス) との統合

リサーチアプローチ

• 複数の関連パターンを調査する際は、複数の Task エージェントを同時に起動してください
• 巧妙な最適化よりも、正規的で読みやすく、保守性の高いソリューションの発見に焦点を当ててください
• 提案したアプローチを既存のコードベースパターンに対して検証し、一貫性を確保してください (パターンが存在する場合)
• 複数のアプローチが可能な場合、最も慣用的な Effect-TS ソリューションを見つけるためにリサーチしてください

コードベースパターンの発見

Effect を使用するプロジェクトで作業する場合、新しいコードを実装する前に既存のパターンを確認してください:

1. Effect のインポートを検索 — 'effect' からインポートするファイルを探して、既存の使用方法を理解してください
2. サービスパターンを識別 — プロジェクト内でサービスとレイヤーがどのように構成されているかを確認してください
3. エラーハンドリング規約を確認 — エラーがどのように定義され、伝播されているかを確認してください
4. テストパターンを調査 — プロジェクト内で Effect コードがどのようにテストされているかを確認してください

コードベースに Effect パターンが存在しない場合、Effect ソースと例から正規のパターンを使用して進めてください。 欠落しているコードベースパターンでブロックされないでください。

Effect の原則

Effect コードを作成する際、これらのコア原則を適用してください:

エラーハンドリング

• 例外を投げる代わりに Effect の型付きエラーシステムを使用してください
• 適切なエラー伝播を備えた説明的なエラータイプを定義してください
• エラー制御フロー用に Effect.fail、Effect.catchTag、Effect.catchAll を使用してください
• ./references/critical-rules.md で禁止パターンを確認してください

依存性注入

• サービスとレイヤーを使用した依存性注入を実装してください
• Context.Tag でサービスを定義してください
• Layer.merge、Layer.provide でレイヤーを構成してください
• Effect.provide を使用して依存関係を注入してください

合成可能性

• 複雑な操作のために Effect の合成可能性を活用してください
• 適切なコンストラクタを使用してください: Effect.succeed、Effect.fail、Effect.tryPromise、Effect.try
• スコープ付きエフェクトを使用した適切なリソース管理を適用してください
• Effect.flatMap、Effect.map、Effect.tap で操作をチェーンしてください

コード品質

• Effect の型システムを活用した型安全なコードを記述してください
• 読みやすい順序コード用に Effect.gen を使用してください
• Effect のテストユーティリティを使用した適切なテストパターンを実装してください
• 自動テレメトリと優れたスタックトレース用に Effect.fn() を優先してください

重要なルール

Effect コードを作成する前に ./references/critical-rules.md を読んで、内在化してください。主要なガイドライン:

• 非効果的: Effect.gen 内の try-catch (Effect の失敗はスローされません)
• 回避: 型アサーション (as never/any/unknown)
• 推奨: エラー用の return yield* パターン (終了を明示的にします)

よくある失敗モード

頻繁に問題を引き起こすパターンへのクイックリンク:

• SubscriptionRef バージョン不一致 — unsafeMake is not a function → runtime.md
• キャンセルと失敗 — インタラプトはエラーではありません → エラー分類
• Option と null — 内部では Option を使用し、境界では null を使用 → option-null.md
• Stream バックプレッシャー — 無限ストリームはハング → streams.md

ソリューションの説明

ソリューションを提供する際、使用されている Effect-TS の概念と、それが特定のユースケースに適切である理由を説明してください。ドキュメントにカバーされていないパターンに遭遇した場合は、既存のコードベースパターンとの一貫性を保ちながら改善を提案してください (パターンが存在する場合)。

クイックリファレンス

エフェクトの作成

Effect.succeed(value)           // 成功値をラップ
Effect.fail(error)              // 失敗したエフェクトを作成
Effect.tryPromise(fn)           // Promise を返す関数をラップ
Effect.try(fn)                  // 同期例外関数をラップ
Effect.sync(fn)                 // 同期非例外関数をラップ

エフェクトの合成

Effect.flatMap(effect, fn)      // エフェクトをチェーン
Effect.map(effect, fn)          // 成功値を変換
Effect.tap(effect, fn)          // 値を変更しない副作用
Effect.all([...effects])        // エフェクトを実行 (並行性設定可能)
Effect.forEach(items, fn)       // エフェクト付きで項目をマップ

// すべてのエラーを収集 (最初のエラーだけではない)
Effect.all([e1, e2, e3], { mode: "validate" })  // すべての失敗を返す

// 部分的成功の処理
Effect.partition([e1, e2, e3])  // [failures, successes] を返す

エラーハンドリング

// Data.TaggedError を使用した型付きエラーを定義 (推奨)
class UserNotFoundError extends Data.TaggedError("UserNotFoundError")<{
  userId: string
}> {}

// エラーの直接 yield (Effect.fail ラッパー不要)
Effect.gen(function* () {
  if (!user) {
    return yield* new UserNotFoundError({ userId })
  }
})

Effect.catchTag(effect, tag, fn) // 特定のエラータグを処理
Effect.catchAll(effect, fn)      // すべてのエラーを処理
Effect.result(effect)            // Exit 値に変換
Effect.orElse(effect, alt)       // フォールバックエフェクト

エラー分類

適切な処理のためにエラーを分類してください:

カテゴリ	例	処理
想定される却下	ユーザーキャンセル、拒否	グレースフルな終了、リトライなし
ドメインエラー	検証、ビジネスルール	ユーザーに表示、リトライなし
欠陥	バグ、アサーション	ログ + アラート、調査
インタラプション	ファイバーキャンセル、タイムアウト	クリーンアップ、リトライ可能
不明/外部	スロー例外	境界で正規化

// パターン: 境界で不明なエラーを正規化
const safeBoundary = Effect.catchAllDefect(effect, (defect) =>
  Effect.fail(new UnknownError({ cause: defect }))
)

// パターン: ユーザーが開始したキャンセルを個別に捕捉
Effect.catchTag(effect, "UserCancelledError", () => Effect.succeed(null))

// パターン: インタラプションを失敗と異なる方法で処理
Effect.onInterrupt(effect, () => Effect.log("Operation cancelled"))

パターンマッチング (Match モジュール)

Effect の Match モジュールを使用したパターンマッチングが必要な場合、references/pattern-matching.md を参照してください。

サービスとレイヤー / ジェネレータパターン

サービス定義パターン (Context.Tag、Effect.Service、Context.Reference、Context.ReadonlyTag) とジェネレータパターン (Effect.gen、Effect.fn) については、references/services-layers.md を参照してください。

ランタイムパターン (リソース管理、Duration、スケジューリング、State、SubscriptionRef、並行性)

リソースライフサイクル、Duration、スケジューリング、状態管理、リアクティブ ref、および並行性プリミティブについては、references/runtime.md を参照してください。

設定と環境変数

Config で設定を読み取る、Redacted で機密情報を処理する、またはカスタム設定プロバイダーを配線する必要がある場合、references/config.md を参照してください。

クイックユーティリティ (配列操作、ユーティリティ関数、非推奨)

Effect の Array/Order ソートヘルパー、constVoid のような小さなユーティリティ関数、および実行中の非推奨リストについては、references/quick-utils.md を参照してください。

追加リソース

ローカル Effect リソース

• ~/.effect/packages/effect/src/ — コア Effect モジュールと実装

外部リソース

• Effect-Atom — https://github.com/tim-smart/effect-atom (リアクティブ状態管理パターンについてブラウザで開く)

リファレンスファイル

• ./references/config.md — Config、Redacted、カスタム設定プロバイダー
• ./references/critical-rules.md — 禁止パターンと必須規約
• ./references/effect-atom.md — React 向け Effect-Atom リアクティブ状態管理
• ./references/next-js.md — Effect + Next.js 15+ App Router 統合パターン
• ./references/option-null.md — Option と null の境界パターン
• ./references/pattern-matching.md — タグ付きユニオンと条件文用の Match モジュール
• ./references/quick-utils.md — Array/Order、ユーティリティヘルパー、非推奨
• ./references/runtime.md — リソース管理、Duration、スケジューリング、State、SubscriptionRef、並行性
• ./references/services-layers.md — サービス、レイヤー、ジェネレータ (Effect.gen / Effect.fn)
• ./references/streams.md — ストリームパターンとバックプレッシャーの落とし穴
• ./references/testing.md — Vitest 決定論的テストパターン