effect-ts-practices

name	effect-ts-practices
description	Applies Effect-first TypeScript architecture for errors, asynchronous workflows, runtime schemas, services, Layers, logging, tests, and Effect Atom. Use when writing or reviewing code in any project that uses Effect, Effect-TS, @effect packages, Effect Schema, or Effect Atom, unless a repository-specific Effect skill provides stricter guidance.

Effect-TS Practices

Read the repository's Effect guidance and inspect the installed effect and companion-package versions before choosing an API. Project-specific instructions override this portable skill. Do not copy examples across Effect major versions or prerelease lines without checking the matching API and local patterns.

Workflows and errors

• Express application and service workflows as Effect values. Adapt Promise APIs once with Effect.tryPromise; keep raw async/await only at framework entrypoints that must return a Promise and run an already-built Effect there.
• Do not use JavaScript try/catch or throw inside an Effect workflow. Wrap throwing boundaries with Effect.try or Effect.tryPromise.
• Model expected failures with specific Schema.TaggedErrorClass types. Preserve meaningful error distinctions and recover with catchTag or catchTags; do not erase a useful error union with a generic catch.
• Do not run Effects inside services with nested runSync or runPromise. Keep composition in Effect and run once at the owning boundary.

Schema and types

• Use Effect Schema for new runtime validation, transported data, persistence contracts, and domain models. Do not add Zod in an Effect project.
• When changing an existing Zod boundary, migrate it only when the migration stays focused and preserves the contract.