do-not-widen-types-to-silence-the-checker
Quando um verificador de tipos rejeita uma chamada ou um valor de retorno, estreite o valor ou trate o caso ausente em vez de alargar a anotação para Any, object ou uma união não verificada.
Conferida por quem revisou e leu o cartão, não reivindicada pelo próprio arquivo. Um cartão que o agente destila durante uma execução que consumiu conteúdo não confiável nasce contaminado e fica retido para revisão antes de alguma vez ser recuperado.
Quando ele vem à mente
- erro do verificador de tipos em um argumento ou valor de retorno
- a tentação de adicionar Any ou cast para fazer o mypy ou pyright passarem
- a união inclui None e o chamador espera um tipo concreto
- alargar uma assinatura só para satisfazer um único ponto de chamada
Evite e Verifique são onde costuma estar o valor. Faça é a seção que todo mundo escreve.
O corpo do cartão acima é uma tradução. O original em inglês é o que a CLI importa, o que o agente lê em execução e o que o hash abaixo atesta.
Gatilho
Um verificador de tipos estático (mypy, pyright, tsc, cargo check) aponta um tipo incompatível, por exemplo passar str | None onde se exige str, ou retornar uma união mais ampla que a assinatura declara. O caminho mais rápido para o diagnóstico sumir é alargar a anotação do parâmetro ou do retorno (Any, object, unknown, # type: ignore, ou acrescentar | None a uma interface que nunca quis aceitá-lo).
Faça
- Entenda o que o verificador está provando: qual ramo pode produzir o tipo inesperado e se esse ramo é alcançável em tempo de execução. 2. Se o valor mais amplo é um bug ou um caso de borda não tratado no ponto de chamada, estreite-o antes da chamada: teste contra
None, valide a entrada na fronteira ou lance um erro claro logo no início. 3. Se a função realmente aceita o tipo mais amplo, atualize a implementação para tratar todos os membros desse tipo antes de alargar a assinatura. 4. Mantenha a fronteira estreita: interprete ou refine dados não tipados (dict[str, Any], JSON bruto) uma única vez, na entrada do módulo, em vez de propagar tipos largos para dentro.
Evite
Tratar o verificador de tipos como um obstáculo a ser apaziguado, em vez de uma prova de que um ramo não está tratado. O modo de falha clássico é mudar def load_user(user_id: str) -> User para aceitar str | None ou retornar User | Any porque um chamador esqueceu de checar se user_id estava presente. O verificador fica verde de imediato, o None não tratado passa de um erro estático na fronteira para um AttributeError em tempo de execução três quadros adiante, e todo chamador a jusante passa a herdar a união mais ampla ou perde a verificação por completo. Igualmente ruim é colocar cast(...) ou # type: ignore em uma linha sem um invariante no código imediatamente anterior que torne o cast verdadeiro.
Verifique
Rode o verificador de tipos no módulo tocado e inspecione o diff de cada assinatura alterada. Todo parâmetro ou retorno recém-alargado tem um ramo explícito ou um teste cobrindo o caso acrescentado. Nenhum Any, cast ou # type: ignore foi introduzido apenas para silenciar uma divergência que poderia ser resolvida estreitando na fronteira. Os chamadores a jusante não precisaram acrescentar verificações defensivas para um tipo que o produtor nunca precisou emitir.
Risco
Às vezes um stub de biblioteca está genuinamente errado ou incompleto, ou um payload externo é realmente arbitrário até que uma etapa posterior o inspecione. Nesses casos, um # type: ignore[code] localizado e documentado, ou um adaptador de fronteira estreito, é melhor do que deformar o código de execução com ramos mortos só para satisfazer um stub quebrado.
Como usar
O cartão é dado. Clone o repositório e importe pelo caminho — o que chega pela rede é tratado como contaminado e fica retido para aprovação, que é o comportamento desejável e a razão de não haver um instalador de uma linha aqui.
git clone https://github.com/brcampidelli/chimera-agent.gitchimera skills-import chimera-agent/skills/do-not-widen-types-to-silence-the-checker/SKILL.mdIntegridade
SHA-256 do arquivo como publicado. Quem importa pode conferir que o que recebeu é o que esta página mostrou.
9fdad16332fb728bb73f495c19effaeab028d4160a220ad94a8ff0ab8996a5b9