spnngl/agent-skills

Codificação TypeScript

Fluxo de trabalho

1. Orientação. Leia as fontes de verdade do projeto antes de escrever: package.json (type, engines, packageManager, exports, scripts, maiores versões instaladas), o lockfile, cada tsconfig*.json junto com sua cadeia de extends, o workspace raiz, framework, lint e configuração de formatação (pnpm-workspace.yaml, turbo.json, next.config.ts, biome.json, .oxlintrc.json), e CI para os comandos canônicos de verificação. Execute tsc --showConfig para resolver a cadeia de extends; ele omite opções deixadas com seus valores padrão, então leia-as de references/modules.md (TypeScript 6 e 7 as alteraram). Leia o módulo que você está alterando e seus vizinhos; reutilize seus helpers, tipos de erro, schemas e padrões. Concluído quando: você puder nomear o gerenciador de pacotes, a versão principal do TypeScript, module e moduleResolution, as flags de rigor além de strict (noUncheckedIndexedAccess, exactOptionalPropertyTypes, erasableSyntaxOnly), o conjunto de ferramentas de lint e formatação, e os comandos de verificação do projeto.

2. Modele os tipos. Projete dados antes do fluxo de controle, seguindo Tipos. Entrada de fora do processo: leia references/zod.md. Alterando uma API pública de um pacote: leia references/api.md. Concluído quando: toda invariante da qual a alteração depende está codificada em um tipo, e todo valor que cruza um limite de confiança é analisado por um schema antes do uso.

3. Implemente em um loop apertado. Trabalhe em pequenos passos e execute tsc --noEmit (tsc -b com referências de projeto) após cada um. Leia o diagnóstico completo; seu código (TS2742) é a chave de pesquisa nas tabelas em references/modules.md e references/types.md. Para a API de uma dependência, leia seu .d.ts em node_modules/<pkg>/ na versão instalada. Correção de bug: escreva o teste de regressão primeiro e veja-o ficar vermelho. Concluído quando: a alteração verifica tipos sem novos diagnósticos, e qualquer teste de regressão ficou vermelho antes da correção e verde depois.

4. Verifique. Execute os comandos do projeto da etapa 1 através de seu gerenciador de pacotes (pnpm exec, npx, bunx); caso contrário, para o conjunto de ferramentas que o projeto usa:

   tsc --noEmit                                           # tsc -b quando tsconfig.json lista apenas referências
   biome ci                                               # Biome
   oxfmt --check && oxlint --type-aware --deny-warnings   # oxlint + oxfmt
   vitest run --typecheck                                 # ou o executor de testes do projeto
   

   • Um tsconfig.json raiz com "files": [] e references faz com que tsc --noEmit não verifique nada; use tsc -b. Em um workspace sem um tsconfig raiz, execute as verificações por pacote através do executor de tarefas (turbo run check-types test).
   • Mantenha tsc no loop com cada linter: a inferência de tipos do Biome e as regras com reconhecimento de tipo do oxlint o complementam, nunca o substituem.
   • Falhas de formatação: aplique o formatador (biome check --write, oxfmt) em vez de editar manualmente.
   • Corrija diagnósticos na causa. Quando a supressão for apropriada, limite-a a uma linha e forneça o motivo: // biome-ignore lint/<group>/<rule>: motivo, // oxlint-disable-next-line <rule> -- motivo, // @ts-expect-error motivo.
   • Configuração de lint ou formatação modificada: verifique-a em references/lints.md, depois execute o linter e o formatador em todo o repositório, não apenas nos arquivos alterados.
   • API pública de um pacote publicado modificada: execute references/api.md. Concluído quando: todo comando sai com código 0, as linhas que você alterou não geram avisos, e toda nova supressão carrega um motivo.

5. Auto-revisão do diff. Releia o git diff completo (git add -A && git diff --cached quando arquivos são novos), não sua memória dele, contra Regras e as regras de cada arquivo de referência cujo ramo o diff toca. Concluído quando: todo hunk é exigido pela tarefa, console.log, debugger, .only e código comentado foram removidos, comentários de documentação correspondem ao comportamento, e toda regra aplicável é válida para cada hunk.

Revisando o código de outra pessoa: execute a etapa 1, execute os comandos da etapa 4 quando possível, depois aplique a etapa 5 ao diff deles. Relate cada descoberta como caminho:linha, a regra e a correção.

Regras

Tipos

• Restrinja com evidência: typeof, instanceof, in, uma verificação discriminante, um predicado de tipo ou uma análise de schema. any, o ! não-nulo e as T são proibidos, mesmo em testes; as const e satisfies permanecem. Quando os tipos de uma biblioteca estão errados, corrija-os na fonte com augmentação de módulo (references/types.md).
• Torne estados ilegais irrepresentáveis: uma união discriminada com um campo kind literal, em vez de flags boolean mais campos opcionais. Marque IDs, unidades e valores validados através de um schema (z.string().brand<"UserId">()) ou um predicado de tipo, nunca as.
• Analise, não valide: JSON.parse, Response.json(), variáveis de ambiente, armazenamento, parâmetros de URL e dados postMessage são unknown até que um schema Zod os analise no limite; passe o tipo analisado para dentro.
• Faça switch exaustivo em uniões que você possui: termine com default: x satisfies never; throw new Error(...), ou mapeie com uma busca Record<Union, V> que falhe ao compilar quando um membro é adicionado.
• Acesso indexado é T | undefined sob noUncheckedIndexedAccess: trate o undefined (guarda, ?? fallback, for...of) em vez de afirmar que não existe.
• Funções exportadas declaram seu tipo de retorno; locais permanecem inferidos.
• interface para formas de objeto, extends em vez de interseções com &; type para uniões, tipos mapeados e condicionais.
• Aceite readonly T[] e Readonly<T> para entradas que a função não modifica.
• Uma união de literais string ou um objeto as const, em vez de enum e namespaces com código em tempo de execução (ambos proibidos sob erasableSyntaxOnly).

Erros e async

• Falhas esperadas que o chamador deve tratar retornam um resultado discriminado; bugs e estados irrecuperáveis lançam uma subclasse de Error com { cause }. Detalhes: references/errors.md.
• Toda promise é aguardada, retornada ou passada para um manipulador que observa sua rejeição.

Idiomas atuais

Dados de treinamento são anteriores ao TypeScript 6 e 7: TypeScript 7 é o compilador nativo em Go, strict está ativado por padrão, types padroniza para [], e baseUrl, outFile, target: "ES5" e moduleResolution: "node10" foram removidos (references/modules.md). Prefira a forma atual, incluindo APIs da biblioteca padrão pelo nível lib, quando as versões instaladas permitirem. Onde uma referência discordar do .d.ts ou CHANGELOG do pacote instalado, a versão instalada vence.

Prefira	Em vez de	Desde
const config = { ... } satisfies Config	const config: Config (amplia), as Config	4.9
function f<const T>(x: T)	as const em cada ponto de chamada	5.0
import type { T } com verbatimModuleSyntax	importsNotUsedAsValues (removido)	5.0
using / await using com [Symbol.dispose]	try / finally para limpeza	5.2, lib esnext
import data from "./d.json" with { type: "json" }	assert { type: "json" } (erro desde 6.0)	5.3
NoInfer<T>	bloqueadores de inferência T & {}	5.4
predicados inferidos: xs.filter((x) => x !== undefined)	guards manuais (x): x is T =>	5.5

Documentação e comentários

• Itens exportados recebem documentação /** */ declarando o contrato: @throws para erros lançados, @deprecated nomeando o substituto, @example quando o uso não é óbvio pela assinatura.

Dependências

• Reutilize o que package.json já lista e prefira a plataforma quando ela cobrir a necessidade: fetch, structuredClone, crypto.randomUUID, AbortSignal.timeout, builtins prefixados com node:.
• Adicione com o gerenciador de pacotes do projeto, fixando @types/* à versão principal do pacote em tempo de execução (@types/node: o Node mais baixo em engines).

Referências

Carregue a correspondente ao ramo em que você está:

• references/types.md: genéricos, tipos condicionais e mapeados, predicados de tipo, augmentação de módulo, erros em nível de tipo.
• references/errors.md: definindo tipos de erro, uniões de resultado, cause, limites de erro entre camadas.
• references/async.md: promises, cancelamento com AbortSignal, concorrência, using, iteração assíncrona.
• references/modules.md: tsconfig.json, package.json, resolução de módulos, ESM e CommonJS, migração TypeScript 6 e 7, erros de configuração.
• references/zod.md: analisando entrada não confiável, schemas, API Zod 4.
• references/react.md: componentes React, hooks, APIs React 19, React Compiler.
• references/nextjs.md: Next.js App Router, Componentes e Funções de Servidor, "use cache", tipos de rota.
• references/recharts.md: gráficos Recharts, dataKey tipada, tooltips personalizados e formas, dimensionamento de gráficos.
• references/lints.md: configurando ou alterando Biome, oxlint ou oxfmt.
• references/testing.md: escrevendo testes, testes de tipo, testes de componentes React, mocks.
• references/perf.md: verificação de tipos lenta, lag do editor, tamanho do bundle, um caminho crítico medido.
• references/api.md: projetando ou alterando a API pública de um pacote publicado, exports, arquivos de declaração, semver; ferramentas que importam typescript como biblioteca.
• references/runtimes.md: executando .ts diretamente no Node, Bun ou Deno.
• references/monorepo.md: workspaces pnpm, Turborepo, pacotes que dependem uns dos outros.
• references/jsdoc.md: arquivos .js verificados com checkJs, tipos JSDoc, migrando JavaScript para TypeScript.