| name | effect-best-practices |
| version | 0.1.0 |
| description | Local Effect doctrine for the pi healthcare harness. Use when a task touches
files importing effect and needs consistent rules for services, schemas,
errors, layers, config, and structured effectful composition.
|
| allowed-tools | ["Read"] |
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.
- Compose runtime dependencies with layers at the app boundary, not with ad hoc
provide chains at random call sites.
- Use
Effect.fn for named effectful operations that deserve stable tracing and
reviewable boundaries.
- Use
Effect.log with structured fields instead of console.log.
- Use
Config with validation instead of reading process.env directly in
domain or service logic.
- Prefer explicit optional handling over nullable domain state when the contract
needs to preserve meaning.
- Do not call
runSync or runPromise inside domain services.
Review categories
- contracts and schemas
- errors
- service and layer boundaries
- effectful composition
- config and logging
- optional and nullable data
- dependency admission drift
Out of scope
- React atom patterns
- UI state conventions
- non-Effect framework doctrine outside this harness
