pua-loop

Visão geral da skill pua-loop

Para que serve a pua-loop

pua-loop é uma skill de execução em loop para tarefas longas e com várias etapas de implementação, quando você quer que o agente continue iterando sem parar para fazer perguntas. Ela combina um loop autônomo de tentativas com as regras de comportamento pua:pua do repositório, para que o agente continue checando o trabalho, validando, corrigindo e executando de novo até conseguir declarar conclusão.

Quando a pua-loop é a melhor opção

A pua-loop skill funciona melhor para quem está lidando com tarefas de código ou fluxo de trabalho que podem ser verificadas localmente: correções de bugs, refactors, conclusão de features, reparo de testes e limpezas repetitivas. Ela é especialmente relevante para pua-loop for Workflow Automation quando o custo de interromper o fluxo é maior do que o de aceitar algumas suposições imperfeitas.

O trabalho real que ela resolve

Na prática, o que os usuários costumam querer não é “um prompt esperto”, e sim uma forma de delegar uma tarefa delimitada sem precisar vigiar o agente a cada poucos minutos. pua-loop foi feita para esse tipo de repasse. A principal promessa aqui é iteração autônoma: inspecionar o estado atual, fazer uma mudança, rodar validação, diagnosticar falhas e seguir em frente.

O que diferencia a pua-loop

O principal diferencial é que pua-loop assume uma postura clara em relação à persistência. A skill proíbe explicitamente que o agente faça perguntas ao usuário durante o modo loop e espera que ele esgote as alternativas antes de desistir. Ela também persiste o estado do loop em um arquivo local, então esse comportamento sobrevive melhor à compactação de contexto do que um prompt pontual comum.

Ressalva importante antes de adotar

Esta não é uma skill genérica para “programar melhor”. pua-loop é mais forte quando a tarefa tem uma condição de sucesso clara e verificações disponíveis. Se a tarefa for ambígua, exigir decisões frequentes de produto ou depender de aprovações externas, o prompting interativo tradicional costuma ser mais seguro.

Como usar a skill pua-loop

Verifique o contexto de instalação antes de depender dela

O trecho do repositório mostrado inclui apenas SKILL.md, e a skill depende de suporte do repositório mais amplo tanweai/pua, incluindo um caminho de script de setup e o comportamento da skill central pua:pua. Antes de usar a sério, revise a raiz do repo e confirme se o script de loop citado e a skill central estão presentes no seu ambiente instalado.

Como a pua-loop é acionada

O gatilho documentado é /pua:pua-loop "task description". A descrição também lista gatilhos em linguagem natural como loop mode, 自动循环 e 一直跑, mas o comando com barra é a forma menos ambígua de acionar pua-loop usage com confiabilidade.

O que acontece depois de iniciar

Ao ser iniciada, a skill executa um comando de setup que cria .claude/pua-loop.local.md. Esse arquivo armazena a tarefa junto com o protocolo do loop. Em seguida, um stop hook usa esse arquivo para reenviar instruções ao agente a cada iteração. Na prática, isso permite que o agente mantenha o mesmo padrão de execução ao longo de várias rodadas sem que você precise reexplicar o fluxo.

Quais entradas fazem a pua-loop funcionar bem

Dê ao pua-loop quatro coisas logo de início:

1. O resultado esperado da tarefa
2. O escopo do repo ou da pasta
3. O comando de validação
4. Quaisquer restrições rígidas

Uma entrada fraca:

• “Fix the app.”

Uma entrada forte:

• “Use pua-loop to fix the failing login flow in apps/web. Success means pnpm test --filter web passes and the OAuth callback no longer throws a 500. Do not change the database schema. Prefer the smallest safe fix.”

Essa versão mais forte reduz iterações desperdiçadas, porque o agente sabe onde trabalhar, como verificar e no que não deve mexer.

Como transformar um objetivo vago em um prompt completo de pua-loop

Um padrão prático de pua-loop guide é:

• Tarefa: o que deve ser construído ou corrigido
• Escopo: arquivos, pacote ou limites do serviço
• Verificação: testes, lint, build, smoke check
• Restrições: sem mudanças de schema, sem novas dependências, manter a API estável
• Prioridade: correção mais rápida e segura vs refactor mais profundo

Exemplo:

• /pua:pua-loop "Resolve TypeScript errors in packages/api only. Run pnpm --filter api build after each meaningful fix. Do not modify public endpoint contracts. Stop only when build passes and no new lint errors are introduced."

Arquivos do repositório para ler primeiro

Comece por:

• skills/pua-loop/SKILL.md

Depois inspecione o repositório pai em busca de:

• a definição da skill central pua:pua
• qualquer scripts/setup-pua-loop.sh
• documentação de hooks ou arquivos de setup de plugin do Claude

Essa ordem de leitura importa porque a decisão de pua-loop install depende menos do texto explicativo e mais de o seu ambiente local realmente dar suporte ao script de setup e ao loop acionado por stop hook.

O que o loop realmente faz em cada iteração

O conjunto principal de regras da skill é simples:

• carregar o comportamento pua:pua
• não fazer perguntas ao usuário
• não encerrar cedo com “cannot solve”
• depois de cada mudança, validar, encontrar problemas, corrigir e validar de novo

Isso faz da pua-loop algo mais próximo de um ciclo autônomo de reparo do que de uma interação comum com assistente.

Quando usar pua-loop em vez de um prompt normal

Use pua-loop quando:

• o sucesso puder ser verificado automaticamente
• você esperar várias rodadas de corrigir e verificar
• quiser menos interrupções
• o repo tiver comandos executáveis

Evite quando:

• a tarefa exigir julgamento de produto em cada etapa
• o agente não tiver acesso a testes ou verificações de runtime
• uma suposição errada puder custar caro

Fluxo prático para usar a pua-loop pela primeira vez

Uma primeira execução sensata:

1. Comece com um problema delimitado, não com uma grande reescrita.
2. Inclua o comando exato de validação.
3. Mantenha o escopo restrito a um pacote ou feature.
4. Deixe o loop rodar.
5. Revise as mudanças finais e só então amplie o uso.

Isso reduz o principal risco de adoção: edições autônomas excessivamente confiantes em tarefas mal especificadas.

Cancelamento e limites de segurança

A skill documenta dois caminhos de parada: /cancel-pua-loop ou a exclusão de .claude/pua-loop.local.md. Trate isso como conhecimento operacional obrigatório antes de ativar iteração autônoma. Se no seu ambiente você não consegue inspecionar ou remover esse arquivo com facilidade, a pua-loop skill talvez não seja adequada para o seu setup.

FAQ da skill pua-loop

A pua-loop é boa para iniciantes?

Sim, mas apenas para tarefas bem delimitadas. Iniciantes costumam se beneficiar da automação, mas também têm mais chance de fornecer instruções vagas. Se você está começando, inicie por um teste quebrado ou um erro de build, não por um pedido aberto de arquitetura.

A pua-loop substitui prompts comuns?

Não. pua-loop é melhor para loops de execução, não para exploração colaborativa. Se você ainda precisa escolher uma abordagem, comparar opções ou esclarecer requisitos, use primeiro um prompt normal e mude para pua-loop quando o plano já estiver definido.

Qual é o maior bloqueio para uma instalação bem-sucedida de pua-loop?

Na maioria dos casos, incompatibilidade de ambiente. A skill faz referência a um script de setup e a um loop acionado por stop hook. Se a sua configuração local de Claude/plugin não oferecer essas peças, o markdown sozinho não vai produzir o comportamento autônomo pretendido.

A pua-loop pode funcionar sem testes?

Pode, mas a qualidade cai. Sem testes, comandos de build ou smoke checks, o agente tem menos sinal para saber se cada iteração realmente melhorou a tarefa. Nesse cenário, pua-loop usage passa a depender mais de tentativa e menos de evidência, ficando menos confiável.

Em que a pua-loop difere de apenas dizer “continue tentando”?

Um prompt comum até pode pedir persistência, mas pua-loop acrescenta um padrão operacional específico: persistência de estado via arquivo local, validação repetida, modo explícito sem perguntas e sinalização de conclusão. Essa estrutura é o verdadeiro motivo para instalá-la.

Quando eu não devo usar pua-loop for Workflow Automation?

Não use pua-loop for Workflow Automation quando o fluxo depender de etapas de aprovação humana, credenciais externas, regras de negócio ambíguas ou tarefas em que “pronto” seja algo subjetivo. O loop autônomo só ajuda quando é possível verificar a conclusão.

Como melhorar a skill pua-loop

Dê à pua-loop uma linha de chegada mensurável

A forma mais rápida de melhorar os resultados de pua-loop é definir a conclusão em termos verificáveis por máquina. “Make it work” é fraco. “All auth tests pass, build succeeds, and /login/callback returns 200” é forte. A skill foi construída em torno de iteração, então ela precisa de um alvo que consiga validar.

Reduza o escopo para diminuir decisões autônomas ruins

Como pua-loop evita fazer perguntas de acompanhamento, tarefas amplas criam risco desnecessário. Em vez de “refactor payments”, diga “fix duplicate retry handling in services/payments/retry.ts without changing webhook payloads.” Um escopo mais estreito melhora tanto a velocidade quanto a segurança.

Forneça restrições que evitem correções destrutivas

Boas restrições não são enfeite; elas evitam que o loop resolva o problema errado. Exemplos úteis:

• não adicionar dependências
• não mudar o schema
• manter respostas da API retrocompatíveis
• preferir patch mínimo a reescrita

Isso melhora diretamente a qualidade da saída de pua-loop.

Use o comando de validação mais forte disponível

Se houver várias verificações possíveis, escolha a mais relevante, não a mais barulhenta. Para um bug de UI, uma suíte de testes focada é melhor do que rodar um monorepo inteiro. Para um problema de tipagem, tsc no pacote afetado pode ser melhor do que um lint amplo. Validação melhor leva a decisões melhores no loop.

Espere modos de falha quando faltar contexto

Os modos de falha mais comuns de pua-loop são previsíveis:

• descrições de tarefa vagas
• caminho do repo ou escopo do módulo ausente
• ausência de comando de validação
• requisitos não técnicos ocultos
• mudanças autônomas no pacote errado

Na maior parte dos casos, isso se corrige melhorando o prompt inicial, não apenas rodando de novo sem mudanças.

Depois da primeira rodada, itere com instruções mais precisas

Se a primeira passada de pua-loop chegar perto, mas não resolver tudo, não diga apenas “try again”. Acrescente o sinal que faltou:

• o que ainda falha
• quais arquivos foram alterados incorretamente
• qual tradeoff deve ser priorizado
• qual resultado de validação importa mais

Isso transforma a segunda rodada em uma correção guiada, e não em mais um loop cego.

Aumente a confiança lendo a dependência central

Como pua-loop herda comportamento de pua:pua, usuários avançados deveriam inspecionar essa skill central antes de adotar a ferramenta. Se você não gostar do estilo de pressão ou das regras de decisão dela, talvez nem queira esse wrapper de loop. Este é um dos passos mais importantes de leitura do repositório para tomar uma decisão de instalação mais informada.

Comece com automação delimitada e só depois expanda

Para a maioria dos times, o melhor pua-loop guide é uma adoção gradual: primeiro use em tarefas de reparo com verificações claras, depois em pequenas conclusões de feature e só mais tarde em fluxos maiores de automação. Essa sequência permite validar se o comportamento do loop combina com o seu repositório e com a sua tolerância a risco.