Simon Willison recolhe descrições de PR geradas por IA: os principais pontos em 1 parágrafo

Você abre um pull request e encontra várias telas de texto: a definição do problema, a estrutura da solução, a lista de arquivos, as verificações e mais algumas explicações. O agente documentou tudo com cuidado. Mas, antes de ler esse relatório, você quer entender uma coisa: o que mudou e por que isso merece sua atenção.

Simon Willison descreveu uma técnica que usa nos seus PRs preparados com Claude Code e Codex. Ele mantém no início uma breve introdução e assume a responsabilidade pelo conteúdo. A descrição completa do agente fica em uma seção expansível. O GitHub permite fazer isso diretamente no Markdown com as tags HTML <details> e <summary>.

Para uma equipe que recebe alterações de agentes de programação com frequência, essa é uma maneira pronta para organizar as descrições. É possível adotá-la por meio de um modelo de PR e de uma instrução para o agente. Ainda assim, uma pessoa precisará ler a breve introdução.

O que deve ficar visível

Willison usa o PR como unidade de trabalho: reúne os commits, aprimora uma funcionalidade, registra decisões e depois faz o merge do resultado pronto. Uma descrição detalhada é útil nesse contexto. O problema surge quando o leitor precisa percorrer todo o material para descobrir a finalidade da alteração.

Na experiência dele, os textos dos agentes podem ser precisos e informativos, mas a própria prolixidade desestimula a leitura. Por isso, o primeiro parágrafo deve apresentar rapidamente o contexto: qual problema o usuário ou desenvolvedor enfrentava e o que agora funciona de outra forma.

Em um dos exemplos apresentados, a página de um registro individual exibia os dados em uma tabela com uma única linha. Quando havia muitos campos, a tabela se estendia bastante para a direita, enquanto o restante da página ficava vazio. Essa explicação dá imediatamente ao revisor o contexto necessário para avaliar a nova visualização. Uma captura de tela ajuda a ver o resultado antes mesmo de examinar o código.

A introdução não precisa ser escrita do zero. Às vezes, Willison aproveita um trecho adequado do texto do agente. O que importa é que uma pessoa o tenha escolhido e considere que ele merece a atenção do leitor.

Como montar a seção expansível

A tag <details> envolve a parte oculta da descrição. Dentro dela, <summary> define o título visível: um clique nele revela o restante do conteúdo. O GitHub oferece suporte a essa estrutura nas descrições de PRs e nos comentários de issues.

Willison inclui o nome do modelo no título da seção e, às vezes, acrescenta o nível de esforço. Isso identifica a origem do relatório detalhado. O relatório é preservado na íntegra: o leitor pode abri-lo quando precisar de explicações sobre a implementação ou de informações sobre as verificações.

Imagine um PR que adia o carregamento de um script de edição. No início, basta explicar que antes o script era carregado em todas as páginas e que agora ele é carregado quando um usuário com as permissões necessárias interage pela primeira vez com o recurso de edição. Essa é uma paráfrase de um dos exemplos do autor.

Abaixo, pode ficar o relatório do agente: quais manipuladores foram alterados, como o carregamento é acionado e quais verificações foram executadas. O revisor já entende a finalidade do trabalho e decide de quais detalhes precisa. Para um gerente de produto, o parágrafo introdutório pode bastar para avaliar o impacto sobre os usuários; um desenvolvedor continuará a análise pelo código e pela descrição técnica.

Os limites da formatação

Uma seção expansível não comprova que as alterações estão corretas nem torna confiáveis as verificações listadas. Se o agente afirma que os testes passaram, ainda é necessário conferir isso com os resultados da execução. Willison descreve sua prática de trabalho; o artigo não apresenta medições de economia de tempo ou de qualidade da revisão.

Há também um limite editorial: condições importantes não devem ficar escondidas a ponto de o leitor só descobri-las por acaso. Se uma alteração exige uma migração, afeta a compatibilidade ou modifica um fluxo de trabalho habitual, faz sentido destacar isso junto à introdução. Essa já é uma aplicação prática da abordagem proposta ao trabalho em equipe.

Você pode experimentar a técnica no próximo PR: mantenha no início uma explicação do problema e do resultado, acrescente uma captura de tela útil e depois recolha o relatório técnico do agente. Antes de encaminhar para revisão, leia o primeiro parágrafo isoladamente. Se ele deixar claro o que precisa ser avaliado, a descrição terá cumprido sua primeira função.