Resolvedor Paralelo de Issues

Resolve vários issues do GitHub em paralelo, cada um em seu próprio worktree git isolado, e então integra cada um através de seu próprio pull request. Planeja um grafo de dependências a partir dos números dos issues, implementa cada issue desbloqueado concorrentemente via subagentes, faz com que um revisor independente e separado verifique cada diff antes de integrar, copia automaticamente arquivos de ambiente/segredo para cada worktree, abre um PR por issue, aguarda o CI passar, faz squash-merge e fecha cada issue com um comentário descrevendo exatamente o que foi feito. Use quando o usuário fornecer um conjunto de números de issues (ex: 'resolva #12 #15 #18', 'corrija esses issues em paralelo', 'trabalhe esses tickets em worktrees', 'paralelize esses issues') e quiser que sejam feitos concorrentemente.

O que é Resolvedor Paralelo de Issues?

O Resolvedor Paralelo de Issues é uma skill para o Claude Code que permite resolver múltiplos issues do GitHub de forma concorrente, cada um isolado em seu próprio worktree git, e então integrá-los via pull requests individuais. Sua principal vantagem é automatizar todo o fluxo de trabalho: planejamento (construindo um grafo de dependências), implementação paralela por subagentes, revisão independente de cada diff, correção, e integração final com squash-merge, CI e fechamento do issue com comentário. A skill é executada exclusivamente no Claude Code, utiliza subagentes com isolamento de worktree para garantir que implementações concorrentes não interfiram umas nas outras, e possui múltiplas salvaguardas: revisão independente obrigatória (por padrão), verificação de CI, nunca faz push para a branch base, e só considera um issue como resolvido quando o GitHub reporta o PR como 'MERGED'. Ela também copia automaticamente arquivos como `.env` para cada worktree, garantindo que o ambiente de desenvolvimento seja preservado em cada tarefa isolada.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/dhiraj-verhelm/agent-skills/tree/HEAD/skills/parallel-issue-resolver

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que Resolvedor Paralelo de Issues faz?

Resolva um lote de issues do GitHub concorrentemente, cada um isolado em seu próprio worktree git, e então integre cada um através de seu próprio pull request. Cinco fases — Planejar → Implementar → Revisar → Corrigir → Integrar.

A regra fundamental: um issue é fechado se e somente se o GitHub reportar seu PR como MERGED. Não em um merge local, não em uma execução de teste verde em um worktree, não por determinação de um subagente. Cada fechamento carrega um comentário dizendo o que foi realmente implementado.

O trabalho chega ao main da mesma forma que o de um humano faria: branch → PR → CI → squash-merge. Nada é integrado que o CI não tenha visto.

Início rápido

O usuário diz: "Resolva #12 #15 #18 em paralelo".

  1. Pré-verificação: bash <diretório-da-skill>/scripts/preflight.sh — deve sair com código 0 antes de você gerar qualquer coisa. Não há etapa de configuração separada; ele configura o próprio repositório na primeira execução.
  2. Planejar: leia cada issue, construa um grafo de dependências, escolha os issues que podem rodar agora sem colidir.
  3. Implementar: um subagente por issue desbloqueado com isolation: "worktree", todos gerados em uma única mensagem para que sejam executados concorrentemente. Cada um implementa, commita, faz push, abre um PR e escreve um handoff.
  4. Revisar: um subagente revisor separado por issue — nunca o autor — lê o diff em relação ao issue e retorna approve ou changes-requested.
  5. Corrigir: envie as descobertas bloqueantes de volta ao implementador original e então re-revise. No máximo duas rodadas.
  6. Integrar: para cada issue aprovado, bash <diretório-da-skill>/scripts/land.sh <issue> <branch> <arquivo-de-comentário> — um de cada vez.
  7. Repetir se ainda houver issues recém-desbloqueados.

Leia REFERENCE.md para obter detalhes sobre mecânica, detecção de comandos e armadilhas antes da primeira execução.

Fase 0 — Pré-verificação

Execute isso antes de cada lote. É o único comando de configuração na skill:

bash <diretório-da-skill>/scripts/preflight.sh        # adicione --fix para limpar sobras seguras

Ele inicializa tudo o que ainda não estiver configurado — .worktreeinclude para que arquivos .env/secretos ignorados pelo git sejam copiados para todo worktree, regras de ignore, worktree.baseRef: "head" — então verifica se a execução realmente será bem-sucedida: ferramentas necessárias presentes, árvore limpa, gh autenticado, base em sincronia com a origem, CI acionando em pull_request e nenhum branch agent/issue-* ou worktree órfão residual que possa colidir.

A inicialização é idempotente e só imprime quando algo muda, portanto, a partir da segunda execução, é puramente uma verificação. Não escreve nenhum arquivo rastreado — as regras de ignore vão para .git/info/exclude, para que a skill nunca deixe um diff no repositório de ninguém.

Se a saída for diferente de zero, pare e corrija — não gere agentes. Relate ao usuário o que foi encontrado.

Capture a branch base: git branch --show-current → BASE. Todos os PRs têm como alvo BASE.

Fase 1 — Planejar (orquestrador, inline)

Para cada issue: gh issue view <id> --json number,title,body,labels,state,comments. Se um issue referenciar um PRD/épico pai, leia-o também.

Pule qualquer issue que já esteja CLOSED ou que já tenha um PR aberto (gh pr list --search "<id> in:body") — diga isso em vez de duplicar trabalho.

Construa um grafo de dependências. O issue B é bloqueado por A se qualquer um dos seguintes se aplicar:

  • B precisa de código/infra que A introduz.
  • B e A modificam arquivos/módulos sobrepostos → edições concorrentes colidiriam.
  • B depende de uma forma de API ou decisão que A estabelece.

Um issue está desbloqueado se não tiver dependências bloqueantes nos outros issues deste lote. Apenas issues desbloqueados são executados nesta rodada. Se todo issue estiver bloqueado, execute apenas aquele com as dependências mais fracas para quebrar o ciclo.

Atribua a cada um uma branch determinística: agent/issue-<id>. Informe ao usuário o plano do lote antes de gerar — quais issues serão executados agora, quais aguardarão e por quê.

Fase 2 — Implementar (subagentes paralelos)

Para cada issue desbloqueado, gere um subagente através da ferramenta Agent com isolation: "worktree". Coloque todas as gerações em uma mensagem para que sejam executadas concorrentemente.

  • Tipo do subagente: general-purpose (precisa de edição + bash).
  • Nomeie-o como impl-<id> — você precisará do nome para enviar as descobertas da revisão de volta a ele na Fase 4 com seu contexto intacto.
  • Prompt: o conteúdo de prompts/implement.md com {{ISSUE_ID}}, {{BRANCH}} (= agent/issue-<id>), {{BASE}} e {{STATE_DIR}} (caminho absoluto para <repo>/.claude/pir) preenchidos.

Cada subagente implementa, organiza seu próprio diff, faz push, abre um PR e escreve dois arquivos de handoff em {{STATE_DIR}}. Os arquivos são o registro durável — eles sobrevivem à compactação de contexto, a linha RESULT não. Consulte REFERENCE.md.

Fase 3 — Revisão independente (subagentes paralelos)

O agente implementador não revisa seu próprio trabalho. Para cada issue que retornou complete com um PR aberto, gere um revisor separado — novamente todos em uma mensagem.

  • Tipo do subagente: general-purpose. Nomeie-o como review-<id>.
  • Sem isolation: "worktree" — a revisão é somente leitura e funciona com git diff {{BASE}}...{{BRANCH}} a partir do checkout base. Nenhum worktree para criar ou limpar.
  • Prompt: prompts/review.md com {{ISSUE_ID}}, {{BRANCH}}, {{BASE}}, {{PR}}, {{STATE_DIR}} preenchidos.

O revisor escreve {{STATE_DIR}}/issue-<id>.review.json com um veredito de approve ou changes-requested mais descobertas. Ele nunca edita, faz push, mescla ou comenta — ele relata, você decide.

Publique o veredito no PR para que o raciocínio fique registrado onde um humano o procuraria:

gh pr comment <PR> --body "$(jq -r '"**Revisão automatizada: \(.verdict)**

\(.summary)"' .claude/pir/issue-<id>.review.json)"

Fase 4 — Rodada de correção (apenas para changes-requested)

Envie as descobertas bloqueantes de volta ao implementador original, que ainda tem o código no contexto:

SendMessage → to: "impl-<id>"

A revisão independente do PR # encontrou problema(s) bloqueante(s). Corrija apenas estes, reexecute as verificações, faça push para a mesma branch e atualize seu handoff .md para corresponder ao estado final.

<o array blocking, na íntegra>

Se você achar que uma descoberta está errada, diga o porquê em vez de alterar código que você acredita estar correto.

Em seguida, reexecute a Fase 3 para esse issue (um agente review-<id> novo — rodada 2).

Limite em duas rodadas de revisão. Se um issue ainda estiver changes-requested após a rodada 2, pare: deixe o PR e o issue abertos e informe ao usuário o que não foi resolvido com as descobertas do revisor. Três rodadas significam que o issue está mal especificado ou o desacordo precisa de um humano, e rodadas adicionais queimam tokens sem convergir.

Se o implementador contestar uma descoberta em vez de corrigi-la, leia ambos os argumentos e julgue você mesmo. Não apenas repasse — é assim que se formam loops.

Fase 5 — Integrar (orquestrador, a partir do checkout BASE)

Integre os issues um de cada vez, em série — nunca em paralelo. Cada merge altera BASE, o que pode desatualizar o próximo PR; land.sh faz rebase quando o GitHub reporta um conflito, e isso só funciona contra uma base já atualizada.

Para cada issue cujo handoff diga status: "complete" e cujo veredito da revisão seja approve:

bash <diretório-da-skill>/scripts/land.sh <issue> agent/issue-<issue> .claude/pir/issue-<issue>.md

O script realiza toda a parte final na única ordem correta: verifica o veredito da revisão → libera o worktree → faz rebase se houver conflito → poll no CI até ficar verde → squash-merge → verifica se o GitHub reporta MERGED → fecha o issue com o comentário de handoff → faz fast-forward da BASE → exclui a branch → limpa worktrees.

Ele se recusa a integrar qualquer coisa sem um veredito approve em disco, portanto a revisão é uma barreira, não um hábito. PIR_SKIP_REVIEW=1 o substitui — se você usar isso, diga em voz alta, pois remove a única verificação que o CI não pode realizar.

Ramifique com base no código de saída:

CódigoSignificadoO que você faz
0Integrado, fechado, limpoContinue para o próximo issue
2Pré-condição falhouCorrija e reexecute; não force a passagem
3Conflito de rebase que o script não pode resolverResolva manualmente nessa branch, faça push, reexecute land.sh
4CI falhou ou expirouLeia a verificação com falha, corrija na branch, faça push, reexecute land.sh
5Problema de merge/fechamentoInspecione o PR — pode estar mesclado com o issue ainda aberto

Qualquer coisa diferente de 0 deixa o PR e o issue abertos, deliberadamente. Relate isso ao usuário com o link do PR; não tente novamente cegamente.

Em seguida, volte para a Fase 1 se ainda houver issues bloqueados.

Fase 6 — Relatar

Informe ao usuário, por issue: integrado (PR # + link), deixado aberto e por quê, ou pulado e por quê. Para qualquer coisa deixada aberta após duas rodadas de revisão, inclua as descobertas bloqueantes não resolvidas do revisor. Nunca afirme que um issue foi concluído sem o número do PR mesclado.

Requisitos

Roda no Claude Code: depende de subagentes com isolation: "worktree", SendMessage e .worktreeinclude. Instale com npx skills add dhiraj-verhelm/agent-skills --skill parallel-issue-resolver, ou copie este diretório para ~/.claude/skills/ ou .claude/skills/ de um repositório. Não há configuração por repositório, nenhum arquivo de configuração para editar e nenhum caminho para corrigir.

O que precisa na máquina: git, gh (autenticado) e jq. A pré-verificação verifica todos os três e nomeia qualquer um que estiver faltando.

O que precisa do repositório: um remote no GitHub e CI que reporte verificações em pull requests. A pré-verificação avisa se não encontrar esse CI. Você ainda pode executar com PIR_REQUIRE_CI=0, que integra PRs sem uma barreira de CI. Diga isso em voz alta se o fizer, pois remove a principal propriedade de segurança da skill.

O que não fará ao repositório: modificar qualquer arquivo rastreado. As regras de ignore são escritas em .git/info/exclude, portanto a inicialização não deixa diff e nada pode vazar para um commit.

Os scripts são invocados como bash <caminho>, portanto um bit executável perdido durante a cópia não quebra nada.

Segurança e barreiras

  • Nunca git push para BASE e nunca --force nada além da própria branch do agente (--force-with-lease, apenas dentro do rebase de land.sh).
  • Nunca git add -A / git add . — selecione apenas caminhos explícitos.
  • Nunca coloque Closes #N / Fixes #N no corpo de um PR. Isso faz o GitHub fechar o issue silenciosamente no merge, sem comentário sobre o que foi feito. Use Refs #N; o fechamento é explícito, com barreira de verificação de merge verificada, e sempre carrega o resumo.
  • Nunca faça merge com --admin e nunca pule uma verificação vermelha.
  • Um subagente por issue, trabalhando apenas em seu issue.
  • Se a pré-verificação falhar, pare e informe o usuário. Se a árvore estiver suja, pare — worktrees ramificam a partir de HEAD.

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Habilidades Relacionadas