effect-first-development
/effect-first-development
Canonical Effect-first development guide for this repo. Trigger on: new features, refactors, bug fixes, API boundaries, typed errors, Option usage, schema decoding, service wiring, and test authoring.
- Author
- kriegcloud ↗
- Repository
- beep-effect ↗
- Licence
- Apache-2.0
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 4
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
What it does and when to use it
Canonical Effect-first development guide for this repo. Trigger on: new features, refactors, bug fixes, API boundaries, typed errors, Option usage, schema decoding, service wiring, and test authoring.
Original author description
Canonical Effect-first development guide for this repo. Trigger on: new features, refactors, bug fixes, API boundaries, typed errors, Option usage, schema decoding, service wiring, and test authoring.
How it works
- Zero-Fail Memory Rule
- Non-Negotiable Laws
- Always / Never Examples (load on demand)
- Source of Truth References
- Verify
SKILL.md preview
---
name: effect-first-development
description: >
Canonical Effect-first development guide for this repo. Trigger on: new features,
refactors, bug fixes, API boundaries, typed errors, Option usage, schema decoding,
service wiring, and test authoring.
metadata:
version: "0.1.0"
status: active
---
# Effect-First Development (Canonical)
Use this skill when implementing or reviewing production code in this repository.
If there is any conflict, repository laws win.
## Zero-Fail Memory Rule
Before writing code, walk the Non-Negotiable Laws below as a question checklist.
The fast triage questions:
1. Can it fail? Typed tagged error in `Effect`. Can it be missing? `Option`.
2. Is input external? Decode with `Schema` at the boundary; schema is the source of truth for data shapes.
3. Touching arrays/objects/strings/booleans or branching on shape? Effect modules (`A`/`R`/`Str`/`Bool`), `Predicate`, `Match`, `A.match` — never native helpers or `switch`. Prefer the flattest equivalent form first. Before I keep an `O.match(...)`, can `O.map`/`O.flatMap`/`O.liftPredicate`/`O.getOrElse` express it more flatly?
4. Defining services, schemas, unions, or Effect-returning functions? Identity composer + `Context.Service`/`Layer`, branded `S.Opaque` for data, `LiteralKit`/`S.toTaggedUnion`, named `Effect.fn`.
5. At a runtime boundary? `Effect.run*` only at entrypoints/tests, `runMain` owns process exit, `Effect.tryPromise` for promises, `Effect.scoped`/`acquireUseRelease` for resources.
6. Resilience/observability? `Effect.retry` + `Schedule`, `timeoutOption`/`timeoutOrElse`, explicit concurrency, spans + structured logs from the start, `Config`/`Redacted` for env + secrets.
7. Recovery? Precise `catchTag`/`catchFilter` in domain, `catchCause`/`matchCauseEffect` at boundaries, `Cause.pretty` for rendering, `fail` for expected vs `die` for invariants.
Additional checks with no law counterpart below:
- Designing a service or test helper? Keep `FileSystem`, `Path`, and `SqlClient` inside the layer/service unless they are the explicit domain boundary.
- Testing platform/runtime semantics? Prefer `@effect/vitest` for supporting tests, but spawn the real runtime when the assertion is about platform lifecycle behavior.
- Testing assertions? Use public `@effect/vitest/utils` helpers for Option (`assertSome` / `assertNone`), Result (`assertSuccess` / `assertFailure`), and Exit (`assertExitSuccess` / `assertExitFailure`). Payload-checking helpers require the expected value; `assertExitFailure` requires an expected `Cause` (for example `Cause.fail(expectedError)`). Plain-value `expect` and `assert` remain legal inside `it.effect`; do not impose a blanket replacement. See [testing patterns](../../../.patterns/testing-patterns.md#specialized-option-result-and-exit-assertions) for complete examples and narrowing behavior.
## Non-Negotiable Laws
1. Canonical aliases are mandatory:
- `effect/Array` as `A`
- `effect/Option` as `O`
- `effect/Predicate` as `P`
- `effect/Record` as `R`
- `effect/Schema` as `S`
2. Import every Effect module from its dedicated path (`effect/Effect`, `effect/Match`, `effect/String` as `Str`, etc.). Import `pipe`, `flow`, and `identity` from `effect/Function`. The root `effect` barrel is not used, including in JSDoc and Markdown examples.
3. No `any`, type assertions, `@ts-ignore`, or non-null assertions.
4. No plain `throw`, `new Error`, or untyped error channels in production logic.
5. No nullish leak in domain logic; convert nullish to `Option` at boundaries.
6. No direct `typeof` checks when `effect/Predicate` covers the case.
7. No native `Object/Map/Set/Date/String` helpers in domain logic.
8. For typed errors, extend `S.TaggedError` from `effect/Schema` directly. Use a package `$I` composer for a distinct namespaced identifier; otherwise omit the identifier, and never pass a bare identifier equal to the tag. Cause-carrying errors declare `cause: S.Defect({ includeStack: true })` explicitly.
9. Exported APIs need JSDoc and docgen-clean examples.
10. Do not finish with failing `check`, `lint`, `test`, or `docgen`.
11. Do not suffix schema constants with `Schema`; use the domain name.
12. For non-class schemas, export runtime type aliases with the same name: `export type X = typeof X.Type`.
13. Do not use native `switch`; use `Match`. For empty/non-empty array branching, prefer `A.match` over manual length checks.
14. All new schemas must be meaningfully annotated: `.pipe($I.annoteSchema("Name", { description }))` for non-class schemas (`LiteralKit` included), `$I.annote("Name", { description })` as a class's trailing argument. Never `.annotate($I.annote(...))`.
15. Service identifiers must use package composer `.create(...)` and `$I\`MyService\``.
16. If a schema has properties that are a union of literal strings, it should be a tagged union composed via `LiteralKit`, `.mapMembers`, and `Tuple.evolve`, then finalized with `S.toTaggedUnion`. Use `S.TaggedUnion` only for canonical `_tag` object-union construction.
17. Reusable functions returning `Effect` should use named `Effect.fn("Namespace.name")` (or `Effect.fnUntraced` for hot/internal paths). Zero-arg effect values may stay `Effect.gen(...).pipe(Effect.withSpan("Name"))` when there is no exported/reused function to expose.
18. Effect workflows should be observable with spans and structured logs from the start; add metrics (`effect/Metric` + `Effect.track*`) where the path is important enough to measure.
19. Durations and time windows should use `effect/Duration`, not ad-hoc number literals.
20. For nullable/nullish/optional schema-to-`Option` conversions, use `S.OptionFromNullOr`, `S.OptionFromNullishOr`, or `S.OptionFromOptionalKey` (never `S.OptionFromOptional`; optional fields use exact keys, EF-40). For runtime `Option` object fields, prefer `O.getSomesStruct({...})` (`@beep/utils`) for heterogeneous struct spreads with known keys — it is runtime-identical to `R.getSomes` but preserves literal keys and per-key value types; reserve `R.getSomes({...})` for homogeneous dynamic-key dictionaries. Use `O.all({...})` when the whole object is all-or-nothing. (Amended 2026-07-05 — see `standards/architecture/DECISIONS.md`.)
21. Exported helper utilities should expose dual data-first/data-last forms via `dual` from `effect/Function`.
22. Never use `JSON.parse` / `JSON.stringify` in Effect-first code, tests, or fixtures; use `S.fromJsonString(S.Unknown)` / `S.fromJsonString` + `S.decodeUnknownEffect` / `S.encodeUnknownEffect` or explicit Result/Option codecs for non-throwing sync helpers.
23. Do not use `S.decodeSync`, `S.decodeUnknownSync`, `S.encodeSync`, or `S.encodeUnknownSync` by default. Prefer Effect codecs, and map schema errors with `Effect.mapError(...)` before returning them across module, service, CLI, HTTP, or test-helper boundaries. If a legacy sync API must remain throwing, use Result codecs plus `Result.getOrThrowWith(...)` to preserve an `Error` or typed boundary error.
24. Plain data schemas are `class X extends S.Opaque<X, { readonly brand: unique symbol }>()(S.Struct({...}).pipe($I.annoteSchema("X", {...}))) {}` (`S.TaggedStruct` for `_tag` data); construct with `X.make(...)`. Keep `S.Class` / `S.TaggedClass` / `S.Error` / `S.TaggedError` for errors, persisted entities, schemas with instance members, and `.extend` chains. Every schema class and Opaque carries `{ readonly brand: unique symbol }`; a `{}` brand needs a schema-first inventory exception. `S.Class` checks `instanceof`, so plain objects fail `S.is` and encoding against it.
25. Only runtime boundaries (app entrypoints/tests) may call `Effect.runSync` / `Effect.runPromise` / `Effect.runFork`; libraries return `Effect`.
26. Process entrypoints must not recover the root cause merely to set `process.exitCode` and print `Cause.pretty(...)`. Pass the failing root effect directly to `BunRuntime.runMain` / `NodeRuntime.runMain`; use `runMain(..., { teardown })` plus `Runtime.defaultTeardown` for custom terminal rendering.
27. Promise-returning APIs must be lifted with `Effect.tryPromise` at boundaries.
28. Resource lifetimes must be explicit with `Effect.acquireUseRelease` or `Effect.scoped`.
29. Retries must be expressed via `Effect.retry` and `Schedule`, not manual retry loops.
30. Timeout behavior should be modeled with `Effect.timeoutOption` / `Effect.timeoutOrElse` instead of ad-hoc timers.
31. Forking defaults to `Effect.forkChild`; `Effect.forkDetach` requires explicit daemon intent.
32. Parallel fan-out should set explicit concurrency for `Effect.forEach` / `Effect.all` / `Effect.validate` when load is non-trivial.
33. Config should be modeled via `Config` and `ConfigProvider`, not direct `process.env` access in domain services.
34. Secrets must be represented as `Redacted` values (`Config.Redacted` / `Redacted.make`) and never logged raw.
35. Error recovery should be precise (`catchTag` / `catchFilter`) instead of blanket recovery that hides unrelated failures; at outer HTTP/worker boundaries prefer `Effect.catchCause` / `Effect.matchCauseEffect`. At process entrypoints, prefer platform `runMain` teardown instead.
36. Use `Effect.fail` for expected business errors and reserve `Effect.die` / `Effect.orDie` for invariants and impossible states.
37. When layer memoization sharing is unsafe, force isolation with `Effect.provide(..., { local: true })` or `Layer.fresh`.
38. Schema-first development: if a data model can be represented as `Schema`, define the `Schema` first and derive runtime types from it; avoid plain `type` / `interface` for domain data shapes.
39. Service contracts may stay interfaces, but row shapes, wire payloads, and persisted models should not.
40. Prefer schema-level defaults (`S.withConstructorDefault`, `S.withDecodingDefaultKey`) instead of ad-hoc runtime fallback object literals.
41. Guard predicates for domain strings/paths/tags should come from branded schemas via `S.is(...)`, not ad-hoc `regex.test(...)` helpers.
42. For schema-modeled domain comparisons, prefer `S.toEquivalence(schema)` over manual `===` / `!==` checks.
43. For deterministic format conversions, prefer schema transformations (`S.decodeTo` + `SchemaTransformation.transform`) over ad-hoc string conversion helpers.
44. Never use native `Array.prototype.sort`; use `A.sort(values, order)` with explicit `Order` instances.
45. Avoid ad-hoc `String(...)` coercion in domain logic; model unknown-to-string normalization with schema transformations and compare via schema equivalence.
46. When branching on boolean values, prefer the flattest equivalent form first; use `Bool.match` when both branches do real work or when it is materially clearer than direct boolean selection.
47. Before keeping `O.match(...)`, check whether `O.map(...)`, `O.flatMap(...)`, `O.liftPredicate(...)`, and `O.getOrElse(...)` express the same control flow more flatly. Avoid `onNone: () => ({})` object compaction; use `O.map(...)` plus `O.getOrElse(() => ({}))`, `O.getSomesStruct({...})` for heterogeneous struct spreads (`R.getSomes({...})` only for homogeneous dynamic-key dictionaries), or `S.OptionFrom*` according to boundary semantics. (Amended 2026-07-05 — see `standards/architecture/DECISIONS.md`.)
48. In callback-only contexts where `yield*` is unavailable (for example `SchemaTransformation.transform*`), consume services with `Context.Service.use(...)`.
49. Do not import `node:path` in production/tooling source. Use `Path.Path` service (`yield* Path.Path`) for `join`, `resolve`, `relative`, `basename`, etc.
50. Do not use native `fetch` in production/tooling source. Use `HttpClient` from `effect/http` and provide platform client layers (Bun: `BunHttpClient.layer`).
51. Named or reused domain constraints must be modeled as schemas first; prefer built-in schema constructors/checks before `S.makeFilter`, then derive guards with `S.is(...)`.
52. Reusable `S.makeFilter`, `S.makeFilterGroup`, and reusable built-in check blocks must include `identifier`, `title`, and `description`; `message` stays user-facing.
53. Use `LiteralKit` for named internal literal domains, especially when `.Enum`, `.is`, `$match`, `.toTaggedUnion`, or annotation-bearing schema values are part of the design; use `S.Literals` for anonymous inline unions never referenced by name.
54. Prefer `P.isTagged("Tag")` over manual `_tag` guard helpers built from `P.hasProperty`, `P.isObject`, or inline `_tag` string checks.
55. When a matcher is the function body or a reusable helper, prefer `Match.type<T>().pipe(...)` / `Match.tags(...)` over `Match.value(...)`.
56. At logging/recovery boundaries, render causes with `Cause.pretty(...)` or `Cause.prettyErrors(...)` instead of ad-hoc `String(error)` fallback chains.
57. Prefer the tersest equivalent helper form when behavior is unchanged: direct helper refs over trivial wrapper lambdas, `flow(...)` for passthrough `pipe(...)` callbacks, and shared thunk helpers when already in scope.
58. Where upstream covers a `foundation/modeling` concept's intent, its covered facets retire in the same PR that migrates their consumers, with no alias; the whole concept retires unless the lines reading its uncovered members outnumber the lines using its covered facets (ADAPT, per the facet census). Do not add a concept upstream already covers (`standards/architecture/DECISIONS.md` "Upstream-First Foundation/Modeling"; effect-laws-v1 law 24).
## Always / Never Examples (load on demand)
- [references/always-never-core.md](references/always-never-core.md) — core modeling:
1 absence handling · 2 typed error boundary · 3 schema naming + annotation ·
4 type checks · 4b schema-backed guards + internal modeling · 5 Match over switch ·
6 tagged unions + exhaustive branching · 7 service identity via package composer ·
8 discriminated union schemas · 9 Effect-returning functions
- [references/observability-runtime.md](references/observability-runtime.md) — observability + runtime boundaries:
10 observability + metrics · 10b boundary logging with Cause · 10c process entrypoint teardown ·
11 Duration values · 12 nullish schemas to Option · 13 dual helper APIs ·
14 JSON via Schema codecs · 15 runtime boundary for running effects ·
16 `Effect.tryPromise` boundaries · 17 scoped resource safety
- [references/resilience-recovery.md](references/resilience-recovery.md) — resilience + recovery:
18 retry + timeout modeling · 19 structured concurrency + bounded parallelism ·
20 config + secret redaction · 21 precise recovery by tag ·
22 expected failures vs defects · 23 layer isolation
## Source of Truth References
`.repos/effect` points to the Effect child at
`$HOME/YeeBois/references/effect/effect` (Effect `main` is v4). The workspace also
contains `effect-tsgo`; `bun run beep refs provision` provisions it from
`scripts/references.json`, with `BEEP_REFERENCES_ROOT` overriding the
`$HOME/YeeBois/references/effect` root.
- [Effect LLMS guide](../../../.repos/effect/LLMS.md)
- [Effect ai-docs index](../../../.repos/effect/ai-docs/src/index.md)
- [Effect migration notes](../../../.repos/effect/MIGRATION.md)
- [Effect Schema docs](../../../.repos/effect/packages/effect/SCHEMA.md)
- [Effect core API source](../../../.repos/effect/packages/effect/src/Effect.ts)
- [Effect Config source](../../../.repos/effect/packages/effect/src/Config.ts)
- [Effect Fiber source](../../../.repos/effect/packages/effect/src/Fiber.ts)
## Verify
1. `rg -n " as |@ts-ignore|!\\.|\\bany\\b" apps packages tooling`
2. `rg -n "new Error\\(|throw " apps packages tooling`
3. `rg -n "typeof " apps packages tooling`
4. `rg -n "\\bswitch\\s*\\(" apps packages tooling`
5. `rg -n "export const [A-Za-z0-9_]+Schema\\b" apps packages tooling`
6. `rg -n ":\\s*Effect\\.Effect<|=>\\s*Effect\\.Effect<|=>\\s*Effect\\.[A-Za-z]+" apps packages tooling`
7. `rg -n "Date\\.now\\(|Math\\.random\\(|setTimeout\\(|setInterval\\(" apps packages tooling`
8. `rg -n "\\.split\\(|\\.trim\\(|\\.toLowerCase\\(|\\.toUpperCase\\(|\\.replace\\(" apps packages tooling`
9. `rg -n "S\\.Struct\\(" apps packages tooling`
10. `rg -n "^export interface [A-Za-z0-9_]+" apps packages tooling`
11. `rg -n "^export type [A-Za-z0-9_]+\\s*=\\s*\\{" apps packages tooling`
12. `rg -n "JSON\\.parse\\(|JSON\\.stringify\\(" apps packages tooling`
13. `rg -n "Effect\\.run(Sync|Promise|Fork)\\(" apps packages tooling infra`
14. `rg -n "process\\.env" apps packages tooling infra`
15. `rg -n "forkDetach\\(" apps packages tooling`
16. `rg -n "catchAll\\(|Effect\\.catch\\(" apps packages tooling`
17. `rg -n "Redacted\\.value\\(" apps packages tooling`
18. `rg -n "Effect\\.die\\(|Effect\\.orDie\\(" apps packages tooling`
19. `rg -n "Effect\\.provide\\(.*local:\\s*true|Layer\\.fresh\\(" apps packages tooling`
20. `rg -n "const hasTag|P\\.hasProperty\\(.*_tag|P\\.isObject\\(.*_tag|Match\\.value\\(" apps packages tooling`
21. `rg -n "Effect\\.fn\\(function\\*|=\\s*Effect\\.gen\\(function\\*" apps packages tooling`
22. `rg -n "Cause\\.pretty\\(|Cause\\.prettyErrors\\(|Effect\\.catchCause\\(|Effect\\.matchCauseEffect\\(" apps packages tooling`
23. `bun run check`
24. `bun run lint`
25. `bun run test`
26. `bun run docgen`
Files in this package (4)
- SKILL.md 17 KB
- references/always-never-core.md 11 KB
- references/observability-runtime.md 9 KB
- references/resilience-recovery.md 4 KB
Versions
The database has no other skills named effect-first-development.
Database snapshot: 13.11.2026 · package version 4aad40189f89 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100effect-ts
Effect-TS (Effect) guidance for TypeScript. Use when building, refactoring, reviewing, or explaining Effect code, especially for: typed error modeling (expected errors vs defects), Context/Layer/Effect.Service dependency wiring, Scope/resource lifecycles, runtime execution… - 91effect-development
Effect development guidance. Use when implementing or reviewing code that composes Effect APIs or patterns, or that adds or changes API signatures. - 100schema-first-development
Focused schema-first guidance for this repo's effect/Schema and @beep/schema patterns. Use when adding or refactoring schemas, replacing exported interface/type data models, fixing schema-first lint violations, modeling literal domains or tagged unions, applying schema defaults… - 95effect-error-handling
Use when Effect error handling patterns including catchAll, catchTag, either, option, and typed errors. Use for handling expected errors in Effect applications. - 100effect-ts
Effect-TS guide for TypeScript, v4 default with v3 support. Use when writing, debugging, or reviewing Effect code across errors, concurrency, services, streams, and schema, or when code imports from 'effect' or any '@effect/*' package. - 100effect-v3-to-v4
Use this skill when migrating a codebase from Effect v3 to Effect v4, upgrading `effect` or any `@effect/*` package across the v3/v4 boundary.