Learn

LLM Workflow: Vendoring Effect Source

AI agents write better Effect code when they can read the actual source. Docs describe APIs; source shows patterns, conventions, and edge cases.

Why Vendoring Helps

When an AI agent works with Effect, it needs to know:

  • Which patterns the maintainers use (e.g., Effect.fn over wrapping Effect.gen)
  • Which APIs are v3 vs v4 (the import map is huge)
  • What the anti-patterns are (try-catch in generators, missing return yield*)
  • How services, layers, and scopes compose in practice

Official docs are large (SCHEMA.md alone is 7410 lines) and describe APIs, not conventions. Pattern files in the repo (like .patterns/effect.md) encode conventions that docs don’t cover. Having the source vendored lets agents search and read these directly.

Vendoring with git subtree

# Add Effect source as a subtree in your project
git subtree add --prefix=vendor/effect git@github.com:Effect-TS/effect.git main --squash

# Update later
git subtree pull --prefix=vendor/effect git@github.com:Effect-TS/effect.git main --squatch

Use SSH URLs. Verify SSH access first:

ssh -T git@github.com

Gotcha: The Effect monorepo is large. If you only need the core package, a shallow clone is cheaper:

git clone --depth 1 git@github.com:Effect-TS/effect.git vendor/effect

A shallow clone gives you the latest source without history. Update with git pull --ff-only.

What to Read First

When the source is vendored, point agents at these files in priority order:

  1. vendor/effect/LLMS.md - canonical guide for writing Effect code. Covers Effect.gen, Effect.fn, services, error handling, streams, testing.
  2. vendor/effect/.patterns/effect.md - anti-patterns and conventions not in the docs.
  3. vendor/effect/migration/v3-to-v4.md - the full import map. Essential when upgrading.
  4. vendor/effect/migration/*.md - individual migration docs for yieldable, services, error handling, layers, fiber keep-alive.
  5. vendor/effect/packages/effect/README.md - package overview and module list.
  6. vendor/effect/packages/effect/SCHEMA.md - comprehensive Schema guide (read in chunks).

AGENTS.md Configuration

Add vendored Effect guidance to your project’s AGENTS.md so agents know where to look:

## Effect

This project uses Effect v4. Source is vendored at `vendor/effect/`.

Before writing Effect code, read:
- `vendor/effect/LLMS.md` - canonical coding guide
- `vendor/effect/.patterns/effect.md` - anti-patterns to avoid
- `vendor/effect/migration/v3-to-v4.md` - import map for v4

Key conventions:
- Use `Effect.fn("name")` for reusable effect functions, not `(args) => Effect.gen(...)`
- Use `return yield*` for terminal effects (fail, interrupt, die)
- Never use try-catch inside Effect.gen
- Define services with `Context.Service<Self, Shape>()("id")`
- Define layers explicitly with `Layer.effect` (no auto-generated `.Default`)
- Use `Effect.catch` not `Effect.catchAll` (v4 rename)
- Use `Ref.get(ref)` not `yield* ref` (v4 Yieldable changes)

Creating Pattern Files

Pattern files encode API-specific conventions. Put them in vendor/effect/.patterns/ or in your project’s _docs/:

<!-- .patterns/schema.md -->
# Schema Patterns

## Always use Schema for validation
Never write manual validation predicates. Use Schema.Struct or Schema.Class.

## Decode at boundaries
Use Schema.decodeUnknown at system boundaries (HTTP, DB, config).
Use the typed value everywhere else.

## Define errors with Schema.TaggedError
Not plain Error classes. TaggedError integrates with Effect.catchTag.
<!-- .patterns/services.md -->
# Service Patterns

## Class syntax for all services
class MyService extends Context.Service<MyService, Shape>()("myapp/MyService") {}

## Static layer on the class
static readonly layer = Layer.effect(this, this.make)

## Use yield* not Service.use
Prefer `const svc = yield* MyService` over `MyService.use(fn)`.
Dependencies are explicit in generators.

Tip: Pattern files should be short. Each file covers one API area. A few concrete do/don’t examples are worth more than paragraphs of explanation.

tsgo LSP for Better Feedback

The Effect team maintains tsgo, a TypeScript compiler fork optimized for Effect. Benefits for AI agents:

  • Faster type checking (important for iterative agent workflows)
  • Better error messages for Effect-specific patterns
  • Catches missing yield* and wrong return types that stock tsc misses
# Install
npm install -D @effect/tsgo

# Use in place of tsc
npx @effect/tsgo check

Tip: If agents are generating Effect code and hitting type errors, tsgo produces clearer messages. This helps agents self-correct faster in autonomous workflows.

Workflow for AI-Assisted Effect Development

  1. Vendor the source so agents can read patterns and conventions.
  2. Configure AGENTS.md with the file reading list and key conventions.
  3. Create pattern files for project-specific Effect usage (schema, services, error handling).
  4. Use tsgo for type checking to get faster, clearer feedback.
  5. Point agents at migration docs when upgrading from v3 to v4.
  6. Keep the vendor updated with git subtree pull or git pull --ff-only (for shallow clones) before starting new work.