Effect Program Design

Effect Program Design

Build production Effect v4 programs with small domain-shaped interfaces, typed success and error channels, declared dependencies, observable operation boundaries, and tests that substitute layers at real seams. This skill combines broad Effect mechanics with deep-module, capture-before-narrow, and real-seam design standards.

Source rule

Check these before guessing:

1. the nearest CLAUDE.md / AGENTS.md and project-local conventions;
2. the installed effect, @effect/*, and related package versions and declarations;
3. the Effect v4 docs at https://effect.website/docs/v4;
4. the installed package source and declarations, plus an upstream source checkout when available, when docs do not settle an API.

effect/unstable/* can change between beta/minor versions. Typecheck examples against the installed version. Local project conventions take precedence unless the task explicitly changes them.

References

Read only the references relevant to the task; read all matching branches when work crosses concerns.

• Public module depth and domain-shaped APIs: references/DEEP_MODULES.md. Read this when modifying or creating services or layers.
• Service tags, live layers, file placement, Effect.fn, or runtime composition: references/SERVICES_LAYERS.md.
• Tagged errors, capture-before-narrow, spans, logs, or error reporting: references/ERRORS_OBSERVABILITY.md.
• Records, schemas, variants, optionality, brands, decoding, or construction: references/SCHEMA_DATA_MODELING.md.
• Config, env vars, providers, or secrets: references/CONFIG_SECRETS.md.
• HTTP, SDK, database boundaries, persistence records, or transactions: references/BOUNDARIES_PERSISTENCE.md.
• Scopes, acquisition, concurrency, best-effort work, or workflow transitions: references/RESOURCES_CONCURRENCY.md.
• Retry, repeat, polling, pacing, backoff, or workers: references/SCHEDULING_WORKERS.md.
• Streams, queues, pubsub, pagination, backpressure, or long-lived consumers: references/STREAMS.md.
• Memoization, TTL caches, request dedupe, or batching: references/CACHING_BATCHING.md.
• Outgoing HTTP, provider adapters, status/decode handling, or HTTP retry: references/HTTP_CLIENTS.md.
• Effect tests, test services, clocks, synchronization, fakes, or real seams: references/TESTING.md.
• Platform-neutral services and the native-API boundary: references/PLATFORM.md.
• Node runtime, filesystem, path, crypto, child processes, sockets/WebSocket, Redis, or workers: references/PLATFORM_NODE.md.
• Effect Atom or React reactive Effect state: references/EFFECT_ATOM.md.
• TypeScript safety, Predicate refinements, Match dispatch, naming, collections, imports, and escape hatches: references/TYPESCRIPT_CONTRACTS.md.

The creed

1. Deep modules. The interface is the cost and the hidden implementation is the benefit. Public operations use domain inputs and outputs; callers do not supply credentials, clients, rows, or other internals.

2. Everything stays in Effect. Keep expected failures in E, dependencies in R, and resources in scopes. Do not pass services, layers, effects, or errors as ordinary values when composition expresses the relationship.

3. Two-tier errors. Classify rich internal failures, capture them, then narrow to a small caller-actionable union. Prefer typed catchTag/catchTags; never recover with instanceof, Match, or manual _tag comparisons. Respect the error channel! Errors stay in the error channel and are not passed as values

4. Observe operations. Every public operation has a stable Effect.fn("domain.operation"), an explicit Effect.withSpan, or both. Capture raw actionable or unexpected failures before narrowing or swallowing them. Use Effect's logging APIs rather than passing loggers through domain interfaces. Report failures through the repository's configured observability capability, when one exists, before remapping or transforming them.

   someEffect.pipe(
     Effect.tapError(Effect.logError),
     Effect.tapError((error) => errorReporter.capture(error)),
   );
   

5. Test at real seams. Use the repository's Effect-compatible test integration, layers, deterministic test services, and real infrastructure where behavior depends on it. Assert both the result/error and externally visible end state. If you are writing tests you MUST read references/TESTING.md

6. Use Effect platform services. Application code depends on Effect's FileSystem, Path, Crypto, HTTP, process, socket, worker, and related abstractions. Native Node/Bun/browser APIs belong only in runtime adapters when no Effect service exists or when constructing the platform layer.

7. Use clear domain names. Follow the host repository's naming conventions. Prefer names that communicate the domain operation over ambiguous generic names, such as publishPatchDiffToStream instead of publish when the distinction matters.

Core defaults

• Compose workflows with Effect.gen and named Effect.fn operations.
• Prefer Context.Service for application capabilities and Layer.effect/Layer.scoped for live acquisition.
• Small services may collocate shape, tag, errors, operations, and layer in one file. Split larger services and external adapters by transport, persistence, orchestration, and other meaningful concerns.
• Keep substantial operation effects independently testable. They may remain beside a small service or move to a concern file; avoid burying business workflows in a large layer-construction closure.
• Dependencies normally remain ambient in R. Capturing a yielded dependency is reasonable for genuinely layer-local acquired state or configured clients.
• Model ordinary records with Schema.Struct plus a same-name inferred interface. Use Data.TaggedEnum for trusted internal control flow and Schema tagged variants/unions for encoded boundaries.
• Prefer Schema.TaggedError for network, RPC, queue, workflow, or other boundary-facing errors. Data.TaggedError is fine for internal-only failures that do not need a codec.
• Branding remains optional/aspirational. Named input objects are mandatory even when IDs remain raw strings.
• Decode unknown input at the adapter edge with Schema; do not cast JSON or leak SDK/row types through a service.
• Prefer Predicate refinements over ad hoc typeof, instanceof, nullish, and property-presence checks. Predicate is for trusted values or intentional shallow refinement, not a replacement for Schema decoding at an unknown boundary.
• Prefer exhaustive Match dispatch for trusted discriminated unions and multi-branch value handling. Never compare _tag manually: use catchTag/catchTags for Effect errors and Match for non-error values.
• Read runtime config through Config; keep secrets Redacted until the adapter call.
• Use Schedule for retry/repeat/polling and Stream for many-valued, backpressured sources.
• Use bounded concurrency, bounded/idempotent retries, scoped background fibers, and explicit finalizers.
• Keep external network calls outside authoritative database transactions.
• Keep TypeScript contracts precise: no any, non-null assertions, as-casts, excepting as const, vague helper files, or truthiness shortcuts that erase meaningful domain distinctions.
• PARSE, DON'T VALIDATE. Parse at trust boundaries (non-effect-to-effect code bridges, databases, networks) to ensure type safety without bad validation code.

Testing defaults

• When using @effect/vitest, prefer it.effect; use it.live only when live runtime behavior is itself under test.
• Use TestClock, Deferred, Queue, Latch, and Ref instead of sleeps and timing races.
• Test services, recording fakes, and Layer.mock are allowed in test files or dedicated test utilities only—never production source.
• Use an isolated real database when behavior depends on database semantics, constraints, transactions, conflicts, or state transitions.
• Use fake Effect services or clients for true external systems and make unexpected methods fail loudly.
• Prefer dependency substitution through layers over module patching or method spies.

Review checklist

• The public surface is small, domain-shaped, and hides implementation knowledge.
• Each method exposes a narrow caller-actionable error union.
• Rich failures are captured before narrowing or best-effort swallowing.
• Every public operation has a safe, stable trace boundary.
• Dependencies are declared in R; resources and background work have clear scoped owners.
• Unknown boundaries are decoded; secrets stay Redacted; raw rows/SDK values do not cross public seams.
• Runtime refinements use Predicate; trusted union dispatch uses exhaustive Match; no code manually compares _tag.
• Native platform APIs are isolated behind Effect services and runtime layers.
• Each service's implementing Layer is provided once during application runtime construction unless its required configuration or resources do not exist until a later operation scope.
• Retries are bounded and idempotent; concurrency and buffering are bounded.
• Tests use real seams, deterministic synchronization, and assert external end state.