Melhores Práticas de Habilidades de Agente
Um resumo condensado das 25 melhores práticas mais importantes extraídas de cada página desta seção.
//
Busque em todas as páginas da documentação
Um resumo condensado das 25 melhores práticas mais importantes extraídas de cada página desta seção.
Habilidades são playbooks, não tutoriais: Arquivos SKILL.md dizem aos agentes como executar - Noções Básicas de Habilidades de Agente define a estrutura; Noções Básicas de net/http ensina conceitos.
Fixar a stack em cada habilidade: Go 1.26.x, configuração da equipe golangci-lint, frameworks (chi, gin, gRPC-Go, controller-runtime, TinyGo, wazero) - habilidades não fixadas alucinam APIs depreciadas.
Uma habilidade por domínio de decisão: Revisão de concorrência, auditoria de módulos, design de API, profiling, testes, operadores, WASM - nunca uma mega-habilidade.
Declarar entradas antes de agir: go.mod, pacotes afetados, links de ADR, comandos de CI - agentes adivinham sem elas.
Saídas devem ser verificáveis: Comandos e checklists, não resumos em prosa - rejeitar execuções de habilidades que omitem go test ./....
Guardrails são a seção de maior valor: Deadlines de contexto, mapeamento de erros, política de go get, RBAC de operador - veja Habilidade de Revisão de Design de API Go.
Invocar habilidades em pontos de decisão: Revisão pré-merge, varredura de CVE, profiling de incidentes - não para ler documentação introdutória.
Documentação humana permanece fonte da verdade: Habilidades linkam para Testes Orientados por Tabela, documentação do govulncheck, Padrões de Reconciliador - não duplicar.
Executar go test -race quando a concorrência for tocada: Gate obrigatório na saída da Habilidade de Revisão de Concorrência Go.
Executar govulncheck ./... antes de merges de dependência: A Habilidade de Auditoria de Módulos e Segurança Go orquestra o mesmo gate que o CI de segurança.
Sem go get -u ./... cego: Pins cirúrgicos com revisão de changelog e aprovação humana.
Propagar r.Context() em handlers: Falta de deadlines é um achado bloqueador na habilidade de revisão de API.
Mapear erros em uma camada: Handlers ou pacote apierr - não ambos com códigos de status conflitantes.
Fazer profiling antes de otimizar: A Habilidade de Profiling de Performance Go bloqueia sync.Pool especulativo sem pprof.
Subtestes orientados por tabela a partir do AC: A Habilidade de Teste e Benchmark Go mapeia cada item para t.Run.
Fuzz apenas parsers puros: Sem rede/DB em alvos de fuzz sem configuração de integração dedicada.
Reconcile do Operador deve ser idempotente: Sem panics; finalizadores precisam de caminho de remoção - Habilidade de Revisão de Operador Kubernetes Go.
Privilégio mínimo de RBAC: Sinalizar verbos * e marcadores de cluster-admin antes do merge.
WASI vs WASM de navegador: Nunca syscall/js em builds wasip1 - Habilidade de Revisão de Build WASM & TinyGo.
Orçamento de tamanho em artefatos WASM: Medir com wasm-objdump / ls -la antes de aprovar novas dependências.
Alinhar habilidades com ADRs: Linkar Escrevendo ADRs para Decisões de Arquitetura Go na seção Referências.
Espelhar comandos de CI em habilidades: Se a habilidade diz golangci-lint run, o CI deve executá-lo - engenheiros ignoram gates incompatíveis.
Tratar saída de habilidade como um PR júnior: Revisão humana antes do merge; mesma barra que rascunhos de código assistidos.
Versionar habilidades no repositório: Commit .cursor/skills/ ou registro com nota semver no changelog quando os guardrails mudarem.
Atualizar habilidades após postmortems: Cada guardrail perdido se torna um novo item - reexecutar comandos de verificação na atualização.
Repositório do módulo .cursor/skills/ para convenções específicas do projeto; registro da organização para auditoria compartilhada e playbooks de incidentes. Sempre fixe a versão do Go.
A habilidade pode rascunhar comandos go get - o humano aprova antes do merge. Guardrails bloqueiam merge automático em PRs de dependência.
Habilidades referenciam o mesmo conjunto de linters que o CI impõe. Não sugira //nolint sem um caminho de exceção de ADR.
Não. Habilidades aceleram checklists; revisores humanos são responsáveis pela autoridade de merge e julgamento de arquitetura.
Após um bump menor do Go, mudança na configuração do linter, atualização de ADR de framework ou item de ação de postmortem. Reexecute go test e govulncheck na seção de verificação ao atualizar.
Versões da Stack: Esta página foi escrita para Go 1.26.x (padrão Green Tea GC, go fix modernizers - verificar patch na compilação), chi (latest - verificar na compilação), gin (latest - verificar na compilação), echo (latest - verificar na compilação), google.golang.org/grpc (latest - verificar na compilação), sigs.k8s.io/controller-runtime (latest - verificar na compilação), kubebuilder (latest - verificar na compilação), tinygo (latest - verificar alvos de placa na compilação), wazero (latest - verificar na compilação), e golangci-lint (latest - verificar conjunto de linters na compilação).
Revisado por Chris St. John·Última atualização: 16 de jul. de 2026