Ir para o conteúdo

20. As ferramentas do time: pull requests, issues e quadros

Depois deste capítulo você consegue levar uma entrega ao branch principal por um pull request cuja revisão lê a página antes do diff, sabendo quem no time é o revisor que o kit assume e o que o kit assume de quem no time não lê código, e manter issues e um quadro em sintonia com a fila sem fazer de nenhum deles a fonte da verdade, atualizando o quadro por um slot do docs/05 em vez de uma edição nos comandos. Você também consegue dizer por que os documentos de um projeto ficam em docs/ e nunca numa wiki.

O problema

O kit assume uma pessoa que propõe uma entrega, usa a entrega e a revisa: por padrão o diff em stage, antes de fazer o commit, ou, quando a palavra do slot Git deixa o agente fazer o commit, o commit, depois que ele entra. O kit não divide esses papéis além disso; como um time os divide é prática do próprio time. Quem não lê código participa do /propose, onde a página é escrita em linguagem de usuário (capítulo 12), testa a entrega como seu usuário (capítulo 13) e pergunta a qualquer sessão em que pé as coisas estão ou o que uma página decidiu (capítulo 17). Um time precisa de mais duas coisas: uma segunda pessoa que revisa, por padrão antes do merge, e um jeito de quem não abre nem o repositório nem uma sessão, um cliente ou um gerente, ver o progresso. As estratégias de git do capítulo 18 param no merge: elas dão forma ao histórico, e não dizem nada sobre quem revisou uma mudança ou quem acompanha o trabalho.

O pull request como a revisão do time

Um pull request é um pedido, feito num host de código como o GitHub, para fazer o merge de um branch em outro. Ele reúne a descrição, os commits, as verificações automáticas e o diff num só lugar, onde os revisores comentam e aprovam: nas palavras do GitHub, "Um pull request reúne o contexto de que os revisores precisam para entender uma mudança".1 O GitLab chama a mesma coisa de merge request.

Com o focus-kit, um pull request carrega uma entrega:

  1. Um branch por entrega, com o nome do seu slug. O /propose envia o branch no momento em que o cria, então a linha fica ocupada para todo mundo que faz git fetch.
  2. A página primeiro. O primeiro commit no branch é work/<slug>.md, escrita pelo /propose. Abra o pull request assim que o commit da página for enviado, o segundo envio, seu ou pedido ao agente, e a página pode ser revisada antes de existir qualquer código.
  3. A construção depois. O /apply constrói no mesmo branch; a página vai para work/done/ e a linha da fila vira [x] na mesma mudança.
  4. Um merge. A entrega chega inteira ao branch principal, com a sua página, o seu código, os seus testes, a sua prova e a sua marca, então a fila no branch principal só muda por merges e guarda o que já chegou; um [~] ou [*] posto em um branch está só nesse branch, onde um quadro ou uma sessão o lê (capítulo 14).

O revisor lê a página, depois o diff contra ela. Cada linha de Comportamento tem o seu teste ou a sua checagem manual; o Contrato bate com o código até os nomes; nada listado em Fora do escopo foi construído; cada item do Pronto quando está marcado com a sua prova. Uma mudança no diff que a página não pede é o primeiro achado, qualquer que seja a sua qualidade.

O primeiro revisor pode ser um agente: o comando de revisão do próprio host, ou a revisão de código do GitHub Copilot, que lê as instruções personalizadas e de agente do repositório no branch em revisão, então conhece as mesmas regras que o agente que construiu a mudança.2 A documentação do GitHub dá o próprio limite: "Sempre valide o feedback do Copilot com cuidado. Complemente o feedback do Copilot com uma revisão humana."2 A revisão do agente encontra o que uma pessoa cansada lê por cima; a pessoa decide o que é um achado, e aprova o merge. Por padrão o revisor que o kit assume é quem decide o merge, fazendo-o ou pedindo-o ao agente: em um branch o merge é a única mudança da entrega, como o commit é no trunk; quando a palavra do slot Git deixa o agente fazer o merge, o revisor é a pessoa que revisa o merge depois que ele entra.

Issues

Uma issue é o registro do GitHub para "ideias, feedback, tarefas ou bugs", aberta na web por qualquer pessoa com acesso, inclusive gente de fora do time.3 Isso faz dela uma boa porta de entrada para o relato de bug de um usuário.

Uma linha da fila pode espelhar uma issue, e o slug nomeia as duas: o título da issue começa com o slug, e a linha termina com o número da issue.

[ ] corrigir-devolucao  data de devolução um dia antes no fim do mês (#42)

O pull request diz "Fixes #42", e o GitHub fecha a issue quando o merge acontece.3 A fila continua a fonte da verdade, porque o agente lê o repositório e nunca uma página web: uma issue sem linha na fila não existe para o /propose. Então uma issue vira uma linha por conversa, e daí em diante é uma entrega como qualquer outra.

Quadros

Um gerente abre um quadro; raramente abre um repositório. Um quadro cujos cartões são movidos à mão, porém, é uma segunda fila, e se afasta da primeira no dia em que alguém esquece de arrastar um cartão.

A resposta é um espelho numa só direção, da fila para o quadro. No Caso A, um projeto para um cliente em uma plataforma low-code, uma customização registrada no seu docs/05 fazia isso: um script e um pipeline enviavam a fila, numa só direção, ao quadro kanban do projeto no Azure DevOps, então o gerente de projeto acompanhava o progresso no portal sem perguntar a um desenvolvedor. O /propose e o /apply atualizavam o quadro sempre que mudavam uma marca, e avisavam sempre que não conseguiam, então um quadro desatualizado nunca ficava em silêncio. Um projeto dá ao seu quadro essa atualização com um slot próprio no docs/05 §5 que cita o /propose, o /apply e o comando que envia a fila, como no docs/05 da biblioteca de empréstimos do capítulo 7; os comandos o seguem como seguem os slots do kit, sem nenhuma edição nos seus arquivos, que a instalação do kit escreve. Como o envio roda dentro do comando que mudou a marca, o quadro mostra essa marca na hora; com um branch ou um worktree por entrega o comando que envia lê a linha de cada slug no branch dele, local ou remoto, e as linhas que só um branch tem, então o envio de uma entrega leva a marca de cada outra entrega até onde consegue vê-la: a de um branch quando entra em um commit nele, a de um branch remoto quando esse commit é enviado. Com as seis marcas do kit, um espelho coloca cada cartão pela marca da sua linha, na coluna em que o capítulo 14 as dobra nas colunas de um quadro. O espelho vai numa só direção porque a fila é o único lugar que o agente lê: um cartão movido no quadro não muda nada no repositório, e uma sincronização nas duas direções criaria duas fontes da verdade.

Entregas de pergunta

O Caso A registrou mais uma customização: as entregas de pergunta, cujo único resultado é uma resposta escrita de alguém de fora do projeto. Elas fecham na resposta, não no envio, porque uma sessão certa vez marcou uma delas como concluída quando o email saiu.

Por que a wiki não é o docs/

O GitHub dá a todo repositório uma wiki, e ela parece a casa natural dos documentos de um projeto. Ela é um segundo repositório, editado na web, sem pull requests e sem build. O agente na pasta do projeto não a lê, e nenhuma entrega a muda, então ela se afasta do código na primeira entrega que a esquece. O docs/ muda no mesmo commit que o código que descreve, e é revisado no mesmo pull request. Este livro tomou a mesma decisão para si: nenhuma wiki, escrita ou espelhada; uma só fonte gera o site e o PDF.

O que o time ganha

O gerente vê o progresso sem perguntar a um desenvolvedor, e a revisão lê uma página antes de ler um diff, então uma mudança que ninguém pediu é encontrada na primeira pergunta. O quadro do Caso A rodou em um projeto, e a sua permissão de escrita nunca foi provada.

Pontos-chave

  • O kit assume uma pessoa que propõe, usa e revisa, por padrão o diff em stage antes de fazer o commit, ou o commit que a palavra do slot Git deixou o agente fazer, e um time divide esses papéis como prática própria; quem no time não lê código participa do /propose, testa a entrega como seu usuário e pergunta a uma sessão em que pé as coisas estão ou o que uma página decidiu, e um quadro serve a quem não abre nem o repositório nem uma sessão.
  • Um pull request carrega uma entrega: um branch com o nome do slug, enviado quando o /propose o cria, a página primeiro, a construção depois, um merge com a página, o código e a marca; seu revisor lê a página, depois o diff contra ela; um agente pode revisar primeiro, uma pessoa decide, e o revisor que o kit assume é, por padrão, quem decide o merge, ou, pela palavra do slot Git, a pessoa que revisa o merge que o agente fez.
  • Uma issue espelha uma linha da fila pelo slug, e a fila continua a fonte da verdade, porque o agente lê o repositório.
  • Um quadro é um espelho da fila numa só direção, atualizado, quando uma marca muda, por um slot do docs/05 que os comandos seguem, não por uma edição neles, nunca em silêncio quando não consegue ser, e, com um branch ou um worktree por entrega, lido do branch de cada slug.
  • Uma entrega de pergunta, customização do próprio Caso A, fecha na resposta, não no envio.

  1. GitHub Docs, "Pull requests", seção "Working with pull requests", acesso em 2026-09-30. https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests ↩

  2. GitHub Docs, "About GitHub Copilot code review", seções "Agent skills" e "Validating Copilot code reviews", acesso em 2026-09-30. https://docs.github.com/en/copilot/concepts/agents/code-review ↩↩

  3. GitHub Docs, "About issues", acesso em 2026-09-30. https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues ↩↩