[H1][TS-STANDARDS]
Dictum: Consolidation-first, polymorphic TypeScript. Effect orchestrates; domain computes.
Write dense, integrated modules with minimal public APIs. Prefer capability facades, command algebras, and auto-registration over helper proliferation and manual wiring.
Tasks:
- Read index.md.
- Read references/snippets.md first.
- Read domain references as needed: consolidation.md, composition.md, adts-and-matching.md, errors-and-services.md, repo-conventions.md.
- Implement by reusing canonical snippet IDs (
SNIP-*) instead of inventing new patterns.
- Run validator:
bash ./.claude/skills/ts-standards/scripts/validate-ts-standards.sh --mode check.
- Validate against [VERIFY] checklist.
Versions: TypeScript 6.0-dev, Effect 3.19+, React 19, Vite 7.
[1][WORKFLOW]
Dictum: Snippet-first workflow prevents style drift and file bloat.
- Select target behavior and public surface.
- Route to snippet IDs from references/snippets.md.
- Compose in this order: command algebra -> service surface -> layer integration -> boundary mapping.
- Keep internal symbols internal; integrate via registry/layer composition.
- Run policy validator and fix violations before final output.
[2][CORE_POLICY]
Dictum: Few powerful interfaces beat many narrow functions.
- Hard-minimal public APIs -- stable capability entrypoints only.
- Auto-integration by default -- new internal logic becomes active via registration, not extra exports.
- Polymorphism over proliferation -- one command/config function replaces clusters of near-duplicate methods.
- Exhaustive branching -- closed variants require
Match.exhaustive.
- Schema-derived types only -- no parallel manual types.
[3][NON_NEGOTIABLES]
Dictum: Compiler-visible constraints remove ambiguity.
[IMPORTANT]:
- [ALWAYS] Prefix private/internal symbols with
_.
- [ALWAYS] Gather public exports in final
[EXPORT] section.
- [ALWAYS] Use
Effect.Service for services and Effect.fn('Service.method') for methods.
- [ALWAYS] Reuse snippet IDs for shared patterns before authoring new variants.
- [ALWAYS] Keep each file in this skill directory at
<=275 LOC.
[CRITICAL]:
- [NEVER]
any, let, var, for, while, try/catch, default exports (except config files).
- [NEVER]
if (...) statements in TypeScript policy scope.
- [NEVER]
Effect.if(...).
- [NEVER] Helper/utility file sprawl (
helpers.ts, utils.ts, thin wrappers).
- [NEVER] Export
_-prefixed symbols.
- [NEVER] Widen package export surface without explicit policy update.
[4][PUBLIC_SURFACE_POLICY]
Dictum: Packages expose capabilities, not internals.
Server allowed exports:
./api./runtime./errors./testing
Database allowed exports:
./runtime./models./migrator./testing
Everything else is internal-by-default and consumed via internal composition.
[5][SNIPPET_ROUTING]
Dictum: Use canonical snippets as stable building blocks.
| [INDEX] |
[PROBLEM] |
[SNIPPET] |
| [1] |
Too many sibling methods |
SNIP-01 |
| [2] |
Manual handler wiring |
SNIP-02 |
| [3] |
Wide service object |
SNIP-03 |
| [4] |
Weak generic polymorphism |
SNIP-04 |
| [5] |
Error union leaks at boundaries |
SNIP-05 |
| [6] |
Hook/check validator architecture |
SNIP-06 |
[REFERENCE] Canonical code snippets: references/snippets.md
[6][VALIDATION]
Dictum: Automated gates enforce consistency at scale.
[FILE_LAYOUT]: Types -> Schema -> Constants -> Errors -> Services -> Functions -> Layers -> Export.
[VERIFY]:
Commands:
bash ./.claude/skills/ts-standards/scripts/validate-ts-standards.sh --mode checkpnpm run check:ts-standards
[REFERENCE] Script: scripts/validate-ts-standards.sh
1---2name: ts-standards3description: Enforces TypeScript/Effect standards with snippet-first guidance: algebraic data types, exhaustive pattern matching, schema-derived types, hard-minimal export surface, and auto-integrated internal functionality. Use when writing, refactoring, or reviewing TypeScript code.4---5
6# [H1][TS-STANDARDS]
7>**Dictum:** *Consolidation-first, polymorphic TypeScript. Effect orchestrates; domain computes.*
8
9<br>
10
11Write dense, integrated modules with minimal public APIs. Prefer capability facades, command algebras, and auto-registration over helper proliferation and manual wiring.
12
13**Tasks:**
141. Read [index.md](./index.md).
152. Read [references/snippets.md](references/snippets.md) first.
163. Read domain references as needed: [consolidation.md](references/consolidation.md), [composition.md](references/composition.md), [adts-and-matching.md](references/adts-and-matching.md), [errors-and-services.md](references/errors-and-services.md), [repo-conventions.md](references/repo-conventions.md).
174. Implement by reusing canonical snippet IDs (`SNIP-*`) instead of inventing new patterns.
185. Run validator: `bash ./.claude/skills/ts-standards/scripts/validate-ts-standards.sh --mode check`.
196. Validate against [VERIFY] checklist.
20
21**Versions:** TypeScript 6.0-dev, Effect 3.19+, React 19, Vite 7.
22
23---
24## [1][WORKFLOW]
25>**Dictum:** *Snippet-first workflow prevents style drift and file bloat.*
26
27<br>
28
291. Select target behavior and public surface.
302. Route to snippet IDs from [references/snippets.md](references/snippets.md).
313. Compose in this order: command algebra -> service surface -> layer integration -> boundary mapping.
324. Keep internal symbols internal; integrate via registry/layer composition.
335. Run policy validator and fix violations before final output.
34
35---
36## [2][CORE_POLICY]
37>**Dictum:** *Few powerful interfaces beat many narrow functions.*
38
39<br>
40
41- **Hard-minimal public APIs** -- stable capability entrypoints only.
42- **Auto-integration by default** -- new internal logic becomes active via registration, not extra exports.
43- **Polymorphism over proliferation** -- one command/config function replaces clusters of near-duplicate methods.
44- **Exhaustive branching** -- closed variants require `Match.exhaustive`.
45- **Schema-derived types only** -- no parallel manual types.
46
47---
48## [3][NON_NEGOTIABLES]
49>**Dictum:** *Compiler-visible constraints remove ambiguity.*
50
51<br>
52
53[IMPORTANT]:
54- [ALWAYS] Prefix private/internal symbols with `_`.
55- [ALWAYS] Gather public exports in final `[EXPORT]` section.
56- [ALWAYS] Use `Effect.Service` for services and `Effect.fn('Service.method')` for methods.
57- [ALWAYS] Reuse snippet IDs for shared patterns before authoring new variants.
58- [ALWAYS] Keep each file in this skill directory at `<=275` LOC.
59
60[CRITICAL]:
61- [NEVER] `any`, `let`, `var`, `for`, `while`, `try/catch`, default exports (except config files).
62- [NEVER] `if (...)` statements in TypeScript policy scope.
63- [NEVER] `Effect.if(...)`.
64- [NEVER] Helper/utility file sprawl (`helpers.ts`, `utils.ts`, thin wrappers).
65- [NEVER] Export `_`-prefixed symbols.
66- [NEVER] Widen package export surface without explicit policy update.
67
68---
69## [4][PUBLIC_SURFACE_POLICY]
70>**Dictum:** *Packages expose capabilities, not internals.*
71
72<br>
73
74**Server allowed exports:**
75- `./api`
76- `./runtime`
77- `./errors`
78- `./testing`
79
80**Database allowed exports:**
81- `./runtime`
82- `./models`
83- `./migrator`
84- `./testing`
85
86Everything else is internal-by-default and consumed via internal composition.
87
88---
89## [5][SNIPPET_ROUTING]
90>**Dictum:** *Use canonical snippets as stable building blocks.*
91
92<br>
93
94| [INDEX] | [PROBLEM] | [SNIPPET] |
95| :-----: | ----------------------------------- | --------- |
96| [1] | Too many sibling methods | `SNIP-01` |
97| [2] | Manual handler wiring | `SNIP-02` |
98| [3] | Wide service object | `SNIP-03` |
99| [4] | Weak generic polymorphism | `SNIP-04` |
100| [5] | Error union leaks at boundaries | `SNIP-05` |
101| [6] | Hook/check validator architecture | `SNIP-06` |
102
103[REFERENCE] Canonical code snippets: [references/snippets.md](references/snippets.md)
104
105---
106## [6][VALIDATION]
107>**Dictum:** *Automated gates enforce consistency at scale.*
108
109<br>
110
111[FILE_LAYOUT]: Types -> Schema -> Constants -> Errors -> Services -> Functions -> Layers -> Export.
112
113[VERIFY]:
114- [ ] No forbidden syntax (`any`, `let/var`, loops, `try/catch`, default exports, inline export style violations).
115- [ ] No `if (...)` and no `Effect.if(...)`.
116- [ ] No exported `_`-prefixed symbols.
117- [ ] Public export map complies with hard-minimal policy.
118- [ ] Deep imports from server/database follow approved allowlist.
119- [ ] All files under `/.claude/skills/ts-standards/` are `<=275` LOC.
120- [ ] Snippet-first reuse applied before adding custom variants.
121
122**Commands:**
123- `bash ./.claude/skills/ts-standards/scripts/validate-ts-standards.sh --mode check`
124- `pnpm run check:ts-standards`
125
126[REFERENCE] Script: [scripts/validate-ts-standards.sh](scripts/validate-ts-standards.sh)
majiayu000