O que uma Habilidade de Agente de SME de Go contém e quando invocá-la - dez exemplos para equipes que usam assistentes de IA em Go 1.26.x. Estas páginas documentam habilidades, não código de aplicação. Uma habilidade é um playbook SKILL.md que seu agente lê antes de agir.
Fixe a pilha em cada cabeçalho de habilidade para que os agentes nunca se desviem para APIs desatualizadas:
## Fixação de Pilha- Go 1.26.x (verificar patch na compilação)- golangci-lint (conjunto de linters da equipe)- HTTP: stdlib net/http por ADR-014 (ou chi - verificar na compilação)
Uma Habilidade de Agente é um arquivo de instrução estruturado - tipicamente SKILL.md - que diz a um assistente de IA o que fazer, o que pedir e o que não fazer em uma tarefa Go.
Artefato da habilidade
Propósito
SKILL.md
Frases de gatilho, entradas, saídas, salvaguardas
references/
Links profundos opcionais para ADRs internos ou runbooks
examples/
Prompts de invocação que passaram por revisão
Habilidades não são tutoriais de recursos - são contratos operacionais para desenvolvimento assistido
Habilidades devem ser fixadas em Go - agentes alucinam roteamento pré-1.22 sem contexto de versão explícito
Uma habilidade = um domínio de decisão (revisão de concorrência, auditoria de módulo, design de API, RBAC de operador)
Cada habilidade Go deve começar com o mesmo esqueleto:
# Habilidade de Revisão de Design de API Go## O que esta habilidade fazRevisa handlers net/http para contexto, erros e códigos de status.## Quando invocar- Antes de mesclar alterações de handler- Ao criar um novo pacote REST- Quando o agente cria cadeias de middleware## Entradas (obrigatório)- go.mod, pacotes afetados, ADR de tratamento de erros da equipe- Escolha do Roteador: stdlib ServeMux vs chi/gin## Saídas- Lista de verificação de revisão com achados de arquivo:linha- Correções sugeridas (sem mesclagem automática)- Verificação: go test ./..., golangci-lint run## Salvaguardas- Nunca remova prazos de contexto em chamadas de saída- Nunca retorne 500 para erros de validação- Nunca desabilite linters sem exceção de ADR## Fixação de PilhaGo 1.26.x · golangci-lint · net/http (ADR-014)## Prompts de exemploVeja §10 abaixo.
Entradas impedem que o agente adivinhe o caminho do módulo ou pule links de ADR
Saídas devem ser verificáveis - comandos, não prosa
Salvaguardas são a seção de maior valor - agentes refatoram excessivamente sem elas
Antes de executar, uma habilidade bem escrita força o agente a coletar:
## Lista de verificação de entradas- [ ] go.mod e go.sum (caminho do módulo, diretiva de versão Go)- [ ] Pacotes afetados (`./internal/api/...`)- [ ] ADRs da equipe para erros, logging, autenticação- [ ] Comandos CI (test, lint, race, vuln)- [ ] Escolha do Framework se não for stdlib (chi, gin, echo, gRPC)- [ ] Contexto do incidente (se triagem): snapshot pprof, caminho do dump de goroutine
Caminho do módulo ausente quebra sugestões de importação e comandos de teste
Links de ADR ausentes produzem tratamento de erro genérico que conflita com a política da equipe
Agentes devem colar os valores coletados de volta para confirmação humana antes de comandos destrutivos
## Salvaguardas (Go 1.26)1. Use `go get` com a política MVS da equipe - nunca `go get -u ./...` às cegas.2. Propague `r.Context()` para todas as I/Os de saída (DB, HTTP, gRPC).3. Retorne erros tipados; mapeie para status HTTP em uma única camada.4. Execute `go test -race` quando a habilidade tocar em goroutines ou estado compartilhado.5. Execute `govulncheck ./...` antes de sugerir mesclagens de dependência.6. Não desabilite regras do golangci-lint sem exceção de ADR.7. Alterações de operador exigem revisão de manifesto RBAC antes da aplicação.
Salvaguardas convertem entusiasmo do agente em disciplina de engenharia
Agentes usam versões de dados de treinamento por padrão. Fixe explicitamente:
## Fixação de Pilha (obrigatório)| Ferramenta | Versão || --- | --- || go | 1.26.x (verificar patch) || golangci-lint | configuração da equipe (verificar na compilação) || Roteador HTTP | stdlib ServeMux (padrões Go 1.22+) |## Específicos do Go 1.26- GC padrão Green Tea - perfil antes de assumir que ajustes de GOGC são necessários.- Modernizadores `go fix` disponíveis - a habilidade não deve lutar contra correções automatizadas.- ServeMux suporta `GET /users/{id}` - prefira stdlib a menos que ADR exija chi/gin.
Re-fixe habilidades a cada bump menor do Go - habilidades desatualizadas são piores do que nenhuma habilidade
Verifique a saída do agente com go test ./... e golangci-lint run
# Portão de unidade e racego test ./...go test -race ./internal/...# Análise estáticago vet ./...golangci-lint run# Segurança (antes de mesclagens de dependência)govulncheck ./...
Verificação
Captura
go test -race
Corridas de dados, encerramento incorreto de goroutine
golangci-lint run
Estilo, errcheck, vazamentos de contexto por configuração da equipe
govulncheck
Vulnerabilidades conhecidas no grafo de módulos
go vet
Erros comuns (printf, tags de struct)
Trate a saída da habilidade como um PR de engenheiro júnior - revise antes de mesclar
Use a habilidade Go API Design Review. Pilha: Go 1.26, stdlib ServeMux.Entradas: Diferença de PR para internal/api/handlers.go anexada.Revise propagação de contexto, mapeamento de erros e códigos de status.Salvaguardas: sem mesclagem automática; saída de lista de verificação com referências de linha.
Auditoria de concorrência:
Use a habilidade Go Concurrency Review.Pacote: ./internal/worker/...Verifique o ciclo de vida da goroutine, regras de fechamento de canal e cancelamento de contexto.Inclua o comando go test -race para os pacotes afetados.
Varredura de segurança de módulo:
Use a habilidade Go Module & Security Audit.Execute govulncheck ./... e resuma CVEs acionáveis.Proponha apenas fixações de go get - o humano aprova antes da mesclagem.
Fluxo de trabalho de profiling:
Use a habilidade Go Performance Profiling.Sintoma: latência p99 dobrou em /api/orders.Entradas: CPU pprof do staging anexado.Forneça etapas de medir-profile-otimizar; sem micro-otimizações prematuras.
Revisão de operador:
Use a habilidade Go Kubernetes Operator Review.Revise a diferença do reconciliador: finalizadores, referências de proprietário, marcadores RBAC.Marque qualquer RBAC de escopo de cluster sem aprovação de ADR.
As Habilidades de Agente são as mesmas que as diretivas go generate?
Não. go generate executa ferramentas em tempo de compilação. Habilidades de Agente instruem assistentes de IA sobre como executar fluxos de trabalho de equipe com segurança. Você pode invocar uma habilidade de revisão para auditar código gerado - camadas diferentes.
As habilidades devem residir no repositório do módulo ou em um registro central?
Repositório do módulo para convenções específicas do projeto go.mod e de handler. Registro central para política de módulo de toda a organização e playbooks de incidentes. Sempre fixe a versão Go em ambos.
Uma única SKILL.md pode cobrir toda a pilha Go?
Evite isso. Divida por domínio de decisão para que as salvaguardas permaneçam afiadas. Uma habilidade monolítica dilui os limites de concorrência e produz atualizações de dependência inseguras.
Com que frequência devemos atualizar as habilidades?
A cada bump menor do Go, a cada alteração de configuração do golangci-lint, e após qualquer postmortem que revele uma salvaguarda perdida. Execute os comandos de verificação na habilidade ao atualizar.
Versões da Pilha: Esta página foi escrita para Go 1.26.x (GC padrão Green Tea, modernizadores go fix - verificar patch na compilação), chi (mais recente - verificar na compilação), gin (mais recente - verificar na compilação), echo (mais recente - verificar na compilação), google.golang.org/grpc (mais recente - verificar na compilação), sigs.k8s.io/controller-runtime (mais recente - verificar na compilação), kubebuilder (mais recente - verificar na compilação), tinygo (mais recente - verificar alvos de placa na compilação), wazero (mais recente - verificar na compilação) e golangci-lint (mais recente - verificar conjunto de linters na compilação). 49454e4f4d5f434e4f5904434556494d43451e1f1f56181a181c1a1d
Revisado por Chris St. John·Última atualização: 19 de jul. de 2026