Orquestrar Refatoração em Lote

Visão Geral

Use esta habilidade para executar refatorações de alta vazão com segurança. Analise o escopo em paralelo, sintetize um plano único e, em seguida, execute pacotes de trabalho independentes com subagentes.

Quando Usar

• Quando uma refatoração abrange muitos arquivos ou subsistemas e precisa de uma partição de trabalho clara.
• Quando você precisa de planejamento ciente de dependências antes da implementação paralela.

Entradas

• Caminho do repositório e escopo alvo (caminhos, módulos ou área de funcionalidade)
• Tipo de objetivo: refatorar, reescrever ou híbrido
• Restrições: paridade de comportamento, estabilidade de API, prazos, requisitos de teste

Quando Usar Paralelização

• Use esta habilidade para escopos médios/grandes que tocam muitos arquivos ou subsistemas.
• Pule a execução multiagente para edições pequenas ou trabalho de arquivo único altamente acoplado.

Fluxo de Trabalho Principal

1. Defina o escopo e os critérios de sucesso.
   • Liste os caminhos/módulos alvo e os não-objetivos.
   • Declare as restrições de comportamento (por exemplo: preservar o comportamento externo).
2. Execute a análise paralela primeiro.
   • Divida o escopo alvo em "lanes" de análise.
   • Inicie explorer subagentes em paralelo para analisar cada "lane".
   • Peça a cada agente: mapa de intenção, riscos de acoplamento, pacotes de trabalho candidatos, validações necessárias.
3. Construa um plano ciente de dependências.
   • Mescle a saída do explorador em um único grafo de trabalho.
   • Crie pacotes de trabalho com propriedade de arquivo clara e comandos de validação.
   • Sequencie os pacotes por nível de dependência; execute apenas pacotes independentes em paralelo.
4. Execute com agentes trabalhadores.
   • Inicie um worker por pacote independente.
   • Atribua propriedade explícita (arquivos/responsabilidade).
   • Instrua cada trabalhador que ele não está sozinho na base de código e deve ignorar edições não relacionadas.
5. Integre e verifique.
   • Revise as saídas dos pacotes, resolva sobreposições e execute portões de validação.
   • Execute testes direcionados por pacote, depois uma suíte mais ampla para o escopo integrado.
6. Relate e feche.
   • Resuma os resultados dos pacotes, refatorações chave, conflitos resolvidos e riscos residuais.

Regras do Pacote de Trabalho

• Um proprietário por arquivo por onda de execução.
• Sem edições paralelas em conjuntos de arquivos sobrepostos.
• Mantenha os objetivos do pacote estreitos e mensuráveis.
• Inclua critérios de conclusão explícitos e verificações necessárias.
• Prefira refatorações que preservem o comportamento, a menos que o usuário solicite explicitamente a mudança de comportamento.

Contrato de Planejamento

Cada pacote deve incluir:

1. ID do pacote e objetivo.
2. Arquivos de propriedade.
3. Dependências (nenhuma ou IDs de pacotes).
4. Riscos e invariantes a serem preservados.
5. Verificações necessárias.
6. Notas de integração para a thread principal.

Use references/work-packet-template.md para a forma exata.

Contrato de Prompt do Agente

• Use os modelos de prompt em references/agent-prompt-templates.md.
• Os prompts do explorador focam em análise e decomposição.
• Os prompts do trabalhador focam em implementação e validação com limites de propriedade rigorosos.

Barreiras de Segurança

• Não inicie a execução do trabalhador antes que a síntese do plano esteja completa.
• Não paralelize através de dependências não resolvidas.
• Não declare conclusão se qualquer verificação de pacote necessária falhar.
• Pare e replaneje quando os limites do pacote causarem conflitos de mesclagem repetidos.

Estratégia de Validação

Execute nesta ordem:

1. Verificações em nível de pacote (rápidas e com escopo).
2. Verificações de integração entre pacotes.
3. Verificações de segurança completas do projeto quando o escopo for amplo.

Prefira loops de feedback rápidos, mas nunca pule as verificações de comportamento necessárias.

Limitações

• Use esta habilidade apenas quando a tarefa corresponder claramente ao escopo descrito acima.
• Não trate a saída como um substituto para validação específica do ambiente, testes ou revisão de especialistas.
• Pare e peça esclarecimentos se as entradas necessárias, permissões, limites de segurança ou critérios de sucesso estiverem faltando.