Prompt em produção precisa de review como código · Centelha

O problema não é colocar um agente para rodar dentro do GitHub Actions.

O problema é deixar um arquivo em Markdown decidir trabalho, permissão, custo e saída esperada com menos cuidado do que você daria a um workflow de deploy.

Quando o agente está no chat, ainda existe uma sensação de improviso. Você pede alguma coisa, lê a resposta, copia um trecho, testa localmente e decide se aquilo entra ou não no código.

Mas quando o agente vira workflow, a conversa muda. Ele pode responder a evento, abrir branch, comentar em PR, mexer em issue, rodar comando e consumir orçamento da organização. A partir daí, o prompt deixa de ser "texto de apoio".

Ele vira configuração operacional.

E configuração operacional precisa de review.

O que mudou de verdade

A parte interessante dos workflows agênticos no GitHub vai além de "agora tem IA no CI". Isso seria uma leitura meio rasa.

O ponto mais importante é que o agente começa a herdar o trilho que o time já usa para software: arquivo versionado, runner, política, sandbox, permissão explícita e histórico no repositório.

Isso é bom. Muito melhor do que um PAT pessoal esquecido em alguma automação obscura.

Só que também tira uma desculpa da mesa. Se o agente está definido em um arquivo do repo, dispara por um evento do repo e age com permissão do repo, então aquele arquivo precisa ser lido como parte do sistema.

Não basta perguntar se o prompt está bem escrito.

A pergunta certa é: esse workflow deveria existir desse jeito?

Prompt também tem superfície de risco

Dev costuma revisar código com alguns reflexos bem treinados.

Você olha diff, dependência nova, permissão, migração, teste, impacto em produção. Se aparece um write-all estranho no GitHub Actions, alguém levanta a mão. Se um script de deploy roda em pull_request sem motivo, o review fica mais cuidadoso.

Com prompt, muita gente ainda relaxa.

Parece texto. Parece documentação. Parece uma instrução que dá para ajustar depois.

Só que, em um workflow agêntico, o texto pode definir:

quando o agente roda;
qual tarefa ele entende como concluída;
que arquivos ele pode alterar;
que comando ele deve executar;
qual evidência ele precisa anexar;
quando ele deve pedir validação humana;
que tipo de comentário ele pode fazer em um PR.

Isso não é texto bonito para enfeitar automação. É comportamento de sistema.

Um prompt ruim pode ser tão perigoso quanto um script ruim. Às vezes mais perigoso, porque parece flexível demais para quebrar.

Credencial não é detalhe de implementação

A troca de PAT pessoal por GITHUB_TOKEN em workflows agênticos é uma boa direção, mas não resolve o problema sozinha.

Ela só coloca a pergunta no lugar certo.

Esse agente precisa mesmo comentar em PR? Precisa abrir branch? Precisa escrever em issue? Precisa acesso de leitura ao repo inteiro? Precisa rodar em todo push ou só quando alguém marca explicitamente?

Esse tipo de decisão não deveria morar escondido no final do arquivo. É desenho do sistema.

Um exemplo simples:

permissions:
  contents: read
  pull-requests: write
  issues: write

Se o objetivo é apenas resumir um PR, talvez issues: write já seja permissão demais. Se o objetivo é abrir uma correção automática, talvez o evento de disparo precise ser manual. Se o agente consome crédito da organização, talvez precise de limite de tempo e regra clara para parar.

O review não deveria olhar só "o agente consegue fazer?". Deveria olhar "o agente consegue fazer apenas o necessário?".

Um checklist pequeno já evita muita confusão

Não acho que todo workflow com agente precise virar comitê.

Se é uma automação pequena, usada por uma pessoa, em um repo sem produção crítica, um review leve pode bastar. O erro é fingir que "leve" significa "ninguém olha".

Antes de aceitar um workflow agêntico, eu passaria por esta lista:

Quem é o dono do workflow?
Qual evento dispara o agente?
Quais permissões ele recebe?
Qual é o limite de tempo, custo ou tentativas?
Em que sandbox ou runner ele executa?
Quais arquivos, issues ou PRs ele pode tocar?
Que evidência ele precisa deixar no final?
Que parte exige validação humana?
Como desfazer a ação se ele errar?

Isso parece básico porque é básico mesmo. E é exatamente por isso que precisa estar visível.

O agente pode até ajudar a preencher parte desse checklist no próprio PR:

## Evidência do workflow agêntico

- Evento: manual, via workflow_dispatch.
- Permissões: leitura de conteúdo e comentário em PR.
- Limite: 15 minutos por execução.
- Saída esperada: resumo técnico e lista de arquivos citados.
- Validação humana: nenhum commit é feito sem aprovação.
- Rollback: remover o comentário ou reexecutar com contexto corrigido.

Isso não garante que o workflow é bom. Mas já força uma conversa melhor do que "parece útil, vamos testar".

Contexto ruim vira automação ruim

Tem outra coisa que aparece rápido quando agente sai do chat e entra no fluxo do time: dívida de contexto.

Um agente consegue produzir bastante texto, código e comentário. Mas se ele não entende contrato de API, ownership, padrão interno, dependência quebrada, histórico de decisão e limite de produto, ele só automatiza confusão em alta velocidade.

É aqui que muita adoção de IA tropeça.

O time coloca agente para trabalhar antes de deixar claro o que é trabalho aceitável. O prompt pede "corrija o problema", mas o repo não diz qual serviço é dono daquele fluxo. O agente comenta no PR, mas não sabe que aquela API tem compatibilidade pública. Ele sugere refactor, mas ignora que a biblioteca está presa por causa de um cliente antigo.

Depois alguém fala que o agente "alucinou". Às vezes alucinou mesmo. Mas, em muitos casos, o sistema ao redor também não explicou o suficiente.

Review de prompt em produção precisa olhar esse contexto:

o workflow aponta para docs ou contratos relevantes?
o agente sabe quais áreas são proibidas?
existe exemplo de saída boa?
existe critério para parar?
existe caminho para pedir ajuda em vez de inventar?

Sem isso, você não tem automação. Tem um estagiário muito rápido, sem onboarding, com acesso ao repositório.

Subagente não remove responsabilidade

O assunto fica ainda mais sensível quando entram subagentes, harnesses e execuções paralelas.

Dividir uma tarefa grande em partes menores pode fazer sentido. Um agente olha testes, outro olha docs, outro cria plano, outro aplica patch. Legal.

Mas paralelismo sem contrato só espalha o problema.

Se cada subagente recebe uma instrução vaga, escreve em lugares diferentes e devolve saída sem evidência, o agente principal vira apenas um agregador de incerteza. Parece arquitetura sofisticada, mas o review humano fica pior.

O mínimo aceitável é cada etapa deixar um rastro verificável:

entrada recebida;
escopo permitido;
arquivos tocados;
comandos executados;
decisão tomada;
pendências para humano.

Quanto mais agentes você coloca no fluxo, menos dá para depender de confiança implícita. O sistema precisa mostrar como chegou na resposta.

O tradeoff honesto

Dá para exagerar na governança? Claro.

Se toda automação interna precisar de reunião, formulário e aprovação assíncrona, ninguém vai usar. O time volta para o chat solto, copia e cola a saída, e finge que está mais seguro.

A régua precisa acompanhar o risco.

Um workflow que só resume uma issue pode ter review simples. Um workflow que comenta em PR já pede mais cuidado. Um workflow que abre branch, altera arquivo ou roda comando com credencial da organização precisa de dono, limite e rollback claros.

Não é medo de agente. É engenharia normal.

A gente já faz isso com deploy, banco, secrets, feature flag e job de background. O prompt só entrou nessa família porque agora ele também decide comportamento.

O melhor prompt não é o mais longo

O time que vai mais longe com agente provavelmente não é o que escreve o prompt mais detalhado.

É o que sabe responder três perguntas sem enrolar:

Onde esse agente pode agir?
Como ele prova que agiu direito?
Quem segura a decisão final?

Se essas respostas estão claras, o agente vira uma ferramenta de fluxo. Se não estão, ele vira uma fonte elegante de ruído operacional.

Prompt em produção precisa de review como código porque, na prática, ele já está fazendo trabalho de código: define comportamento, toca permissão, consome recurso e muda o estado do projeto.

Tratar isso como texto solto é confortável por pouco tempo.

Até o dia em que a automação funciona exatamente como foi instruída, mas não como o time precisava.

Source notes

GitHub Agentic Workflows em public preview: agentes definidos como workflows versionados e executados dentro do trilho do GitHub Actions.
Atualização de credencial para GITHUB_TOKEN: reforça a necessidade de revisar permissões explícitas e faturamento organizacional.
VS Code Agents window: mostra que agentes estão virando sessões de operação também no editor, não só no CI.
Postman e "context debt": apoio para tratar contexto como pré-requisito de automação útil.
Recursive Agent Harnesses: referência de apoio para pensar subagentes como arquitetura verificável, não como truque de prompt.