hypergadam/agent-skills

Revisão de código Go

Objetivo: a mudança deve tornar a base de código mais saudável. Não precisa ser perfeita. Não bloqueie uma mudança por gosto pessoal.

Passo 1: Obter a mudança

• Se o usuário forneceu um diff, PR ou arquivos, use isso.
• Em um repositório git: git diff --stat main...HEAD, depois git diff main...HEAD (tente master ou origin/main se main não existir). Para trabalho não commitado: git diff e git diff --staged.
• Se o propósito da mudança não estiver claro, pergunte em uma linha curta.

Passo 2: Ler o contexto

• Abra o arquivo inteiro ao redor de cada função alterada, não apenas as linhas do diff.
• Encontre chamadores de funções exportadas alteradas: grep -rn "FuncName(" --include=*.go
• Verifique a versão do Go no go.mod. Alguns conselhos dependem dela (variáveis de laço são por iteração desde Go 1.22).

Passo 3: Executar as ferramentas (se você puder executar comandos)

go build ./...
go vet ./...
go test -race ./...              # apenas pacotes alterados se o repositório for lento
golangci-lint run ./...          # apenas se estiver instalado ou o repositório tiver uma configuração

Relate falhas reais. Para formatação, diga "rode gofmt" uma vez; não liste cada linha. Se você não puder executar comandos, diga isso em uma linha.

Passo 4: Revisar nesta ordem

Primeiro as coisas grandes. Se o design estiver errado, diga isso primeiro e pule os detalhes pequenos.

1. Design – Esta mudança pertence aqui (este pacote, este serviço)? Ela se encaixa no resto do sistema? É o momento certo para ela?
2. Funcionalidade – Ela faz o que o autor queria? Isso é bom para as pessoas que a usam (usuários finais e futuros desenvolvedores)? Pense em casos extremos e concorrência.
3. Complexidade – Um leitor consegue entender rapidamente? Cuidado com superengenharia: código construído para um futuro imaginado em vez do problema atual.
4. Testes – Há testes na mesma mudança? Eles falhariam se o código quebrasse? Eles são simples?
5. Nomenclatura – Clara, não muito longa, estilo Go.
6. Comentários – Explique por que, não o que. Comentários obsoletos e TODOs concluídos removidos.
7. Estilo – gofmt, guia de estilo. Preferência pessoal = apenas Nit.
8. Consistência – O guia de estilo prevalece sobre o código ao redor. Se o guia não diz nada, siga o código ao redor.
9. Documentação – README, godoc, variáveis de config/env, migrações atualizadas se o comportamento mudou.
10. Cada linha – Leia todo o código escrito por humanos. Código gerado (*.pb.go, mocks, saída sqlc) pode ser analisado superficialmente.
11. Saúde do código – O sistema como um todo melhora ou piora com esta mudança?
12. Coisas boas – Nomeie coisas boas reais que você vê.

Para verificações específicas de Go em cada área, leia references/go-checklist.md. Sempre verifique suas seções de Erros, Concorrência e Recursos; a maioria dos bugs em Go está lá.

Rótulos de severidade

• Bloqueador – bug, condição de corrida (data race), vazamento de goroutine, problema de segurança, teste quebrado, design errado. Deve ser corrigido antes do merge.
• Deve corrigir – problema real, não urgente. O autor pode argumentar.
• Nit – melhoria opcional pequena. Sempre comece o comentário com "Nit:".
• Pergunta – algo que você não entende. Se você não consegue entender, outros também não conseguirão; peça código mais claro.

Não invente problemas. Uma boa mudança recebe uma revisão curta. Se você não tem certeza se algo é um bug, use Pergunta, não Bloqueador. Se for solicitado a revisar apenas alguns arquivos ou aspectos, diga quais partes você revisou.

Formato de saída

## Resumo
1–2 frases: o que a mudança faz. Verdicto: Aprovar / Aprovar com comentários / Precisa de alterações.

## Bloqueadores
- `caminho/arquivo.go:42` – o que está errado e por que importa.
```go
  // correção sugerida
```

## Deve corrigir
## Nits
## Perguntas
## Coisas boas

## O que revisei
Ferramentas executadas e resultados, arquivos revisados, qualquer coisa pulada.

Deixe seções vazias de fora. Cada comentário: problema, por que, correção. Mantenha curto.