Santiago.

🔒 Um cadeado para o vibe coding: um revisor de PRs com Claude

3 de outubro de 2026 · 8 min de leitura

Estou trabalhando em um projeto e aconteceu algo de que gostei muito: o Claude, rodando dentro do GitHub Actions, revisou e corrigiu meus pull requests (PRs). Achei muito bom e muito eficiente, tanto que quis entender como funciona para contar aqui. Para mim é como um cadeado 🔒 para o vibe coding: deixa você avançar rápido, mas garante que nada escape.

🧠 O problema: o agente perde contexto

Quando você programa com IA, o que já se conhece como vibe coding (dizer à IA o que você quer e deixá-la escrever o código, muitas vezes aceitando-o sem ler a fundo), o agente com quem você está programando às vezes se perde em detalhes. Por mais que a gente tente sempre dar contexto a ele, conforme a sessão se alonga ele vai perdendo, e algumas coisas escapam: uma regra de negócio, um caso de borda, um arquivo que também dependia do que mudou.

O revisor funciona diferente. Ele começa toda vez com a cabeça limpa, com uma única missão: revisar aquele pull request. Não carrega horas de conversa, e por isso, na minha experiência, é muito mais eficiente para encontrar o que o agente de programação deixou passar.

🤖 O que é?

O Claude Code GitHub Actions é uma Action do GitHub (anthropics/claude-code-action) que executa o Claude Code dentro dos workflows do seu repositório. Funciona de duas maneiras:

  • Interativo: você o menciona com @claude em um comentário de PR ou de issue e ele responde ali mesmo.
  • Automático: você dá a ele um prompt e ele roda sozinho quando algo acontece no repositório, por exemplo toda vez que um pull request é aberto.

Para um revisor, nos interessa o segundo.

Atenção a uma diferença: o revisor que montamos mais abaixo comenta, não modifica código. Se você também quer que o Claude faça a correção, mencione-o com @claude, e para que ele possa enviar mudanças o workflow precisa de permissões de escrita (contents: write e pull-requests: write).

⚙️ Como implementar

⚡ O caminho rápido. Abra o claude dentro do seu repositório e execute /install-github-app. Ele instala o app do GitHub, guarda o segredo de autenticação e deixa pronto um pull request com os workflows. Você precisa ser administrador do repositório, ter o GitHub CLI autenticado (gh auth login) e o repositório precisa estar no github.com.

🛠️ O caminho manual. São três passos:

  1. Instalar o app do Claude no seu repositório.
  2. Guardar um segredo: ANTHROPIC_API_KEY (chave de API) ou CLAUDE_CODE_OAUTH_TOKEN (se você usa uma assinatura).
  3. Criar um workflow em .github/workflows/.

Este workflow revisa cada pull request quando é aberto ou atualizado, usando o plugin de revisão oficial:

name: Code Review
on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          plugin_marketplaces: "https://github.com/anthropics/claude-code.git"
          plugins: "code-review@claude-code-plugins"
          prompt: "/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
          claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'

O que importa em cada parte:

  • on: pull_request: dispara ao abrir, atualizar, reabrir ou marcar um PR como pronto.
  • plugins e prompt: instalam o plugin code-review e executam sua revisão sobre esse PR.
  • --comment: o Claude publica a revisão no próprio PR, com um comentário em linha para cada problema, ou um comentário de resumo se não encontrar nada. Sem essa opção, você só veria o resultado no log da execução.
  • claude_args: mantenha esta linha, porque é ela que habilita os comentários em linha.
  • O Claude ignora PRs em rascunho, fechados, triviais e os que já têm um comentário dele.

🎯 O que mais importa: o prompt do revisor

Aqui está a diferença entre um revisor que só faz barulho e um que realmente ajuda. A qualidade do revisor depende em grande parte do prompt que você programa para ele. O plugin oficial já vem com o seu, mas se você quer um revisor que conheça o seu negócio e a sua arquitetura, escreva o seu (ou um skill). Pela minha experiência, estas são as coisas que é preciso dar a ele:

  • 💼 Contexto do negócio. O que o produto faz e para quem, quais são os fluxos críticos e as regras que não podem ser quebradas: como os valores são calculados, quem pode ver ou alterar o quê, quais estados são válidos. Sem isso, o revisor só vê código; com isso, ele vê se o código faz o que o negócio precisa.
  • 🏗️ Contexto da arquitetura. As camadas e suas responsabilidades, as convenções, os padrões que devem ser respeitados e o que é proibido, por exemplo colocar lógica de negócio nos controllers. Se você tem documentos de arquitetura ou decisões registradas, aponte-os para ele.
  • 📋 O que revisar e em que ordem. Primeiro o que mais custa: erros de lógica e casos de borda, segurança, integridade dos dados, risco de quebrar outras partes e testes que faltam.
  • 🚫 O que ignorar. O formato e o estilo que o linter já valida, e as preferências pessoais. Senão, ele enche o PR de ruído.
  • 🔍 Que olhe além do diff. Peça que ele verifique quem usa o que mudou, não só as linhas modificadas. Muitos erros estão no que o diff não mostra.
  • 💬 Como deve responder. Que classifique cada achado (bloqueante, importante ou sugestão), indique arquivo e linha, o impacto e a correção proposta. Que diga quando tem uma dúvida em vez de inventar e, se tudo estiver bem, diga isso em uma só frase.

Um modelo para começar:

Você é o revisor sênior deste repositório. Revise o pull request atual.

Contexto do negócio:
- O que o produto faz e para quem.
- Regras críticas: como os valores são calculados, quem pode ver ou
  alterar o quê, estados válidos de cada processo.

Contexto da arquitetura:
- Camadas e responsabilidades (API, serviços, acesso a dados).
- Convenções e padrões que devem ser respeitados.
- O que é proibido (por exemplo, lógica de negócio nos controllers).

O que revisar, nesta ordem:
1. Erros de lógica e casos de borda.
2. Segurança e tratamento de dados sensíveis.
3. Integridade dos dados e transações.
4. Risco de quebrar outras partes: verifique quem usa o que mudou,
   não só o diff.
5. Testes que faltam.

O que ignorar: formato e estilo que o linter já valida, e preferências
pessoais.

Como responder:
- Classifique cada achado como bloqueante, importante ou sugestão.
- Indique arquivo e linha, explique o impacto e proponha a correção.
- Se não tiver certeza, diga como dúvida; não invente.
- Se tudo estiver bem, diga em uma só frase.

Onde colocá-lo, conforme o seu jeito de trabalhar:

  • No prompt do workflow. Com um texto próprio, o Claude não tem acesso ao terminal nem à API do GitHub até que você dê as ferramentas de que ele precisa com --allowedTools em claude_args. Diga a ele também qual PR revisar: o número vem em ${{ github.event.pull_request.number }}.
  • Em um skill do repositório. Você o guarda em .claude/skills/, faz o checkout antes e passa /nome-do-skill como prompt. Assim o prompt fica versionado e é revisado como qualquer outro código.
  • No CLAUDE.md. É o lugar para o estilo de código, os critérios de revisão e as regras do projeto. O Claude o lê em cada execução. Mantenha-o curto, porque ele é lido toda vez.

E não espere que fique perfeito de primeira. Veja quais falsos positivos ele dá, o que escapa e ajuste o prompt. É um trabalho iterativo, como afinar qualquer outra ferramenta.

🛡️ Cuidados que não se deve esquecer

  • 🔑 Segredos: nunca envie chaves ao repositório; guarde-as como secrets do GitHub.
  • 🔐 Permissões mínimas: dê ao workflow apenas o que ele precisa. No exemplo, somente leitura de código, PRs e issues, mais id-token: write, de que a Action precisa para se autenticar. Se você quer que o Claude envie correções, ele precisará de escrita: dê-a apenas ao workflow que a exigir.
  • 💰 Custos: cada execução gasta minutos do GitHub Actions e tokens da API (ou da sua assinatura, se você autentica com um token OAuth). --max-turns, os timeouts e o controle de concorrência ajudam a limitar.
  • 🌐 Repositórios públicos: o GitHub não entrega os segredos a execuções de PRs vindos de forks.
  • 🧑‍💻 Você decide: o revisor não substitui o julgamento humano. Revise os comentários dele e as mudanças do Claude antes de fazer o merge.

Se você não quer manter um workflow, existe também o Code Review, o produto do Claude que revisa cada pull request automaticamente sem que você escreva nenhum.

💡 Minha conclusão

🔒 O vibe coding é poderoso, mas precisa do seu cadeado. Para mim, a IA não tira responsabilidade: ela a divide melhor. Eu escrevo com a ajuda da IA, um revisor com a cabeça limpa e bom contexto revisa, e eu decido. Essa combinação é o que me dá tranquilidade para avançar rápido.

✍️ Por Santiago Perea Restrepo

← Voltar