typescript-best-practices
TypeScript best practices. Use when reading or editing any .ts or .tsx file.
- License 许可
- MIT
- 最近更新
- 2026-11-12
- Stars
- ★ 1
- Forks
- 1
01 前言 Front Matter
- name
- typescript-best-practices
- paths
- [ "**/*.ts", "**/*.tsx" ]
- description
- TypeScript best practices. Use when reading or editing any .ts or .tsx file.
02 资源文件 1
- 参考文档references/patterns.md9.0 KB
03 SKILL.md 正文
TypeScript best practices
Apply the type-system-discipline principle skill first.
| Rule | Summary |
|---|---|
| Discriminated unions | Model variants with a kind literal discriminant so impossible states can't be represented. No optional-field bags. |
| Branded types | Brand primitives with & { readonly __brand: "X" } so they can't be mixed up. Validate once at the boundary. |
| Constructive modeling | Build the shape so the illegal value can't be constructed. [T, ...T[]] for non-empty, [T, T][] for even length, start plus duration for a range. Not a runtime guard, not a wish for refinement types. |
| Simplest total type | Keep T[] while every operation on it stays total. Strengthen to NonEmpty<T> only where the loose type forces !, a cast, or a "should never happen" throw. |
unknown over any |
External data is unknown. |
| Schemas before guards | Before hand-writing a property-by-property type guard, use the repository's runtime schema library and infer the type from the schema, such as z.infer. |
No as casts |
Every as is a runtime crash waiting. Cast only after validation. |
| Narrowing hierarchy | Discriminant switch > in operator > typeof/instanceof > user-defined type guard > as. |
| Type guards | Must verify the claim. A lying guard is worse than as because the bug hides behind a name that says it's safe. Name them isX or hasX. |
| Exhaustiveness | Inline const _exhaustive: never = x; in default arms so the compiler errors when a new variant is added. |
satisfies over as |
Validates the value without widening literal types. |
| Boundary validation | Parse where data crosses in, into a named domain type. Record<string, unknown> (however spelled) stops at that parse. Trust types inside. See the boundary-discipline principle skill. |
| Schema-derived types | Reach for Pick/Omit/Parameters/ReturnType/Awaited/typeof before declaring a new interface. |
| Object args | Pass objects, not positional, so argument order is self-documenting. Skip on hot paths (per-frame render, tokenizers, parsers). |
| Real tests | Don't mock what you can run. Prefer the framework's real test primitives with leak/disposable checks, and verify UI in a running build. Mock only what you can't run locally. |
| Structured telemetry | Prefer structured logger diagnostics with enough context to debug from an id. No console.log in shipped code. |
Examples: references/patterns.md.
04 同仓库更多 Skills
code-review
Review the changes since a fixed point (commit, branch, tag, or merge-base) along five axes: Standards (does the code follow this repo's documented coding standards?), Spec (does the code match what the originating issue/spec asked for?), Evidence (does each claim in the pull request have evidence that shows it?), Bugs (does the changed code have logic errors, unhandled states, races, or regressions?), and Security (does the change open injection, auth, secret, input, or CI workflow holes?). Runs the reviews in parallel sub-agents, tags every finding Important, Nit, or Pre-existing, and reports them side by side with what blocks merge. Given an earlier reviewed head and its findings, it reviews only the newer commits, rechecks the earlier findings, and never repeats one. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X".
writing-for-pstack
Write or tighten an operator prompt for a patina-mode run. Use when the operator asks to write, revise, or review a prompt that will be passed to patina-mode.
writing-for-agents
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
wizard
Generate an interactive bash wizard that walks a human through steps only they can perform. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself.
wayfinder
Plan a huge chunk of work (more than one agent session can hold) as a shared map of decision tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear.
wait-what
Stop. That last message did not land: re-pitch it.