effect-ts

Effect-TS

概要

Effect をベースとする TypeScript プログラムの構築に役立つワークフロー、パターン、ベストプラクティスを提供します。エラー、依存関係、リソース、ランタイム実行、ジェネレーター、スキーマ、テスト、プラットフォームモジュール、シンク／ストリーム処理、Effect AI に関する要点を絞ったリファレンスも提供します。

主なドキュメントと API の情報源：

• https://effect.website/llms.txt （LLM 向けトピックインデックス）
• https://effect.website/docs
• https://effect.website/docs/platform
• https://effect.website/docs/ai/introduction
• https://effect.website/docs/additional-resources/api-reference
• https://tim-smart.github.io/effect-io-ai/ （簡潔な API 一覧）

内部で情報を調べる際は、effect-docs MCP を使って API リファレンスを検索・取得できます：https://github.com/tim-smart/effect-mcp。

段階的な情報開示

1. トピックの参照先を確認するため、references/docs-index.md から始めます。
2. タスクに合った主要なガイドを 1 つ読みます。
3. 必要な場合に限り、関連するガイドを 1 つ読みます（テスト、ランタイム、オブザーバビリティなど、横断的な関心事について）。
4. 関係のないリファレンスの読み込みは避けます。

クイックトリアージ

• Effect のコアデータ型やコンビネーターが必要な場合は、references/core-usage.md を開きます。
• より幅広いデータ型の選択肢（DateTime、BigDecimal、HashSet、Redacted）が必要な場合は、references/data-types-advanced.md を開きます。
• 等価性・順序・ハッシュのセマンティクスが必要な場合は、references/behavior-traits.md を開きます。
• エラーモデリングや型付き失敗がタスクに関係する場合は、references/error-management.md を開きます。
• エラー処理ツール（サンドボックス化、Cause、エラーチャネル変換）が必要な場合は、references/error-tooling.md を開きます。
• サービスや依存関係が関係する場合は、references/dependency-management.md を開きます。
• レイヤーの構築やテストの配線が関係する場合は、references/layer-patterns.md を開きます。
• リソースのライフサイクルが関係する場合は、references/resource-management.md を開きます。
• エフェクトの実行やランタイムの選択が関係する場合は、references/runtime-execution.md を開きます。
• ファイバーや並行処理プリミティブが関係する場合は、references/concurrency.md を開きます。
• 中断、監視、ファイバー参照が関係する場合は、references/concurrency-advanced.md を開きます。
• スケジュールや反復処理が関係する場合は、references/scheduling.md を開きます。
• リトライ、バックオフ、スケジュールの合成が関係する場合は、references/scheduling-retry.md を開きます。
• ストリーム、キュー、PubSub、STM が関係する場合は、references/streams-queues-stm.md を開きます。
• HTTP クライアントや外部 API が関係する場合は、references/http-client.md を開きます。
• HTTP サーバーや API 定義が関係する場合は、references/http-server.md を開きます。
• リクエストのバッチ処理やデータローダーが関係する場合は、references/request-resolver.md を開きます。
• キャッシュやメモ化が関係する場合は、references/caching.md を開きます。
• 設定や設定プロバイダーが関係する場合は、references/configuration.md を開きます。
• 高度な設定や機密情報のマスキングが関係する場合は、references/configuration-advanced.md を開きます。
• ログ、メトリクス、トレースが関係する場合は、references/observability.md を開きます。
• 具体的なロガー／メトリクス／トレースの設定やエクスポーターが必要な場合は、references/observability-examples.md を開きます。
• ログ／メトリクス／トレースのレイヤーの配線が必要な場合は、references/observability-wiring.md を開きます。
• 順次処理や分岐処理を読みやすくする必要がある場合は、references/generators.md を開きます。
• 実行時の検証やデコードが必要な場合は、references/schema.md を開きます。
• リデューサーを使ったストリーム消費パターンが関係する場合は、references/sink.md を開きます。
• テストで決定論的な時間が必要な場合は、references/testing.md を開きます。
• より幅広いテスト用サービスが必要な場合は、references/testing-stack.md を開きます。
• コマンド／ファイル／パス／ターミナル／キーと値のモジュールが関係する場合は、references/platform-primitives.md を開きます。
• Effect AI を介した LLM ワークフロー、計画、ツール使用が関係する場合は、references/ai.md を開きます。
• バンドルサイズに制約のあるランタイムが関係する場合は、references/micro.md を開きます。
• Promise／async からの移行が関係する場合は、references/migration-async.md を開きます。
• バージョニングやシグネチャの変更が必要な場合は、references/versioning.md を開きます。
• よくある落とし穴やランタイムエラーが発生した場合は、references/troubleshooting.md を開きます。
• 結果の確認やデバッグが必要な場合は、references/exit-cause.md を開きます。
• llms.txt からドキュメントとガイドの対応表が必要な場合は、references/docs-index.md を開きます。

コアワークフロー

1. 境界と入出力を明確にし、コアロジックは Effect の値として保持します。
2. スタイルを選びます。単純な合成にはパイプラインを使い、逐次処理には Effect.gen を使います。
3. エラーを明示的にモデル化します。想定されるエラーは型付けし、欠陥は予期しない失敗として扱います。
4. サービス、タグ、レイヤーで依存関係をモデル化し、インターフェースに構築上の関心事を持ち込まないようにします。
5. リソースを開閉する際は、Scope を使ってライフサイクルを管理します。
6. レイヤーを介して環境を提供し、プログラムの境界でのみエフェクトを実行します。
7. プラットフォーム／インフラのコードでは、副作用を専用のアダプターに閉じ込め、ドメインコードには型付きサービスを公開します。
8. エージェントのタスクでは、エラー、並行処理、ランタイムの選択理由を簡潔に記載します。

出力基準

• インポートと、最小限の実行可能な例を示してください。
• 深いモジュールパスよりも、バレルインポート（from "effect"／from "@effect/platform"）を優先してください。
• 関数型の合成のほうが明確な場合は、effect の pipe を使用してください。
• 依存関係グラフ（サービス、レイヤー、コンテキストタグ）を明示してください。
• エラーチャネルの型を含め、想定されるエラーと欠陥エラーを明確にしてください。
• ライブラリ内でエフェクトを実行することは避け、エントリーポイントやテストでのランタイムの使用方法を示してください。
• 現行の Effect メジャーバージョンでコンパイルできる例を優先してください。

エージェントの品質チェックリスト

• 設計上の判断に役立つ場合は、対象の型を Effect<A, E, R> として明示してください。
• 想定されるエラー（E）と欠陥エラーを明確に分けてください。
• レイヤーを提供する場所と、run* を呼び出す場所を特定してください。
• 並行処理のコードでは、並行処理数に上限があるかどうかと、シャットダウンの方法を明記してください。
• 境界でのデコードでは、Schema の使用方法と失敗への対処箇所を示してください。
• テストでは、提供するテストサービス（TestContext、TestClock、ライブのオーバーライド）を記載してください。
• ドキュメントに不明な点がある場合は、API を確定する前に references/docs-index.md とソースドキュメントを確認してください。

参考資料

• 関連するガイドをすばやく選ぶには、まず references/docs-index.md を確認してください。
• ほとんどのコードタスクでは、references/core-usage.md、references/error-management.md、references/dependency-management.md を標準として使用してください。
• 境界処理や統合には、プラットフォーム／ランタイムの参考資料（references/platform-primitives.md、references/runtime-execution.md）を使用してください。
• 検証とデバッグには、テスト／診断の参考資料（references/testing.md、references/testing-stack.md、references/troubleshooting.md）を使用してください。