Merge commit '36c66dd290d3ce6eb1ccd310d0c658d4a32bb8eb' as 'repos/effect'
This commit is contained in:
-Puter
148
repos/effect/AGENTS.md
Normal file
148
repos/effect/AGENTS.md
Normal file
@@ -0,0 +1,148 @@
|
||||
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:
|
||||
|
||||
```md
|
||||
---
|
||||
"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.
|
||||
Reference in New Issue
Block a user