effect-v4

Effect v4

Effect v4 はモデルのトレーニングデータにほとんど含まれておらず、effect.website のドキュメントは v3 のものです。思い出した API は正しそうに見えても、実際には間違っています。ベータ版の変更は単調ではありません。他のベータ版で見たパターンは、検証するための手がかりであって事実ではありません。また、公式ドキュメントでさえ、リリース済みのコードに追いついていないことがあります（migration/yieldable.md では、存在しない .asEffect() がいまだに説明されています）。これらとソースコードの記述が異なる場合は、ソースコードを優先してください。

タスクで明示的に変更する場合を除き、確立されたプロジェクトの規約を優先してください。

ソースの規則

推測する前に、次の内容を上から順に確認してください。上にあるものほど権威があります。

1. プロジェクトにインストールされている node_modules/effect の型定義 — 最終的な判断基準です。
2. リポジトリにベンダー提供されている場合は、プロジェクトのバージョンに対応するタグの Effect ソースコードの固定チェックアウト。
3. そのチェックアウトに含まれる公式ドキュメント：LLMS.md、ai-docs/src/**、migration/**、packages/effect/SCHEMA.md。
4. これらのリファレンスファイル。

Effect のコードを書く前に、プロジェクトで固定されているバージョンを明記してください。

参照するファイル

タスクに必要なものだけを読んでください。

タスク	読むファイル
サービスやシームを設ける基準、コーディネーターとストアの分割、コントラクト優先、設計レビュー	references/architecture.md
サービス、レイヤー、DI、provide の場所、Effect.fn	references/services-layers.md
型付きエラー、捕捉、復旧、欠陥	references/errors.md
再試行／繰り返しポリシー、ポーリング、TTL キャッシュ	references/schedule-cache.md
Schema、信頼できない入力の解析、ドメインモデリング	references/schema-boundaries.md
テスト、フェイク、TestClock、プロパティテスト	references/testing.md
エントリーポイント、ランタイム、Config、CLI、オブザーバビリティ	references/runtime-config.md
v3 コードの移植、または「存在するはず」の API	references/v3-to-v4.md
モジュールのパッケージまたはインポートパス	references/module-paths.md

タスクが複数の項目にまたがる場合は、編集前に該当するファイルをすべて読んでください。

基本方針

状況	使用するもの
サービスを定義する	class X extends Context.Service<X, Shape>()("pkg/dir/X") {}
実装を追加する	static readonly layer = Layer.effect(X, ...) を使い、X.of({...}) を返します
Effect を返す関数に名前を付ける	Effect.fn("X.method")(function* () {...})
Effect.fn にコンビネーターを追加する	末尾の引数を使います — .pipe は使いません
エラーを定義する	class E extends Schema.TaggedErrorClass<E>()("E", {...}) {}
エラーを発生させる	return yield* E.make({...}) — return が必要です
捕捉する	Effect.catchTag／catchTags。チャネル全体には Effect.catch を使います
外部の原因をラップする	cause: Schema.Defect()
信頼できない入力をデコードする	Schema.decodeUnknownEffect(S)(input)
スキーマを絞り込む	.check(Schema.isMinLength(1))
ドメイン値をモデル化する	Schema.Class。構造的な形状には Schema.Struct を使います
設定を読み込む	Config.*。process.env は使いません
現在時刻／乱数	Clock、DateTime、Random — Date.now、Math.random は使いません
ファイル、パス、ターミナル	コア effect の FileSystem、Path — node:fs は使いません
プログラムを実行する	NodeRuntime.runMain／BunRuntime.runMain
テストを書く	@effect/vitest の assert を使った it.effect
レイヤーを provide する	依存関係を閉じるレイヤーの内部、およびプロセスのルートで一度だけ — それ以外では行いません

レイヤーの命名

layer（本番用） · layerNoDeps（依存関係を RIn に残す） · layerFake · layerTest · layerInProcess · layerInMemoryStore · layerFromEnv

Live のサフィックスは使いません。汎用的な layerMemory も使いません。

強制適用プリセット

このスキルには、以下のルールをチェックする読み取り専用チェッカーが付属しています。レビュー前、または大幅な編集後にプロジェクトに対して実行してください。

nu <path-to-this-skill>/scripts/check-effect.nu <project-dir> [source-paths...]

プリセットを assets/ から読み込み、effect-tsgo の診断、oxlint、ast-grep を実行します。対象には書き込まず、対象にツールがないため実行できないゲートはスキップとして報告します。診断をプロジェクトの tsconfig／エディターに恒久的に組み込むのは、プロジェクト側で行う作業です：npx @effect/tsgo setup。

assets/tsconfig-compiler-options.json は、診断が前提とする厳格さの基準です。tsconfig-language-service.json と併せて拡張してください。strict がなければ noImplicitAny は有効にならず、effectFnImplicitAny は何もせずに終了します。

effect-tsgo patch は 冪等ではありません。インストール済みの tsc バイナリをその場でパッチします。適用済みの場合、tsc --version は +effect-tsgo.<version> というサフィックスを報告します。したがって、サフィックスがない場合、またはインストール済みの @effect/tsgo のバージョンと一致しない場合にのみパッチを適用してください。"prepare": "effect-tsgo patch" だけを設定すると、すでにパッチ済みのコンパイラーに再度パッチが適用されます。

アダプターの例外

アダプターファイルにはベンダー固有の事情が持ち込まれるため、一部の診断はそこで適用を緩める必要があります。必要最小限の範囲で抑制してください。

• ファイル先頭の // @effect-diagnostics <rule>:off — 推奨する方法です。プロジェクト内のプラグイン overrides エントリーは、--lspconfig で設定を注入するランナーによって破棄されます（プロジェクトのプラグイン設定を 置き換える ためです）。プラグマはどちらの方法でも維持されます。references/runtime-config.md を参照してください。
• leakingRequirements に限っては、言語サービスで使える JSDoc の例外が 2 つあります。受け渡しが意図された依存関係のインターフェース宣言に @effect-leakable-service を付ける方法と、依存関係を漏らすサービスに @effect-expect-leaking <Type> を付ける方法です。

例外を設けることは、ベンダーとの境界が確かに存在するという主張です。1 つのファイルに複数の例外が必要なら、境界の引き方が誤っています。

禁止事項

• Effect.gen の内部で try／catch を使わないでください。Effect の失敗を検知できません。代わりに Effect.result を使って分岐してください。
• async／await や通常の Promise を使わないでください。境界を越えるときは Effect.tryPromise を使ってください。
• ライブラリーコードで Effect.runPromise／runSync／runFork を呼び出さないでください。
• 本体が Effect.gen を返すだけの通常の関数を書かないでください。Effect.fn を使ってください。
• Effect の型付けを回避するために as any、as unknown as、非 null アサーションの !、未検証のキャストを使わないでください。代わりに分岐、解析、または型の絞り込みを行ってください。
• JSON.parse(x) as T を使わないでください。スキーマを通してデコードしてください。
• isString のような型ガードを独自に実装しないでください。Predicate を使ってください。
• リトライ／ポーリングループや TTL キャッシュを独自に実装しないでください。Schedule と Cache を使ってください。
• 設定、状態、調整、復旧の処理で Effect.orDie を使わないでください。
• v3 パッケージをインポートしないでください：@effect/platform、@effect/schema、@effect/cli、@effect/rpc、@effect/cluster、@effect/experimental。
• Context.Tag、Context.GenericTag、Effect.Tag、または ServiceMap という名前のものを使わないでください。いずれも v4 より前、または中間ベータ版の名前です。
• コンパイルを通すためだけに Layer.mergeAll や provideMerge を使わないでください。