Como transformar uma issue vaga em um prompt para o Claude Code executar

Fala aí, beleza? "Tá bugado" é a issue mais comum do mundo, e também a que mais faz agente de IA sair refatorando arquivo que ninguém pediu

Quando o Claude Code devolve qualquer coisa, a primeira reação é culpar o modelo

Só que quase sempre o problema não é ele: é o pedido

O board te entrega uma frase de quatro palavras, sem reprodução, sem comportamento esperado, sem alvo, e você repassa isso pro agente esperando mágica

Esse post é sobre a tradução: pegar a demanda vaga que chega e virar um pedido que dá pra executar e conferir

E a parte incômoda: boa parte das perguntas só VOCÊ pode responder, não o agente

O que você precisa antes de acionar o agente

Nada exótico aqui, é o básico do repositório funcionando

• Claude Code instalado e rodando dentro do repositório do projeto, não numa pasta solta
• Um CLAUDE.md no projeto, que é o arquivo que o Claude lê no início de toda conversa pra pegar contexto que ele não consegue inferir só olhando o código: comando de build, estilo de código, regra de fluxo
• A CLI gh do GitHub instalada, porque a própria Anthropic recomenda: o Claude sabe usar ela pra criar issue, abrir pull request e ler comentário
• Acesso de escrita no repo, senão a etapa de PR morre no fim

Não tem CLAUDE.md ainda? Roda /init dentro do Claude Code

Ele analisa o projeto (detecta sistema de build, framework de testes e padrões de código) e gera um CLAUDE.md inicial pra você refinar depois

Que refinar é esse? Tirar o que é óbvio pelo código e deixar o que é decisão de time: "toda migration passa por X", "nunca commitar direto na main", esse tipo de coisa

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

A recomendação é manter curto e legível, não escrever um manual

Se a base é grande e o arquivo tá virando um monstro, dá pra dividir as instruções em vários arquivos dentro do diretório .claude/rules/

Se você ainda tá montando o cenário do zero, vale ver antes o fluxo completo do Claude Code do primeiro projeto até o deploy

Como transformar uma issue vaga em um prompt executável, passo a passo

A sequência abaixo é chata de propósito

A ideia é que você faça o trabalho de decidir ANTES de gastar contexto do agente

1. Leia a issue crua, sem interpretar

gh issue view 123

Lê inteiro, incluindo comentários

Muita informação boa tá enterrada no terceiro comentário, não no corpo

O erro comum deste passo: jogar o link da issue pro agente e mandar "resolve isso", sem nem você ter lido o que tá escrito

2. Responda as 4 perguntas que só você responde

• O que deveria acontecer? (o comportamento correto, descrito em uma frase)
• Como reproduzir? (o caminho exato: quem, onde, com qual dado)
• Onde isso mora? (rota, tela, componente, serviço)
• O que NÃO pode quebrar? (o efeito colateral que você não aceita)

Se você não sabe responder alguma, o agente também não vai saber

Ele vai CHUTAR, e chute vira código

O erro comum deste passo: responder a pergunta 3 por dedução ("acho que é no componente de login") e passar esse achismo como fato pro Claude

3. Defina o critério de pronto verificável

A Anthropic afirma que o Claude tem melhor desempenho quando existe um alvo claro pra iterar contra: um caso de teste, um mock visual ou outro tipo de saída esperada

O motivo é simples: com alvo, ele muda, avalia o resultado e melhora até acertar

Sem alvo, ele muda e para, e quem avalia é você no olhômetro

O erro comum deste passo: escrever "funcionar corretamente" como critério de pronto. Isso não é critério, é torcida

4. Delimite o alvo sem chutar

Se você sabe o arquivo, escreve o arquivo

Se não sabe, escreve o que sabe ("a rota de checkout") e deixa EXPLÍCITO que localizar faz parte da tarefa

É muito melhor dizer "não sei onde mora, procura" do que apontar pro lugar errado com confiança

O erro comum deste passo: mandar o agente pra um caminho errado e depois passar três rodadas desfazendo edição em arquivo inocente

5. Escreva o pedido reescrito, em um bloco só

Junta tudo: comportamento esperado, reprodução, alvo, critério de pronto e a lista do que não pode quebrar

A issue original vira anexo, não vira o pedido

O erro comum deste passo: mandar o pedido fatiado em cinco mensagens no chat. Cada ida e volta come contexto que faria falta na hora de codar

6. Rode em modo de plano antes de qualquer edição

Aperta Shift+Tab até a barra de status mostrar o modo de plano, ou já abre a sessão assim:

claude --permission-mode plan

No modo de plano o Claude explora o código e produz um plano sem editar arquivo

As ferramentas de leitura rodam normal e as edições de arquivo NUNCA são aprovadas automaticamente, mesmo que exista uma regra de permissão que daria match

Ou seja: leitura e proposta, zero edição em disco até você aprovar

O erro comum deste passo: pular direto pro modo que aceita edição porque "é uma correção pequena". Pequena até o momento em que não era 🙂

7. Leia o plano procurando a premissa errada

Essa é a etapa de maior retorno do post inteiro

Você não tá lendo pra aprovar, tá lendo pra caçar a frase onde ele entendeu outra coisa

Corrige ali, ainda no plano, que sai muito mais barato do que corrigir depois de 12 arquivos alterados

O erro comum deste passo: bater o olho, ver que "parece certo" e aprovar. Plano bonito com premissa errada gera código bonito e errado

8. Aprove e deixa codar

Sai do modo de plano aprovando o plano ou apertando Shift+Tab de novo, e aí ele passa a codar com base no que foi combinado

O erro comum deste passo: aprovar e sumir. Alvo verificável do passo 3 existe justamente pra você ter como conferir o resultado sem ler linha por linha

Três issues vagas reescritas (antes e depois)

Padrão de tradução, não fórmula mágica

O que se repete nos três é a troca do adjetivo ("bugado", "feia", "lenta") por comportamento observável mais um critério de pronto

O resto entra conforme o caso: reprodução quando é bug, escopo e fora do escopo quando é ajuste de tela, alvo apontado quando você sabe onde mora

"Tá bugado"

Antes: "o cadastro tá bugado, não vai"

Depois: "Ao enviar o formulário de cadastro com e-mail já existente, a tela fica em estado de carregamento e nada acontece

Esperado: exibir a mensagem de erro de e-mail duplicado e liberar o botão

Reprodução: abrir o formulário, usar um e-mail já cadastrado, enviar

Pronto quando: existe teste cobrindo o caso de e-mail duplicado e ele passa

Não pode quebrar: o cadastro com e-mail novo continua funcionando"

"Melhorar a tela"

Antes: "melhorar a tela de listagem, tá feia"

Depois: "Ajustar a tela de listagem para bater com o mock anexado

Escopo: espaçamento, hierarquia dos títulos e estado de lista vazia

Fora do escopo: qualquer mudança de dados, filtro ou paginação

Pronto quando: o resultado bate com o mock e nenhum comportamento de filtro mudou"

Aqui não tem passo a passo de reprodução, porque não é bug: o mock faz o papel do teste, é o alvo pra iterar contra

"Otimizar isso"

Antes: "otimizar essa consulta, tá lenta"

Depois: "A listagem de pedidos demora demais para responder no ambiente local com a base de exemplo

Esperado: reduzir o tempo dessa resposta e registrar o número antes e depois na descrição do PR

Alvo: a consulta que alimenta a listagem de pedidos

Não pode quebrar: o resultado retornado precisa ser idêntico ao atual, mesma ordem e mesma quantidade"

Repara que eu não escrevi um número mágico de milissegundos

Se você não mediu, não inventa a meta: pede a medição antes e depois, que é verificável de verdade

Como transformar a tradução em um comando reutilizável (.claude/commands/)

Fez a tradução três vezes na mão? Vira comando 😀

Comandos customizados do Claude Code moram em arquivos markdown dentro da pasta .claude/commands/ e aceitam argumento dinâmico pelo placeholder $ARGUMENTS (além dos posicionais $0, $1 e por aí vai)

A própria documentação usa .claude/commands/fix-issue.md como exemplo

1. Crie o arquivo do comando

mkdir -p .claude/commands
touch .claude/commands/fix-issue.md

2. Escreva o frontmatter e o roteiro dentro dele

O arquivo de comando suporta os campos allowed-tools, argument-hint e description

---
allowed-tools: Bash, Read, Edit
argument-hint: numero da issue
description: Corrige uma issue do GitHub seguindo o roteiro do time
---

Corrija a issue $ARGUMENTS seguindo estes passos:

1. Use `gh issue view` para ler a issue
2. Entenda o problema descrito
3. Procure os arquivos relevantes no repositório
4. Implemente as mudanças necessárias
5. Escreva e rode os testes
6. Garanta que o lint e o type check passam
7. Escreva uma mensagem de commit descritiva
8. Faça push e abra o pull request

Esse roteiro de 8 passos não saiu da minha cabeça: é o fluxo que a Anthropic recomenda pra corrigir issue do GitHub

A sacada é que ele é sempre o mesmo, então não faz sentido redigitar toda vez

O erro comum deste passo: transformar o comando num textão

O arquivo é lido junto com o resto, então quanto mais gordo, mais contexto ele come antes mesmo do trabalho começar

3. Chame passando o número da issue

/fix-issue 123

E se você esquecer de colocar o $ARGUMENTS dentro do arquivo? Não quebra

O Claude Code anexa ARGUMENTS: <sua entrada> ao final do conteúdo, então ele ainda enxerga o que foi digitado

É um fallback, não uma desculpa pra não usar o placeholder: com $ARGUMENTS você escolhe ONDE o argumento entra no texto

4. Empilhe comandos quando fizer sentido

Dá pra colocar mais de um comando no início da mesma mensagem, e o texto final é passado como $ARGUMENTS pra cada um deles

O exemplo da doc é exatamente esse:

/write-tests /fix-issue 123

Os dois comandos são carregados e o 123 chega nos dois

Quando a issue vira trabalho do Claude direto no GitHub

Até aqui a tradução acontece no seu terminal

Dá pra mover ela pro repositório, e aí a coisa muda de figura: a issue bem escrita passa a ser o prompt LITERAL, porque é o texto dela que o agente vai receber

Motivo a mais pra escrever direito, né? 😛

O caminho rápido de configuração é rodar /install-github-app dentro do Claude Code no terminal

Ele conduz a configuração do GitHub App e das secrets necessárias pra usar o Claude Code no GitHub

A alternativa é instalar o Claude GitHub App manualmente no repositório

As permissões do GitHub App são três, todas em leitura e escrita:

Pra autenticação existem duas opções: ANTHROPIC_API_KEY (chave da Claude Console) ou CLAUDE_CODE_OAUTH_TOKEN, que é um token OAuth pros planos Pro, Max, Team e Enterprise

Esse token você gera localmente:

claude setup-token

Com tudo no lugar, o gatilho: no modo interativo da Claude Code Action, quando o workflow não passa um prompt, o Claude espera a frase de gatilho padrão @claude

Ela vale em comentário de issue, em comentário de pull request, em review de PR e também no corpo e no título de uma issue recém-aberta

O gatilho é configurável, mas o padrão é esse

Ou seja: alguém abre uma issue já traduzida no formato do post e marca o @claude no corpo

Se a issue for a frase de quatro palavras de sempre, adivinha o que chega no PR

Por que o pedido vago custa caro (e como prevenir)

Sintoma: o agente sai refatorando o que ninguém pediu, a conversa vira ida e volta longa e, lá pro fim da sessão, as respostas pioram visivelmente

Aquela sensação de "ele tava indo bem e do nada ficou burro"

Causa: a Anthropic afirma que a maioria das boas práticas do Claude Code decorre de uma restrição só, a janela de contexto

Ela enche rápido, e o desempenho degrada conforme ela enche

Pedido vago é justamente a máquina de encher contexto: cada rodada de "não era isso" empilha texto, e o texto empilhado é o mesmo que vai faltar depois

Prevenção, em três frentes:

• Contexto persistente no CLAUDE.md, não repetido no chat toda sessão. Se você digita a mesma explicação três vezes por semana, ela é arquivo, não mensagem. E se o seu contexto de projeto vive espalhado em notas, dá pra ligar um segundo cérebro no Obsidian no fluxo
• Escopo estreito, com o "fora do escopo" escrito explicitamente. É a linha que impede o refactor não solicitado
• Plan mode antes de escrever, sempre que o pedido tocar mais de um arquivo

E os outros modos de permissão?

O modo de plano não é o único, e cada um tem seu lugar

O dontAsk é o mais interessante pra quem roda em pipeline: em vez de aprovar tudo pra não travar, ele nega o que não foi explicitamente liberado

Dá pra deixar rodando sem ninguém no volante e sem entregar a chave da casa

Conclusão

Escrever a issue direito é trabalho de quem PEDE, não do agente

O Claude Code lê o que você escreveu, não o que você quis dizer, e nenhum modelo adivinha o que não pode quebrar no seu sistema

O caminho é sempre o mesmo: ler a issue crua, responder as quatro perguntas (o que deveria acontecer, como reproduzir, onde mora, o que não pode quebrar), fixar um critério de pronto verificável, rodar em modo de plano e caçar a premissa errada antes de aprovar qualquer edição

Quando a tradução estabilizar, ela vira arquivo em .claude/commands/ e para de custar seu tempo

Próximo passo prático pra hoje: abre o board, pega a issue MAIS vaga que tiver lá, responde as quatro perguntas num bloco de texto e roda em plan mode antes de deixar ele encostar em qualquer arquivo

Se o plano voltar com uma premissa errada, você acabou de economizar uma tarde inteira

até o próximo post!