Home › Effect (TypeScript) › Effect TypeScript AGENTS.md

Effect TypeScript AGENTS.md

AGENTS.md for TypeScript codebases built on Effect: typed errors, services and Layers, Schema validation, resource safety, and @effect/vitest tests.

AGENTS.mdEffect (TypeScript)

Copy AGENTS.md

How to use

Save this as AGENTS.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

# AGENTS.md: Effect (TypeScript)

## Commands
`pnpm check` (tsc) · `pnpm lint` · `pnpm test` (`@effect/vitest`) · check `package.json` for the `effect` version and follow that version's docs.

## Rules
- Business logic returns `Effect<A, E, R>`; don't mix in raw `async/await` + `try/catch` in core modules. Convert at the edges with `Effect.tryPromise({ try, catch })`.
- Write effects with `Effect.gen(function* () { const x = yield* ... })` for readability; use `pipe` for short combinator chains.
- Errors are typed values: define them with `Data.TaggedError("NotFound")<{ id: string }>` (or `Schema.TaggedError`) and handle with `Effect.catchTag`/`catchTags`. Reserve defects (`Effect.die`) for bugs, not expected failures.
- Dependencies are services: `class Db extends Context.Tag("Db")<Db, {...}>() {}` (or `Effect.Service`), provided via `Layer`s composed in one place (`MainLive`). No module-level singletons or hidden globals.
- Validate all external input (HTTP, env, files, queues) with `Schema` (`Schema.decodeUnknown`); read config with `Config` instead of `process.env`.
- Resources use `Effect.acquireRelease` / `Scope` so connections and handles always close.
- Concurrency is explicit: `Effect.all(xs, { concurrency: 5 })`, `Effect.forEach` with a bound; use `Effect.timeout` and `Schedule` for retries with backoff.
- Run effects only at the program edge (`Effect.runPromise`, `NodeRuntime.runMain`, or the platform HTTP server). Never call `runPromise`/`runSync` inside library code.
- Log with `Effect.log*` and add spans with `Effect.withSpan` for tracing.

## Tests
Use `it.effect` from `@effect/vitest`, provide test Layers instead of mocking modules, and use `TestClock` for time.

## Done
Typecheck, lint and tests pass with no `any` and no unhandled error channels (`E` is `never` at the entrypoint).