Effect Best Practices

Goal

Keep the harness on one Effect style so builder and reviewer do not improvise different patterns for contracts, runtime services, and failures.

Apply when

• The task edits files that import from effect.
• The task introduces or changes Schema boundary contracts.
• The task adds runtime services, typed errors, config loading, or logging.

Rules

• Use Schema for external contracts, agent handoffs, and runtime boundary data.
• Use branded identifiers when IDs cross meaningful service or contract boundaries.
• Use Schema.TaggedError for domain and transport errors that need stable structure.
• Prefer specific domain errors over generic HTTP or catch-all errors.
• Handle typed failures with catchTag or catchTags, not broad catchAll rewrites that erase intent.
• Use Effect.Service for business services and declare dependencies in the service definition.