LLM Wiki — Synaptic Lattice

especificacao-de-issues-para-agentes

Properties1
tagsvibe-coding, specification, founder, pm

Leitura de 4 min

Especificação de Issues para Agentes

Definition

Especificação de issues para agentes é a disciplina de escrever o pedido de trabalho — a issue — de um jeito que um agente de IA (ou um dev júnior) consiga executar sozinho, sem inventar premissas. É o momento mais crítico do funil de desenvolvimento assistido por IA: uma issue mal escrita não é apenas uma issue ruim, é dívida técnica que nasce antes da primeira linha de código, porque o agente vai preencher as lacunas com suposições que raramente coincidem com o que o founder/PM queria.

Este conceito foi sintetizado a partir de um documento-fonte (“Workflow Funnel”) que compila 86 princípios operacionais extraídos de múltiplos documentos-fonte, mas que cita alguns números (percentuais, contagem de PRs de estudos) sem link rastreável — por isso a confidence desta página é medium, não high, até que essas afirmações sejam cruzadas com fonte primária.

Key Points

  • Critério de aceitação é comportamento observável, não desejo vago. O formato Dado/Quando/Então (herdado do BDD) elimina ambiguidade: “Dado que o usuário está na tela de login, quando insere email/senha válidos, então é redirecionado ao dashboard”.
  • Escopo negativo é obrigatório, não opcional. Uma seção “Fora de Escopo” explícita impede o agente de “alucinar escopo” — adicionar telas, campos ou validações que não foram pedidos nem testados.
  • A issue carrega todo o contexto necessário. Se o agente precisa caçar informação em outro lugar (chat, reunião, documento externo), a issue está incompleta. Decisões duráveis vivem em docs/; a conversa de chat não é contexto, é ruído.
  • Minimum Reproducible Input para bugs: o menor conjunto de passos que reproduz a falha. “A tela trava quando clico” não ajuda; “usuário logado, na página de perfil, clica em excluir conta, confirma, sistema mostra erro 500” ajuda.
  • Templates de issue (.github/ISSUE_TEMPLATE/) previnem esquecimentos sistemáticos: objetivo, contexto, dentro/fora do escopo, critérios de aceitação, como verificar, riscos.
  • Definição de “pronto” é observável pelo usuário, não técnica. “Sistema processa sem erro” é insuficiente — o sistema pode processar sem erro e ainda entregar o resultado errado. “Pronto” significa que o usuário consegue fazer o que precisava.
  • Issues pequenas, concluíveis em 1-2 sessões. O teste prático: entregue a issue para alguém que não participou da conversa — se essa pessoa consegue executar sem perguntar nada, o tamanho está certo.
  • A Regra das 48h contra feature creep: ideia nova → anota → espera 48h → revisita. Segundo a fonte, isso filtra a maior parte das ideias que não deveriam ter entrado no backlog.
  • Prompt de tarefa em 5 elementos: objetivo, contexto, restrições, “concluído quando”, e a instrução final “rode os testes, o linter e os checks antes de entregar”.

Implications

Tratar a issue como contrato — não como conversa — desloca o controle de escopo para antes da execução, quando corrigir custa minutos, e não para depois, quando corrigir custa reescrita. Para o founder/PM não-técnico, a competência central não é escrever código: é escrever critérios observáveis e delimitar o que fica de fora. Isso conecta diretamente com triagem-e-priorizacao-de-backlog (o que vira issue primeiro) e com plan-first-com-agentes-de-ia (o agente só propõe um plano depois de ler uma issue bem especificada).

Open Questions

  • A fonte cita “70% das features filtradas pela regra das 48h” sem estudo ou base — vale validar com uso real antes de tratar como referência quantitativa.
  • Falta um exemplo aplicado deste vault (uma issue real do próprio Synaptic Lattice) demonstrando o formato Dado/Quando/Então.

Sources

Visão de gráfico

Backlinks