Effect Agent Rules

A TypeScript library for composing applications with typed effects, concurrency, and resource management.

Overview

Effect keeps its contributor guide in .agents/AGENTS.md. Each kind of change has a focused check, and generated output points back to its source. The guide also avoids watch-mode full suites and protects hand-maintained indexes and unmarked sections.

Verification by change type Hard prohibitions Generated file guards

Documents

└── .agents
    └──

Techniques in this file

01 / Verification by change type

Distinguish type checks, prose, and executable examples

The validation table gives API type changes, JSDoc text changes, and JSDoc examples different commands. Documentation-only work does not need tests unless examples or code changed.

17Use the narrowest validation that covers the change:18 19| Change type                      | Validation                                                                         |20| -------------------------------- | ---------------------------------------------------------------------------------- |21| Code changes                     | `pnpm lint-fix`, targeted `pnpm test --run <test_file.ts>`, `pnpm check`           |22| Tests-only changes               | `pnpm lint-fix`, targeted `pnpm test --run <test_file.ts>`, `pnpm check`           |23| Type-level/API type changes      | Targeted `pnpm test-types <filename>`, plus `pnpm check` when source types changed |24| JSDoc text/category/link changes | `pnpm jsdocs --check`, `pnpm lint`                                                 |25| JSDoc example changes            | `pnpm jsdocs --check`, `pnpm lint`, root `pnpm doctest --run <files>`              |26| Docs-only changes                | `pnpm lint-fix`; no tests unless examples or code changed                          |

02 / Hard prohibitions

Prevent accidental watch-mode suites

The guide explains why bare test commands are prohibited: they start the whole suite in watch mode. It requires explicit run mode and file selection, leaving the full suite to CI.

28Never run bare `pnpm test` or `pnpm doctest`; both start the full suite in watch mode. Always pass `--run` and the29specific files covering the change. CI runs the full suite.

03 / Generated file guards

Guard generated regions without freezing the whole file

The barrel rule protects only marked generated sections, not hand-maintained indexes or unmarked code. The guide also names the sources for generated AI docs and migration notes.

39Some `index.ts` sections marked with `@barrel` are generated. Do not edit those40sections manually; update their source modules and run `pnpm codegen`.41Hand-maintained `index.ts` files and unmarked sections are not covered by this42rule.

Ideas for your repo

Give type-level changes and executable documentation their own validation paths.
Name commands that unexpectedly start full suites or watch mode, and provide bounded alternatives.
Define generated regions precisely, including what remains hand-maintained.
Point each generated artifact at the source and command used to rebuild it.