菜单
Use if building TypeScript with Effect-TS v3 — Effect.gen, Layer, Schema, typed errors, Stream.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Use skill if you are exhaustively testing or release-gating martool CLI commands in a source checkout or deployed Coolify container over SSH, without local Docker or provider spend.
Use if driving agent-browser for Chrome/CDP automation, @ref snapshots, tabs, or verification.
Use if testing or debugging an iOS app via agent-device CLI — simulator flows, evidence, bug triage.
Use if supervising Jean agents through MCP and Computer Use for monitoring, recovery, or closure.
Use if auditing or designing a CLI for agent/LLM use — JSON output, exit codes, non-interactive.
Use if auditing or designing an MCP server for agent-readiness — framework, security, context.
| name | build-effect-ts-v3 |
| description | Use if building TypeScript with Effect-TS v3 — Effect.gen, Layer, Schema, typed errors, Stream. |
Build production-grade TypeScript applications with Effect-TS v3. Effect<A, E, R> is a lazy, typed, immutable description of work; services and layers carry dependencies; Schema validates boundaries; fibers run structured concurrency; Stream carries pull-based async data. Ecosystem: @effect/platform, @effect/sql (+ 11 driver packages), @effect/rpc, @effect/cli, @effect/vitest, @effect/opentelemetry, plus @effect-atom/atom-react for React.
For the structured index of every reference file, read references/00-reference-map.md.
effect@3.x)effect packageimport { Effect, Layer, Schema, Stream } from "effect", Effect.gen(function*() { yield* … }), class X extends Effect.Service<X>()(...), class E extends Schema.TaggedError<E>("Tag")(...), Layer.provideMerge, Effect.fn("Service.method")@effect/platform, CLIs with @effect/cli, RPC with @effect/rpc, SQL with @effect/sql, tests with @effect/vitest, OTel with @effect/opentelemetry@effect-atom/atom-reactfp-ts / neverthrow / RxJS code to Effect, or operating in gradual-adoption / portable-utility modeDo NOT use this skill for:
ServiceMap.Service, Schema.TaggedErrorClass, bare Effect.catch, Effect.forkChild, Effect.forkDetach, Schema.makeUnsafe, Result module) is forbidden, see references/anti-patterns/19-v4-syntax-do-not-use.mdfp-ts, neverthrow, or RxJS codebases that do not plan to adopt Effect — only the migration/ docs apply| Rule | Recovery |
|---|---|
Do not import from @effect/schema — deprecated since 3.10. Use import { Schema } from "effect" | references/schema/20-deprecated-effect-schema.md |
Do not use v4 syntax: ServiceMap.Service, Schema.TaggedErrorClass, bare Effect.catch, Effect.forkChild, Effect.forkDetach, Schema.makeUnsafe, Result module | references/anti-patterns/19-v4-syntax-do-not-use.md |
Do not throw inside Effect.gen — it becomes a defect. Use return yield* new TaggedError({...}) or Effect.fail(...) | references/anti-patterns/03-throw-in-gen.md |
Do not write yield fx (no *) inside Effect.gen — yields the Effect object, not its value. Always yield* fx | references/anti-patterns/02-yield-without-star.md |
Do not call Effect.runPromise / Effect.runSync inside library, service, or middleware code — only at program edges | references/anti-patterns/04-runpromise-mid-code.md, references/anti-patterns/12-runsync-in-services.md |
Do not call Effect.all([...]) / Effect.forEach(...) / Stream.mapEffect without { concurrency: N } on lists > 5 items | references/anti-patterns/05-unbounded-parallelism.md, references/concurrency/07-bounded-parallelism.md |
Do not use try / finally for cleanup — bypasses interruption. Use Effect.acquireRelease or Effect.ensuring | references/anti-patterns/15-manual-cleanup.md |
Do not put null / undefined in domain types — use Option<T> | references/anti-patterns/10-null-undefined-domain.md |
Do not use console.log — use Effect.log / logInfo / logError | references/anti-patterns/08-console-log.md |
Do not read process.env directly — use Config.string("X") / Config.redacted("X") | references/anti-patterns/09-process-env.md |
Do not use Option.getOrThrow — use Option.match | references/anti-patterns/11-option-getorthrow.md |
Do not use as never / as any / as unknown to silence Effect type errors — find the real cause | references/anti-patterns/17-type-assertions.md |
Do not catch with catchAll when catchTag / catchTags would preserve narrowing | references/anti-patterns/06-catchall-vs-catchtag.md |
Do not invent generic error names (NotFoundError, Error) — use specific tagged errors (UserNotFoundError) so catchTag dispatches precisely | references/anti-patterns/07-generic-error-types.md |
| Do not call parameterized layer constructors inline at provide-sites — store layers in module-level constants for memoization | references/anti-patterns/14-inline-layer-construction.md |
For the full anti-pattern catalog, read references/anti-patterns/01-overview.md.
Effect.Service over Context.Tag for business services. Use Context.Tag for libraries with multiple implementations and for infrastructure with runtime injection (worker bindings, KV).Schema.TaggedError over Data.TaggedError. The Schema form is serializable across RPC / HTTP and integrates with HttpApiSchema.annotations({ status: 404 }).import { Schema } from "effect". The @effect/schema package is deprecated since 3.10. The migration is import-only.Effect.fn("Service.method") for named functions to gain automatic span tracing and stack traces.Effect.gen for sequential / branching logic; default to pipe for linear transformations.{ concurrency: N } on every Effect.all / Effect.forEach / Stream.mapEffect over a list of more than five items.Layer.provideMerge over Layer.provide for incremental composition (consumers can also use the merged service). Use Layer.mergeAll for flat composition of independent layers.NodeRuntime.runMain for entry points (handles SIGINT / SIGTERM gracefully). Use ManagedRuntime for non-Effect framework integration (Hono, Express, Next.js route handlers).acquireRelease for resource lifecycles, never try / finally (which bypasses interruption).return yield* when raising tagged errors inside Effect.gen so TypeScript narrows the control flow.| Symptom | Cause / fix |
|---|---|
Missing 'X' in the expected Effect context / Effect<A, E, X> not assignable to Effect<A, E, never> | confused Layer.provide for Layer.provideMerge — see references/services-layers/12-layer-composition-gotchas.md, references/anti-patterns/13-layer-provide-confusion.md |
Effect.cachedWithTTL is not a function / unexpected double-yield | API returns Effect<Effect<A,E,R>>; you yield twice — see references/caching/04-effect-cached.md |
SubscriptionRef.unsafeMake is not a function | never call unsafeMake; use SubscriptionRef.make(initial) — see references/state/04-subscription-ref.md |
| AI hallucinated an API that doesn't exist | cross-check references/anti-patterns/18-ai-hallucinations.md and references/anti-patterns/19-v4-syntax-do-not-use.md |
Effect resolved with null unexpectedly | Effect.promise swallowed the error as a defect — switch to Effect.tryPromise({ try, catch }), see references/anti-patterns/16-effect-promise-confusion.md |
| Tests pass with mocks but fail in prod | mocks were vi.mock. Replace with Layer.succeed(Service, mockImpl) — see references/testing/08-test-layers.md |
| Hanging Stream / never-ending program | infinite stream without take(N) / runHead — see references/streams/18-infinite-streams.md |
OOM on large Effect.all | unbounded parallelism — add { concurrency: 10 }, see references/concurrency/07-bounded-parallelism.md |
| Finalizers not running on Ctrl-C | using try / finally instead of acquireRelease, or Effect.runPromise instead of NodeRuntime.runMain — see references/resource-management/03-acquire-release.md, references/platform/12-node-runtime.md |
| Stale logs / no traces in OTel | forgot NodeSdk.layer and OtlpTracer.layer — see references/observability/11-opentelemetry-setup.md |
| Header keys returned 404 | header keys must be lowercase in HttpApiEndpoint.setHeaders — see references/http-server/05-headers.md |
Cannot find module '@effect/schema' | deprecated package; switch to import { Schema } from "effect" — see references/schema/20-deprecated-effect-schema.md |
Load only the reference files needed for the current task.
Read references/core/01-effect-type.md, references/core/02-creating-effects.md, references/core/03-running-effects.md, references/core/04-pipelines.md, references/core/05-generators.md, references/core/06-gen-vs-pipe.md. For named service methods read references/core/07-effect-fn.md. For combinators read references/core/08-effect-all.md, references/core/09-effect-foreach.md, references/core/10-zip-and-tap.md, references/core/11-short-circuiting.md, references/core/12-effect-match.md.
Read references/error-handling/01-overview.md, references/error-handling/02-data-tagged-error.md, references/error-handling/03-schema-tagged-error.md, references/error-handling/04-catch-tag.md, references/error-handling/05-catch-tags.md, references/error-handling/06-catch-all.md, references/error-handling/07-cause-and-exit.md, references/error-handling/08-defects.md, references/error-handling/09-recovery-patterns.md, references/error-handling/10-error-accumulation.md, references/error-handling/11-yield-fail-pattern.md, references/error-handling/12-error-taxonomy.md, references/error-handling/13-error-remapping.md, references/error-handling/14-sandboxing.md.
Read references/services-layers/01-overview.md, references/services-layers/02-context-tag.md, references/services-layers/03-effect-service.md, references/services-layers/04-context-vs-effect-service.md, references/services-layers/05-context-reference.md, references/services-layers/06-layer-succeed.md, references/services-layers/07-layer-effect.md, references/services-layers/08-layer-scoped.md, references/services-layers/09-layer-merge.md, references/services-layers/10-layer-provide.md, references/services-layers/11-layer-providemerge.md, and the critical references/services-layers/12-layer-composition-gotchas.md. Runtime: references/services-layers/13-layer-memoization.md, references/services-layers/14-managed-runtime.md, references/services-layers/15-effect-provide.md, references/services-layers/16-layer-tap-debug.md, references/services-layers/17-fresh-vs-memoize.md.
effect)Read references/schema/01-overview.md, references/schema/02-schema-struct.md, references/schema/03-schema-class.md, references/schema/04-schema-tagged-class.md, references/schema/05-schema-tagged-error.md, references/schema/06-branded-types.md, references/schema/07-primitives.md, references/schema/08-collections.md, references/schema/09-unions-and-literals.md, references/schema/10-decoding.md, references/schema/11-encoding.md, references/schema/12-transforms.md, references/schema/13-filters.md, references/schema/14-annotations.md, references/schema/15-json-schema.md, references/schema/16-arbitrary.md, references/schema/17-equivalence-and-order.md, references/schema/18-recursive-schemas.md, references/schema/19-error-formatter.md, and the migration banner references/schema/20-deprecated-effect-schema.md.
Read references/data-types/01-overview.md, references/data-types/02-option.md, references/data-types/03-option-patterns.md, references/data-types/04-either.md, references/data-types/05-data-struct.md, references/data-types/06-data-tuple-array.md, references/data-types/07-data-case.md, references/data-types/08-equal-and-hash.md, references/data-types/09-chunk.md, references/data-types/10-hashset-hashmap.md, references/data-types/11-readonly-array.md, references/data-types/12-duration.md, references/data-types/13-datetime.md, references/data-types/14-bigdecimal.md, references/data-types/15-redacted.md, references/data-types/16-brand.md, references/data-types/17-order-and-equivalence.md, references/data-types/18-function-utilities.md.
Read references/pattern-matching/01-overview.md, references/pattern-matching/02-match-value.md, references/pattern-matching/03-match-type.md, references/pattern-matching/04-match-tag.md, references/pattern-matching/05-match-when.md, references/pattern-matching/06-not-or-either.md, references/pattern-matching/07-exhaustive-vs-orelse.md.
Read references/concurrency/01-overview.md, references/concurrency/02-fork-types.md, references/concurrency/03-fiber-operations.md, references/concurrency/04-effect-race.md, references/concurrency/05-effect-all-concurrency.md, references/concurrency/06-effect-foreach-concurrency.md, and the rule references/concurrency/07-bounded-parallelism.md. Coordination: references/concurrency/08-semaphore.md, references/concurrency/09-deferred.md, references/concurrency/10-latch.md, references/concurrency/11-interruption.md, references/concurrency/12-stm.md, references/concurrency/13-effect-timeout.md, references/concurrency/14-effect-disconnect.md.
Read references/state/01-overview.md, references/state/02-ref.md, references/state/03-synchronizedref.md, references/state/04-subscription-ref.md, references/state/05-fiber-ref.md, references/state/06-state-patterns.md.
Read references/resource-management/01-overview.md, references/resource-management/02-scope.md, references/resource-management/03-acquire-release.md, references/resource-management/04-acquire-use-release.md, references/resource-management/05-effect-scoped.md, references/resource-management/06-add-finalizer.md, references/resource-management/07-effect-ensuring.md, references/resource-management/08-cleanup-order.md.
Read references/streams/01-overview.md, references/streams/02-creating-streams.md, references/streams/03-stream-from-queue-pubsub.md, references/streams/04-stream-from-schedule.md, references/streams/05-stream-pagination.md, references/streams/06-transformations.md, references/streams/07-flattening.md, references/streams/08-merging-zipping.md, references/streams/09-mapEffect-concurrency.md, references/streams/10-stream-consumption.md, references/streams/11-sink.md, references/streams/12-channel.md, references/streams/13-error-handling.md, references/streams/14-backpressure.md, references/streams/15-batching.md, references/streams/16-broadcast-and-partition.md, references/streams/17-scope-and-stream.md, references/streams/18-infinite-streams.md.
Read references/queue-pubsub/01-overview.md, references/queue-pubsub/02-bounded-queue.md, references/queue-pubsub/03-dropping-sliding-queue.md, references/queue-pubsub/04-queue-operations.md, references/queue-pubsub/05-pubsub.md, references/queue-pubsub/06-producer-consumer.md, references/queue-pubsub/07-graceful-shutdown.md.
Read references/caching/01-overview.md, references/caching/02-cache-make.md, references/caching/03-cache-operations.md, references/caching/04-effect-cached.md, references/caching/05-scoped-cache.md, references/caching/06-keyed-pool.md, references/caching/07-request-resolver.md.
Read references/scheduling/01-overview.md, references/scheduling/02-built-in-schedules.md, references/scheduling/03-cron-schedule.md, references/scheduling/04-schedule-composition.md, references/scheduling/05-jitter-and-modify.md, references/scheduling/06-effect-retry.md, references/scheduling/07-effect-repeat.md, references/scheduling/08-schedule-conditions.md, references/scheduling/09-effect-delay.md.
ConfigRead references/config/01-overview.md, references/config/02-basic-config.md, references/config/03-config-redacted.md, references/config/04-config-collections.md, references/config/05-config-all-nested.md, references/config/06-config-validation.md, references/config/07-config-withDefault.md, references/config/08-config-providers.md, references/config/09-layer-set-config-provider.md.
Read references/observability/01-overview.md, references/observability/02-logging-basics.md, references/observability/03-structured-logs.md, references/observability/04-log-levels.md, references/observability/05-custom-logger.md, references/observability/06-tracing-basics.md, references/observability/07-span-scoped.md, references/observability/08-metrics-counter-gauge.md, references/observability/09-metrics-histogram-summary.md, references/observability/10-metric-tagged.md, references/observability/11-opentelemetry-setup.md, references/observability/12-otlp-exporters.md, references/observability/13-supervisor.md.
Read references/platform/01-overview.md, references/platform/02-filesystem.md, references/platform/03-path.md, references/platform/04-url.md, references/platform/05-command.md, references/platform/06-terminal.md, references/platform/07-keyvaluestore.md, references/platform/08-ndjson.md, references/platform/09-worker.md, references/platform/10-stream-sink-platform.md, references/platform/11-node-context.md, references/platform/12-node-runtime.md, references/platform/13-bun-platform.md.
Read references/http-server/01-overview.md, references/http-server/02-defining-endpoints.md, references/http-server/03-path-params.md, references/http-server/04-query-and-payload.md, references/http-server/05-headers.md, references/http-server/06-grouping.md, references/http-server/07-handlers.md, references/http-server/08-error-responses.md, references/http-server/09-middleware.md, references/http-server/10-cors-and-logger.md, references/http-server/11-swagger.md, references/http-server/12-multipart.md, references/http-server/13-streaming-responses.md, references/http-server/14-custom-encoding.md, references/http-server/15-serving.md, references/http-server/16-platform-router.md, references/http-server/17-shutdown-and-signals.md.
Read references/http-client/01-overview.md, references/http-client/02-fetch-http-client.md, references/http-client/03-request-building.md, references/http-client/04-response-decoding.md, references/http-client/05-derived-client.md, references/http-client/06-retries-and-timeouts.md, references/http-client/07-request-tracing.md, references/http-client/08-error-handling.md.
@effect/vitestRead references/testing/01-overview.md, references/testing/02-it-effect.md, references/testing/03-it-live.md, references/testing/04-it-scoped.md, references/testing/05-it-layer.md, references/testing/06-test-clock.md, references/testing/07-test-random.md, references/testing/08-test-layers.md, references/testing/09-stateful-test-layers.md, references/testing/10-spy-layers.md, references/testing/11-testing-errors.md, references/testing/12-testing-resources.md, references/testing/13-testing-concurrency.md, references/testing/14-property-testing.md.
@effect/sqlRead references/sql/01-overview.md, references/sql/02-sql-client.md, references/sql/03-tagged-templates.md, references/sql/04-transactions.md, references/sql/05-sql-streams.md, references/sql/06-sql-resolver.md, references/sql/07-sql-schema.md, references/sql/08-sql-migrations.md, references/sql/09-driver-postgres.md, references/sql/10-driver-mysql.md, references/sql/11-driver-sqlite.md, references/sql/12-driver-other.md, references/sql/13-orm-adapters.md.
Read references/rpc/01-overview.md, references/rpc/02-rpc-group.md, references/rpc/03-rpc-server.md, references/rpc/04-rpc-client.md, references/rpc/05-rpc-middleware.md, references/rpc/06-rpc-streaming.md, references/rpc/07-rpc-cluster-intro.md.
@effect/cliRead references/cli/01-overview.md, references/cli/02-command.md, references/cli/03-options.md, references/cli/04-options-combinators.md, references/cli/05-args.md, references/cli/06-args-combinators.md, references/cli/07-prompts.md, references/cli/08-subcommands.md, references/cli/09-providing-services.md, references/cli/10-config-files.md, references/cli/11-fallbacks.md, references/cli/12-completions.md.
Read references/frontend-atom/01-overview.md, references/frontend-atom/02-atom-make.md, references/frontend-atom/03-atom-families.md, references/frontend-atom/04-keep-alive.md, references/frontend-atom/05-react-hooks.md, references/frontend-atom/06-result-builder.md, references/frontend-atom/07-side-effect-atoms.md, references/frontend-atom/08-mutations.md, references/frontend-atom/09-cache-invalidation.md, references/frontend-atom/10-atoms-with-localstorage.md, references/frontend-atom/11-effect-runtime-bridge.md, references/frontend-atom/12-vercel-ai-sdk.md.
Read references/migration/01-overview.md, references/migration/02-from-promise.md, references/migration/03-from-trycatch.md, references/migration/04-from-fp-ts.md, references/migration/05-from-neverthrow.md, references/migration/06-from-rxjs.md, references/migration/07-gradual-adoption.md, references/migration/08-portable-utility.md.
Read references/architecture/01-overview.md, references/architecture/02-domain-driven-design.md, references/architecture/03-hexagonal-architecture.md, references/architecture/04-repository-pattern.md, references/architecture/05-use-case-pattern.md, references/architecture/06-error-boundary-design.md, references/architecture/07-shared-kernel.md, references/architecture/08-effect-language-server.md.
Read references/workflows/01-greenfield-cli.md, references/workflows/02-greenfield-http-api.md, references/workflows/03-greenfield-react-spa.md, references/workflows/04-greenfield-nextjs.md, references/workflows/05-adding-effect-existing.md, references/workflows/06-microservice.md, references/workflows/07-background-worker.md, references/workflows/08-mcp-server.md, references/workflows/09-ai-agent.md.