Go Concurrency: goroutines com saída, cancelamento e limites

ANÁLISE EDITORIAL

Concorrência em Go pode deixar um serviço mais responsivo, mas também pode esconder goroutines sem saída, canais fechados pelo lado errado, corridas de dados e trabalho ilimitado. A Skill Go Concurrency transforma esses riscos em perguntas verificáveis: quem é o dono da goroutine, como ela termina, quem fecha cada canal, como o erro cancela tarefas irmãs e qual limite protege CPU, memória e serviços externos.

O material é um guia para agentes que escrevem, revisam ou auditam código Go. Ele não executa monitoramento contínuo, não prova ausência de vazamentos e não substitui testes, revisão humana ou observabilidade em produção. Seu valor está em organizar decisões antes que a concorrência vire um detalhe impossível de rastrear.

Imagem: Ilustração editorial exclusiva do Bastidores da IA sobre fluxos concorrentes atravessando canais, um limite de trabalho e um sinal de cancelamento. Não é captura de tela, interface real, logotipo oficial, benchmark nem prova de execução.

O que esta Skill faz de verdade

O SKILL.md fixado no commit auditado apresenta três modos. No modo de escrita, orienta a implementação de goroutines, canais, primitivas de sincronização, workers e pipelines. No modo de revisão, concentra a análise no diff. No modo de auditoria, permite dividir uma base grande em até cinco frentes, desde que o usuário tenha aprovado o uso de subagentes.

A regra central é exigir uma saída previsível para cada goroutine. A Skill relaciona contexto, canal de encerramento, sync.WaitGroup e errgroup a responsabilidades diferentes. Também compara canal, mutex, atômicos, sync.Map, sync.Once, singleflight e limites de concorrência. Os exemplos detalhados estão nas referências de canais e select, pipelines e worker pools e primitivas de sincronização.

É uma referência de engenharia, não um linter. Ela pode sugerir mudanças e, se o agente tiver escrita e shell autorizados, editar arquivos e executar comandos. A confirmação de correção depende do programa real, da versão do Go, dos testes e do comportamento em carga.

Para quem serve

Serve para pessoas e equipes que mantêm APIs, workers, consumidores de filas, pipelines, CLIs, serviços de rede e bibliotecas em Go. É útil quando uma revisão envolve go func, compartilhamento de mapas, fan-out e fan-in, cancelamento, timeouts, deduplicação de chamadas ou dúvidas entre canais e mutexes.

Não é a melhor ferramenta para um erro isolado de nil, aliasing de slices ou overflow sem relação com concorrência. O próprio projeto encaminha esses casos para skills de segurança. Também não é um depurador de um processo já travado ou em corrida. Para esse cenário, a referência aponta uma skill separada de troubleshooting. Essa separação reduz respostas genéricas e evita aplicar concorrência a um problema que deveria continuar síncrono.

Compatibilidade e pré-requisitos

A compatibilidade declarada cobre Claude Code, Codex e ambientes semelhantes que carreguem Agent Skills em Markdown. O projeto analisado precisa usar Go, e o host deve fornecer o binário go. O cabeçalho autoriza leitura, edição, escrita, busca e comandos restritos a go, golangci-lint e git, além de perguntas ao usuário e agentes auxiliares.

A Skill cita recursos de várias versões. Atômicos tipados exigem Go 1.19 ou superior, funções como OnceValue chegaram no Go 1.21 e WaitGroup.Go no Go 1.25. O perfil goroutineleak é apresentado como disponível sem flag no Go 1.27. Consulte as notas oficiais do Go 1.27 e a documentação de WaitGroup.Go antes de aceitar uma sugestão incompatível com o go.mod.

O uso completo também pode depender de golangci-lint, go.uber.org/goleak ou golang.org/x/sync. O ZIP do Bastidores não instala essas dependências. Ele entrega somente a Skill, três referências, licença e registro de origem.

Instalação recomendada

O README oficial fixado documenta o Skills CLI. Para instalar apenas este item no escopo do projeto, revise primeiro o repositório e use:

npx skills add https://github.com/samber/cc-skills-golang --skill golang-concurrency

O comando consulta a rede, executa um pacote via npx e grava arquivos de skill. Confirme a origem do pacote, a pasta de destino e o diff. Quem preferir o caminho documentado para Codex pode clonar o repositório em ~/.agents/skills/cc-skills-golang, mas isso baixa o catálogo completo. Como o README avisa que as skills são unidades atômicas com referências cruzadas, instalar somente uma oferece uma visão parcial das convenções.

Para máxima reprodutibilidade, fixe o commit 22c58a55a0a799b901aa251172923180bad9e010 em uma cópia revisada. Não faça atualização automática em um projeto sensível. Compare a nova versão com a aprovada e revalide permissões.

Configuração antes do primeiro uso

Defina o modo: escrita, revisão ou auditoria. Em revisão, entregue um diff delimitado. Em auditoria, informe repositório, módulos, diretórios excluídos e se o uso de até cinco subagentes está autorizado. Em escrita, descreva requisito funcional, limites de carga, política de timeout, propagação de erro e ambiente de teste.

Confira go.mod, versão do compilador e dependências existentes. Uma recomendação moderna pode falhar em uma base presa a Go anterior. Registre ainda quais comandos podem rodar. O cabeçalho autoriza git, mas isso não significa autorização para commit, push, troca de branch ou descarte de alterações. Mantenha o repositório limpo ou preserve mudanças não relacionadas.

Classifique os dados. Testes de integração podem abrir rede, acessar banco, filas ou credenciais do ambiente. Use fixtures, serviços descartáveis e segredos fora de prompts e logs. Para produção, comece em leitura e observação. Não permita que uma auditoria altere limites, reinicie serviços ou exponha perfis sem aprovação.

Primeiro uso seguro

Escolha um pacote pequeno e peça revisão sem escrita. Solicite uma tabela com local, risco, evidência e correção proposta. A primeira verificação deve responder: como cada goroutine sai, se o chamador pode cancelar, se existe espera pelo encerramento, quem possui o canal e se a concorrência é realmente necessária.

Depois, valide manualmente os pontos citados e execute testes locais. O detector de corridas oficial documenta o uso do sinalizador -race:

go test ./...
go test -race ./...

O segundo comando é mais caro e só encontra corridas exercitadas pela execução. Uma passagem limpa não prova que toda sincronização está correta. Se houver benchmark ou teste de carga, rode em ambiente controlado, com limite de duração e sem credenciais de produção. Revise qualquer edição antes de mantê-la.

Como o fluxo deve funcionar

1. Localizar os pontos que iniciam goroutines e identificar o proprietário de cada ciclo de vida.
2. Mapear canais, direção, fechamento, buffer e caminhos de bloqueio.
3. Confirmar cancelamento por contexto nos select de longa duração.
4. Examinar estado compartilhado, seções críticas, I/O sob lock e escolha entre mutex e canal.
5. Limitar fan-out, worker pools e chamadas externas com uma política explícita.
6. Propagar o primeiro erro e cancelar trabalho irmão quando esse for o contrato.
7. Adicionar testes de encerramento, corrida e carga proporcional ao risco.
8. Entregar evidências, incertezas e um diff pequeno para revisão humana.

O artigo oficial sobre pipelines e cancelamento mostra por que produtores precisam parar quando consumidores deixam de ler. Já o pacote errgroup oferece propagação de erro, contexto e limite de concorrência. A escolha deve seguir o contrato, não uma preferência automática por abstrações.

Resultado esperado

Uma revisão útil identifica riscos reproduzíveis, aponta o trecho responsável e propõe a menor mudança segura. Para cada goroutine, o relatório deve explicar entrada, saída, cancelamento e espera. Para cada canal, deve registrar quem envia, quem recebe e quem fecha. Para estado compartilhado, precisa justificar a primitiva e o alcance do lock.

Uma implementação bem-sucedida mantém o comportamento exigido, passa pelos testes relevantes e torna os limites explícitos. Não aceite frases como “agora está livre de leaks” sem teste de encerramento, observação de goroutines e cenário de cancelamento. O perfil oficial de goroutine leaks acrescenta um sinal para produção no Go 1.27, mas continua sendo evidência complementar, não certificado de correção.

Permissões, privacidade e riscos

A Skill pode ler todos os arquivos Go alcançados pelo escopo, editar código e executar compilação, testes, linter e comandos Git. Isso pode revelar nomes internos, regras de negócio, endpoints e mensagens de erro ao provedor do agente. Restrinja o projeto e evite bases de clientes sem autorização e política de retenção adequadas.

Comandos de teste podem consumir CPU e memória, iniciar containers, abrir rede ou modificar bancos se a suíte não estiver isolada. golangci-lint pode baixar componentes, e dependências Go podem ser consultadas na rede. Um agente auxiliar recebe parte do código e do contexto. Ative paralelismo apenas quando a base justificar e o usuário tiver concordado.

Perfis pprof também merecem cuidado. Um endpoint exposto pode revelar pilhas, caminhos, nomes de funções e comportamento interno. Colete somente no ambiente autorizado, proteja o acesso e remova artefatos sensíveis após a análise. Nunca publique um perfil real junto com o ZIP documental.

Erros comuns

• Criar goroutine sem dono: toda execução precisa de saída, cancelamento e forma de espera.
• Fechar no receptor: o remetente normalmente possui e fecha o canal.
• Usar buffer para esconder bloqueio: capacidade maior adia pressão sem corrigir o contrato.
• Esquecer ctx.Done(): loops e selects podem sobreviver ao chamador.
• Disparar sem limite: fan-out ilimitado esgota processo e serviços dependentes.
• Executar I/O sob mutex: a seção crítica fica imprevisível e amplia contenção.
• Compartilhar ponteiro por canal: a mutação volta a ser estado compartilhado invisível.
• Chamar wg.Add tarde: versões antigas exigem Add antes de iniciar a goroutine.
• Usar API de versão nova: confira o go.mod antes de aceitar WaitGroup.Go.
• Tratar -race como prova total: ele observa apenas caminhos exercitados.
• Rodar auditoria paralela sem consentimento: subagentes ampliam processamento e exposição.
• Confundir o ZIP com ferramenta executável: o arquivo local contém somente documentação.

Versão, licença e origem verificadas

Em 06/09/2026, o repositório samber/cc-skills-golang estava público, não arquivado, declarava licença MIT e registrava 3.182 estrelas. A curadoria fixou o HEAD 22c58a55a0a799b901aa251172923180bad9e010. O último commit específico do SKILL.md era 8f8e2feb661bfecbba2b7a3f03a5fbad573073f9.

A versão declarada no cabeçalho é 1.2.1. A licença MIT permite a redistribuição com preservação do aviso. Repositório, commit, versão e contagem de estrelas são campos separados porque mudam em ritmos diferentes.

O pacote local contém seis arquivos textuais: SKILL.md, três referências Markdown, LICENSE e ORIGEM.md. Não contém as demais skills do repositório, scripts, binários, módulos Go, dependências, testes, perfis, código do usuário, credenciais ou segredos. O ZIP tem 14.110 bytes e SHA-256 80fc09eb9379eabd1713346b0ee8cffcbd7ea9a9cc18f477bb8208823ac14be7.

Checklist antes de automatizar

• Fixe o commit, confirme a licença e leia os seis arquivos do pacote.
• Escolha escrita, revisão ou auditoria e delimite diretórios e módulos.
• Confira a versão do Go e as APIs aceitas pelo projeto.
• Mantenha alterações do usuário e trabalhe com diff pequeno.
• Autorize separadamente rede, dependências, testes de integração e subagentes.
• Valide saída, cancelamento, espera, propriedade de canais e limites.
• Rode testes e detector de corrida em ambiente isolado e proporcional ao risco.
• Proteja código, perfis, logs, endpoints e dados de clientes.
• Não faça commit, push ou mudança em produção por inferência.
• Registre evidências e limitações antes de afirmar correção.

O download do Bastidores serve para auditoria documental. Compare-o com a pasta oficial fixada. Se optar pelo catálogo completo, revise também as referências cruzadas e habilite somente o que o projeto precisa.

Fontes primárias

• Repositório oficial cc-skills-golang
• Pasta Go Concurrency no commit auditado
• SKILL.md oficial
• Canais e select
• Pipelines e worker pools
• Primitivas de sincronização
• Instalação e compatibilidade
• Licença MIT
• Go Concurrency Patterns: Pipelines
• Go Concurrency Patterns: Context
• Detector de corridas
• Pacote sync
• Pacote errgroup
• Perfil de goroutine leaks