Disponibilidade de Material de Apoio

Esta cópia do catálogo contém as orientações inline abaixo, mas não inclui os seguintes caminhos de suporte. Eles são pré-requisitos externos, não arquivos incluídos:

• <support-root>/references/security-checklist.md
• <support-root>/references/performance-checklist.md

Obtenha o material necessário da fonte upstream declarada ou de uma instalação fornecida pelo usuário dessa fonte. Resolva cada caminho em relação a essa instalação, inspecione seu conteúdo e verifique quaisquer licenças aplicáveis e pré-requisitos de execução. Não execute um comando ou reivindique que um procedimento referenciado foi seguido até que seu arquivo necessário exista. Não fabrique os scripts ausentes nem trate um arquivo não relacionado com o mesmo nome como equivalente. Etapas independentes totalmente documentadas aqui podem prosseguir dentro do escopo autorizado do usuário; relate qualquer etapa dependente como indisponível.

Revisão de Código e Qualidade

Visão Geral

Revisão de código multidimensional com portões de qualidade. Cada alteração é revisada antes do merge — sem exceções. A revisão abrange cinco eixos: correção, legibilidade, arquitetura, segurança e desempenho.

O padrão de aprovação: Aprove uma alteração quando ela melhora definitivamente a saúde geral do código, mesmo que não seja perfeita. Código perfeito não existe — o objetivo é a melhoria contínua. Não bloqueie uma alteração porque ela não está exatamente como você a escreveria. Se ela melhora a base de código e segue as convenções do projeto, aprove-a.

Quando Usar

• Antes de fazer o merge de qualquer PR ou alteração
• Após completar a implementação de uma funcionalidade
• Quando outro agente ou modelo produziu código que você precisa avaliar
• Ao refatorar código existente
• Após qualquer correção de bug (revise tanto a correção quanto o teste de regressão)

A Revisão de Cinco Eixos

Cada revisão avalia o código nessas dimensões:

1. Correção

O código faz o que afirma fazer?

• Ele corresponde à especificação ou aos requisitos da tarefa?
• Casos extremos são tratados (nulo, vazio, valores limite)?
• Caminhos de erro são tratados (não apenas o caminho feliz)?
• Ele passa em todos os testes? Os testes estão realmente testando as coisas certas?
• Existem erros de "off-by-one", condições de corrida ou inconsistências de estado?

2. Legibilidade e Simplicidade

Outro engenheiro (ou agente) consegue entender este código sem o autor explicá-lo?

• Os nomes são descritivos e consistentes com as convenções do projeto? (Sem temp, data, result sem contexto)
• O fluxo de controle é direto (evite ternários aninhados, callbacks profundos)?
• O código está organizado logicamente (código relacionado agrupado, limites claros de módulo)?
• Existem truques "inteligentes" que deveriam ser simplificados?
• Isso poderia ser feito em menos linhas? (1000 linhas onde 100 são suficientes é uma falha)
• Abstrações estão justificando sua complexidade? (Não generalize até o terceiro caso de uso)
• Comentários ajudariam a esclarecer intenções não óbvias? (Mas não comente código óbvio.)
• Existem artefatos de código morto: variáveis no-op (_unused), shims de compatibilidade retroativa ou comentários // removed?
• Uma nova condicional está sendo acoplada a um fluxo não relacionado? Isso é um "smell" de design, não um detalhe — mova a lógica para seu próprio helper, estado ou política em vez de emaranhar um caminho existente.
• Condicionais repetidas sobre a mesma forma aparecem? Elas sinalizam um modelo ou dispatcher ausente. Um branch "temporário" geralmente é dívida permanente.

3. Arquitetura

A alteração se encaixa no design do sistema?

• Ela segue padrões existentes ou introduz um novo? Se novo, é justificado?
• Ela mantém limites limpos de módulo?
• Existe duplicação de código que deveria ser compartilhada?
• As dependências fluem na direção certa (sem dependências circulares)?
• O nível de abstração é apropriado (não superengenharia, não muito acoplado)?
• Este refator reduz a complexidade ou apenas a realoca? Conte os conceitos que um leitor precisa manter para seguir a alteração. Se uma versão "mais limpa" não altera essa contagem, ela não é mais limpa — prefira a reestruturação que faz ramos inteiros, modos ou camadas desaparecerem em vez de uma que recentraliza a mesma lógica. Prefira excluir uma abstração a polí-la.
• Lógica específica de funcionalidade está vazando para um módulo compartilhado ou de propósito geral? Mantenha a lógica em sua camada de origem, reutilize o helper canônico existente em vez de um quase duplicado e não normalize o desvio arquitetural.

…