/effect-program-design

name: effect-program-design
description: >-
    Design, write, review, and test production Effect v4 programs: deep services and layers, schemas,
    tagged errors, observability, Config, persistence, resources, concurrency, schedules, workers,
    streams, caches, HTTP clients, Effect platform services (Node filesystem/path/crypto/process/socket),
    and Effect Atom integrations. Use for any Effect application or adapter work.

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 HumanLayer's 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-ts-effect-smol.mintlify.app/>; 4. the pinned/upstream source (`~/projects/effect-smol`) when docs do not settle an API.

unstable-tagged modules (`effect/http`, `effect/rpc`, `effect/process`, ...) 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 any time you are modifying or creating services or layers - this is the core of our effect philosophy!**
• Service tags, live layers, file placement, `Effect.fn`, or runtime composition:

`references/SERVICES_LAYERS.md`.

• Tagged errors, capture-before-narrow, spans, logs, or Sentry: `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/DB boundaries, Drizzle rows, JSONB, 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`.

• Local exemplars and foils: `references/REPOSITORY_EXAMPLES.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/unexpected failures before narrowing or swallowing them.\ Use Effect's logger to log info, errors, etc - `yield* Effect.logError` - do NOT pass in external loggers. Errors MUST also be captured to sentry as soon as they surface before they are re-mapped or transformed.

    someEffect.pipe(
	Effect.tapError(Effect.logError),
	Effect.tapError((e) => Effect.sync(() => Sentry.captureException(e))),
    )

5. **Test at real seams.** Use `@effect/vitest`, 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 Martin Fowler / Uncle Bob Martin naming conventions. Prefer longer, readable, explanatory names that indicate WHAT the thing is and WHAT the thing does - how it fits into the system. err on the side of overly explanatory. bad: `publish`; good: `publishPatchDiffToStream`

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 mean