spnngl/agent-skills

Codificación en TypeScript

Flujo de trabajo

1. Orientarse. Lee las fuentes de verdad del proyecto antes de escribir: package.json (type, engines, packageManager, exports, scripts, dependencias principales instaladas), el archivo de bloqueo, cada tsconfig*.json a lo largo de su cadena extends, el workspace raíz, la configuración del framework, del linter y del formateador (pnpm-workspace.yaml, turbo.json, next.config.ts, biome.json, .oxlintrc.json), y el CI para los comandos de verificación canónicos. Ejecuta tsc --showConfig para resolver la cadena extends; omite las opciones que quedan en su valor predeterminado, así que léelas desde references/modules.md (TypeScript 6 y 7 las cambiaron). Lee el módulo que estás cambiando y sus módulos vecinos; reutiliza sus ayudantes, tipos de error, esquemas y patrones. Listo cuando: puedas nombrar el gestor de paquetes, la versión mayor de TypeScript, module y moduleResolution, las banderas de rigor más allá de strict (noUncheckedIndexedAccess, exactOptionalPropertyTypes, erasableSyntaxOnly), la cadena de herramientas de lint y formato, y los comandos de verificación del proyecto.

2. Modelar los tipos. Diseña los datos antes que el flujo de control, siguiendo Tipos. Entrada desde fuera del proceso: lee references/zod.md. Cambiar la API pública de un paquete: lee references/api.md. Listo cuando: cada invariante del que depende el cambio esté codificado en un tipo, y cada valor que cruce un límite de confianza sea analizado por un esquema antes de su uso.

3. Implementar en un bucle cerrado. Trabaja en pasos pequeños y ejecuta tsc --noEmit (tsc -b con referencias de proyecto) después de cada uno. Lee el diagnóstico completo; su código (TS2742) es la clave de búsqueda en las tablas de references/modules.md y references/types.md. Para la API de una dependencia, lee su .d.ts en node_modules/<pkg>/ en la versión instalada. Corrección de errores: escribe primero la prueba de regresión y observa que se ponga roja. Listo cuando: el cambio verifique tipos sin nuevos diagnósticos, y cualquier prueba de regresión se haya puesto roja antes de la corrección y verde después.

4. Verificar. Ejecuta los comandos del proyecto desde el paso 1 a través de su gestor de paquetes (pnpm exec, npx, bunx); de lo contrario, para la cadena de herramientas que utiliza el proyecto:

   tsc --noEmit                                           # tsc -b cuando tsconfig.json solo lista referencias
   biome ci                                               # Biome
   oxfmt --check && oxlint --type-aware --deny-warnings   # oxlint + oxfmt
   vitest run --typecheck                                 # o el ejecutor de pruebas del proyecto
   

   • Un tsconfig.json raíz con "files": [] y references hace que tsc --noEmit no verifique nada; usa tsc -b. En un workspace sin un tsconfig raíz, ejecuta las verificaciones por paquete a través del ejecutor de tareas (turbo run check-types test).
   • Mantén tsc en el bucle con cada linter: la inferencia de tipos de Biome y las reglas conscientes de tipos de oxlint lo complementan, nunca lo reemplazan.
   • Fallos de formato: aplica el formateador (biome check --write, oxfmt) en lugar de editar manualmente.
   • Arregla los diagnósticos en la causa. Cuando la supresión sea correcta, limítala a una línea y da la razón: // biome-ignore lint/<grupo>/<regla>: razón, // oxlint-disable-next-line <regla> -- razón, // @ts-expect-error razón.
   • Configuración de lint o formato modificada: compruébala contra references/lints.md, luego ejecuta el linter y el formateador sobre todo el repositorio, no solo sobre los archivos modificados.
   • API pública de un paquete publicado modificada: ejecuta references/api.md. Listo cuando: cada comando salga con 0, las líneas que cambiaste no generen advertencias, y cada nueva supresión lleve una razón.

5. Autorevisar el diff. Vuelve a leer el git diff completo (git add -A && git diff --cached cuando los archivos son nuevos), no de memoria, comparándolo con Reglas y las reglas de cada archivo de referencia cuya rama toque el diff. Listo cuando: cada bloque sea requerido por la tarea, console.log, debugger, .only y el código comentado hayan desaparecido, los comentarios de documentación coincidan con el comportamiento, y cada regla aplicable se cumpla para cada bloque.

Revisar el código de otra persona: ejecuta el paso 1, ejecuta los comandos del paso 4 cuando puedas, luego aplica el paso 5 a su diff. Reporta cada hallazgo como ruta:línea, la regla y la corrección.

Reglas

Tipos

• Acota con evidencia: typeof, instanceof, in, una verificación discriminante, un predicado de tipo o un análisis de esquema. any, el ! no nulo y as T están prohibidos, también en pruebas; as const y satisfies se mantienen. Cuando los tipos de una biblioteca sean incorrectos, arréglalos en la fuente con aumento de módulo (references/types.md).
• Haz que los estados ilegales sean irrepresentables: una unión discriminada con un campo kind literal, en lugar de banderas boolean más campos opcionales. Marca IDs, unidades y valores validados a través de un esquema (z.string().brand<"UserId">()) o un predicado de tipo, nunca con as.
• Analiza, no valides: JSON.parse, Response.json(), variables de entorno, almacenamiento, parámetros de URL y datos de postMessage son unknown hasta que un esquema Zod los analice en el límite; pasa el tipo analizado hacia adentro.
• Haz un switch exhaustivo sobre uniones que posees: termina con default: x satisfies never; throw new Error(...), o mapea con una búsqueda Record<Union, V> que falle al compilar cuando se añada un miembro.
• El acceso indexado es T | undefined bajo noUncheckedIndexedAccess: maneja el undefined (guardia, ?? valorPorDefecto, for...of) en lugar de afirmar que no está.
• Las funciones exportadas declaran su tipo de retorno; las locales se infieren.
• interface para formas de objeto, extends sobre intersecciones con &; type para uniones, tipos mapeados y condicionales.
• Acepta readonly T[] y Readonly<T> para entradas que la función no muta.
• Una unión de literales de cadena o un objeto as const, en lugar de enum y namespaces con código en tiempo de ejecución (ambos prohibidos bajo erasableSyntaxOnly).

Errores y asincronía

• Los fallos esperados que el llamador debe manejar devuelven un resultado discriminado; los errores y estados irrecuperables lanzan una subclase de Error con { cause }. Detalles: references/errors.md.
• Cada promesa es esperada, devuelta o pasada a un manejador que observe su rechazo.

Modismos actuales

Los datos de entrenamiento son anteriores a TypeScript 6 y 7: TypeScript 7 es el compilador nativo en Go, strict está activado por defecto, types por defecto es [], y baseUrl, outFile, target: "ES5" y moduleResolution: "node10" se han eliminado (references/modules.md). Prefiere la forma actual, incluyendo las APIs de la biblioteca estándar por nivel de lib, cuando las versiones instaladas lo permitan. Cuando una referencia discrepe con el .d.ts del paquete instalado o su CHANGELOG, la versión instalada prevalece.

Preferir	En lugar de	Desde
const config = { ... } satisfies Config	const config: Config (ensancha), as Config	4.9
function f<const T>(x: T)	as const en cada punto de llamada	5.0
import type { T } con verbatimModuleSyntax	importsNotUsedAsValues (eliminado)	5.0
using / await using con [Symbol.dispose]	limpieza con try / finally	5.2, lib esnext
import data from "./d.json" with { type: "json" }	assert { type: "json" } (error desde 6.0)	5.3
NoInfer<T>	bloqueadores de inferencia T & {}	5.4
predicados inferidos: xs.filter((x) => x !== undefined)	guardias escritos a mano (x): x is T =>	5.5

Documentación y comentarios

• Los elementos exportados reciben documentación /** */ que indica el contrato: @throws para errores lanzados, @deprecated nombrando el reemplazo, @example cuando el uso no es obvio a partir de la firma.

Dependencias

• Reutiliza lo que package.json ya lista, y prefiere la plataforma cuando cubre la necesidad: fetch, structuredClone, crypto.randomUUID, AbortSignal.timeout, builtins con prefijo node:.
• Añade con el gestor de paquetes del proyecto, fijando @types/* a la versión mayor del paquete en tiempo de ejecución (@types/node: el Node más bajo en engines).

Referencias

Carga la que coincida con la rama en la que estás trabajando:

• references/types.md: genéricos, tipos condicionales y mapeados, predicados de tipo, aumento de módulo, errores a nivel de tipo.
• references/errors.md: definición de tipos de error, uniones de resultado, cause, límites de error entre capas.
• references/async.md: promesas, cancelación con AbortSignal, concurrencia, using, iteración asíncrona.
• references/modules.md: tsconfig.json, package.json, resolución de módulos, ESM y CommonJS, migración a TypeScript 6 y 7, errores de configuración.
• references/zod.md: análisis de entrada no confiable, esquemas, API de Zod 4.
• references/react.md: componentes React, hooks, APIs de React 19, React Compiler.
• references/nextjs.md: App Router de Next.js, Componentes y Funciones de Servidor, "use cache", tipos de ruta.
• references/recharts.md: gráficos Recharts, dataKey tipado, tooltips y formas personalizados, dimensionamiento de gráficos.
• references/lints.md: configuración o modificación de Biome, oxlint u oxfmt.
• references/testing.md: escritura de pruebas, pruebas de tipo, pruebas de componentes React, mocks.
• references/perf.md: verificación de tipos lenta, lag del editor, tamaño del bundle, una ruta crítica medida.
• references/api.md: diseño o modificación de la API pública de un paquete publicado, exports, archivos de declaración, semver; herramientas que importan typescript como biblioteca.
• references/runtimes.md: ejecución de .ts directamente en Node, Bun o Deno.
• references/monorepo.md: workspaces de pnpm, Turborepo, paquetes que dependen unos de otros.
• references/jsdoc.md: archivos .js verificados con checkJs, tipos JSDoc, migración de JavaScript a TypeScript.