| name | coding-standards |
| description | Correct-by-construction TypeScript and Effect standards. Use for TypeScript engineering, Effect code, or when another skill needs the user's coding standards. |
TypeScript and Effect Coding Standards
Build correct by construction: parse data into meaningful types, make expected failures explicit, keep effects behind cohesive services, and test through real interfaces.
Decision priority
When rules pull in different directions:
- Preserve correctness, safety, and debuggability.
- Apply these standards to new code and the complete behavior being changed.
- Follow compatible repository architecture and conventions.
- Contain incompatible older patterns at the nearest existing edge.
- Keep unrelated behavior unchanged unless a broader migration was requested.
- Record meaningful trade-offs with comments or ADRs.
Core principles
- Expected failures are values; defects may throw or panic.
- Parse external and serialized data into domain/application types at the edge.
- Make illegal states unrepresentable where practical.
- Start meaningful services from explicit interfaces.
- Prefer composition, a functional core, and an imperative shell.
- Design deep, cohesive modules with low caller burden.
- Make every abstraction pass the deletion test.
- Test behavior through real interfaces using real or faithful implementations rather than module mocks.
- Prefer the simplest correct design and the least code.
1. Establish the local rules
Read the nearest AGENTS.md, package configuration, architecture docs, and the changed area's conventions for errors, schemas, services, tests, observability, and files.
Apply the decision priority above when local conventions conflict with these standards.
Complete when: the governing files and runtime/library versions have been identified, and every compatible or incompatible local pattern touching the changed behavior is accounted for.
