zopu-code/repos/effect/AGENTS.md

This is the Effect library repository, focusing on functional programming patterns and effect systems in TypeScript.

Overview

• The git base branch is main.
• Use pnpm as the package manager.
• Keep changes focused and follow established patterns in the repository.
• Before writing code, read the relevant files in ./.patterns/ and inspect similar existing code.

Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

Before implementing:

• State your assumptions explicitly. If uncertain, ask.
• If multiple interpretations exist, present them - don't pick silently.
• If a simpler approach exists, say so. Push back when warranted.
• If something is unclear, stop. Name what's confusing. Ask.

Simplicity First

Minimum code that solves the problem. Nothing speculative.

• No features beyond what was asked.
• No abstractions for single-use code.
• No "flexibility" or "configurability" that wasn't requested.
• No error handling for impossible scenarios.
• If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

Surgical Changes

Touch only what you must. Clean up only your own mess.

When editing existing code:

• Don't "improve" adjacent code, comments, or formatting.
• Don't refactor things that aren't broken.
• Match existing style, even if you'd do it differently.
• If you notice unrelated dead code, mention it - don't delete it.

When your changes create orphans:

• Remove imports/variables/functions that YOUR changes made unused.
• Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

Goal-Driven Execution

Define success criteria. Loop until verified.

Transform tasks into verifiable goals:

• "Add validation" → "Write tests for invalid inputs, then make them pass"
• "Fix the bug" → "Write a test that reproduces it, then make it pass"
• "Refactor X" → "Ensure tests pass before and after"

For multi-step tasks, state a brief plan:

1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

Workflow

1. Inspect nearby implementation, tests, and pattern docs before editing.
2. Prefer existing abstractions and conventions over introducing new ones.
3. For ad hoc runnable code, create a temporary file in scratchpad/, run it with node scratchpad/<file>.ts, and delete it when done. The local runtime is Node 24, which can run TypeScript files directly; use plain node for local TypeScript probes instead of tsx unless node fails.
4. Run the validation appropriate to the change type.
5. Report which validation commands were run and any commands that could not be run.

Validation

Use the narrowest validation that still covers the change:

Change type	Validation
Code changes	pnpm lint-fix, targeted pnpm test <test_file.ts>, pnpm check
Tests-only changes	pnpm lint-fix, targeted pnpm test <test_file.ts>, pnpm check
Type-level/API type changes	Targeted pnpm test-types <filename>, plus pnpm check when source types changed
JSDoc text/category/link changes	pnpm lint
JSDoc example changes	pnpm lint; from the changed package directory, run pnpm docgen
Docs-only changes	pnpm lint-fix; no tests required unless examples or code changed

Bundle Size Preview

When asked to show bundle-size impact for a commit, use the existing bundle comparison workflow:

1. For the latest commit, run pnpm bundle-compare HEAD~1. For another base, run pnpm bundle-compare <base-ref>.
2. Read the Markdown report from tmp/bundle-stats.txt and summarize the non-zero differences.
3. Leave tmp/bundle-base in place unless cleanup is requested. To clean it up, run git worktree remove --force tmp/bundle-base.

Coding Patterns

Read .patterns/effect.md before changing Effect code. In particular:

• Prefer Effect.fnUntraced over functions that only return Effect.gen.
• Prefer class syntax for Context.Service.
• Do not use async / await or try / catch; use Effect APIs such as Effect.gen, Effect.fnUntraced, and Effect.tryPromise.
• Do not use Date.now or new Date; use Clock, and use TestClock in tests.

Testing

Read .patterns/testing.md before writing or changing tests.

• Test files are located in packages/*/test/.
• Main Effect library tests are in packages/effect/test/.
• Use it.effect for Effect-returning tests.
• Use regular it for pure synchronous tests.
• Do not use Effect.runSync in tests.
• Do not use expect from Vitest; use assert from @effect/vitest.
• Type-level tests are in packages/*/typetest/ and run with pnpm test-types <filename>.

Documentation

• For AI documentation, read ai-docs/README.md very carefully before writing examples.
• AI documentation changes may include explanatory comments when useful.
• For public JSDoc @category guidance, read .patterns/jsdoc.md.
• When JSDoc examples are localized to a single package, run pnpm docgen from that package directory instead of the repository root.

Generated Files

Do not hand-edit generated files. Run the appropriate generator instead.

• index.ts barrel files are generated; run pnpm codegen after adding or removing modules.

Changesets

Create a changeset in .changeset/ for runtime behavior changes or exported type/API changes:

---
"package-name": patch/minor/major
---

A description of the change.

Tests-only changes, internal refactors, docs-only changes, and JSDoc-only maintenance may skip changesets by maintainer decision.