uinaf/agent-skills

React Ban useEffect

useEffect direto é uma escotilha de escape para sincronização externa. Ele reside em um hook revisado e específico de domínio para um sistema externo real; os componentes permanecem livres de efeitos.

Escopo

A substituição de efeitos altera o comportamento tocado. A imposição de lint em todo o repositório é uma tarefa separada: aplique-a quando solicitado ou exigido pela política existente do repositório. Uma solicitação de revisão produz conclusões; uma solicitação de implementação autoriza substituições no escopo e verificação sem outro ponto de aprovação.

Fluxo de Trabalho

1. Encontre importações diretas, chamadas de namespace React.useEffect(...) e wrappers em torno de useEffect na superfície tocada.

2. Classifique cada efeito e substitua-o nesta ordem de preferência:

   1. cálculo em tempo de renderização
   2. API de dados de servidor, loader ou framework
   3. a camada de estado do servidor do repositório (por exemplo, uma fábrica queryOptions do TanStack Query com variáveis na chave e o signal passado)
   4. manipulador de evento, ação ou mutação
   5. limite de componente com chave
   6. useSyncExternalStore
   7. hook revisado e específico de domínio para um sistema externo real

   Se nenhum se encaixar, declare o contrato de sincronização externa antes de manter um efeito. Substituições cobre os casos não óbvios.

3. Preserve o framework, camada de dados, formato de lint e política de dependência do repositório. Adicione uma biblioteca apenas quando a solicitação ou política do repositório autorizar; sem uma camada de estado do servidor, considere o efeito restante uma lacuna de design.

4. Execute lint, tipo e gates de teste, além da menor verificação real de UI ou hook para o comportamento alterado.

Efeitos Legítimos

Coloque cada efeito legítimo em um hook nomeado para seu sistema externo (uma conexão chat, um SDK de mapa, um widget), em seu próprio arquivo. O hook é responsável pela configuração e limpeza, recebe suas entradas reativas como parâmetros e lista cada valor que a configuração ou limpeza lê, para que react-hooks/exhaustive-deps passe sem supressão. Prefira um hook existente do repositório.

O hook é específico para um sistema externo. Um wrapper genérico que recebe um callback e um array de dependências fornecido pelo chamador (useUpdateEffect(fn, deps), useMountEffect(fn)) é um efeito direto sob outro nome, e estado de servidor, cópias de propriedades, ações do usuário e redefinições com chave cada um tem sua própria substituição acima.

Imposição

Quando a imposição está no escopo, estenda o linter existente do repositório para que ele rejeite tanto importações nomeadas useEffect quanto chamadas React.useEffect(...). Permita apenas os arquivos de hook de integração revisados e nomeados, não um diretório como src/hooks/**; relate wrappers genéricos e seus chamadores como violações a migrar. Execute a mesma superfície de lint no gate local canônico e no CI, com versões de ferramentas fixadas.

Na revisão, todo novo efeito direto é uma conclusão, a menos que a alteração documente e comprove um limite de sistema externo legítimo. Peça uma substituição, não ajuste no array de dependências.

Limites

• Escopo de migrações para a superfície tocada ou solicitada.
• Deixe useLayoutEffect, useInsertionEffect, APIs de ciclo de vida do framework e sistemas de efeitos não-React em paz, inclusive em regras de lint, a menos que solicitado.
• Aplique primitivas de desempenho apenas para comportamento medido ou um padrão estabelecido no repositório.
• Atribuição upstream: upstream.