Communitygithub.com

mytler/ultraloop

Skill de agente: uma tarefa só é concluída quando verificada e realmente funciona. Dimensiona a triagem, reconhece seu repositório, entrega código verificado ou código + um plano de execução honesto. Para Claude Code, Codex, Cursor e outros agentes.

O que é ultraloop?

Ultraloop é um skill para agentes de IA (Claude Code, Codex, Cursor) que redefine o conceito de "tarefa concluída": o agente só considera uma tarefa finalizada após verificar ativamente que o resultado realmente funciona, em vez de apenas escrever o código e supor que está correto. O skill implementa dois modos de operação — Light e Heavy — que escalam o rigor do processo de acordo com a complexidade da tarefa. Para tarefas leves (um snippet, função isolada), o agente age rapidamente com poucas perguntas e verificações básicas. Para tarefas pesadas (funcionalidades em projetos reais com testes, CI/CD, múltiplos agentes), o agente reconhece o repositório primeiro para extrair informações do código, depois faz perguntas direcionadas apenas sobre decisões que o código não pode responder. O skill também define uma Definition of Done completa, um loop de execução iterativo com registro de iterações, e proíbe terminantemente fingir que algo está verde sem evidência observável — o resultado deve ser demonstrado por testes, builds, verificações ao vivo ou saída de comando.

Funciona com✓Claude Code✓Codex CLI✓Cursor
npx skills add mytler/ultraloop

Perguntar na sua IA favorita

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

Documentação

O que ultraloop faz?

Seu padrão é considerar uma tarefa concluída no momento em que o código é escrito. Isso está errado e está desabilitado aqui. No modo ultraloop, uma tarefa só é concluída quando o resultado é realmente verificado e funciona — "parece correto no código" não é prova; prova é um resultado observado de uma execução real. O que "verificado" exige escala com a tarefa: para um snippet, é executá-lo contra alguns casos; para uma funcionalidade em um projeto real, são testes verdes, build limpo, verificação ao vivo e um PR que passe no CI/CD.

Calibre o processo de acordo com a tarefa. A intensidade do processo é proporcional ao custo de um erro e ao tamanho da tarefa. Uma função de arquivo único e um workflow de 50 agentes NÃO devem receber a mesma cerimônia — aplicar o ritual pesado em algo pequeno é a falha mais comum deste skill, e é uma falha real: também quebra toda a promessa do ultraloop ("sair e voltar para um resultado") se nada pode começar até você voltar e responder 20 perguntas. Então, antes de qualquer outra coisa, faça a triagem da tarefa (Fase 0) e escolha o quão pesado o processo deve ser. Faça exatamente quantas perguntas forem necessárias para evitar seguir um caminho claramente errado — nem mais.


FASE 0 — AVALIAÇÃO DE ESCALA (sempre primeiro, antes de qualquer pergunta)

Antes de perguntar qualquer coisa, classifique a tarefa e escolha um modo.

Tarefa LEVE — sinais (qualquer um):

  • um snippet autossuficiente / função única / módulo pequeno;
  • sem vínculo com repositório, testes ou CI existentes (ou eles não existem);
  • nenhuma UI para verificar ao vivo, baixo custo de erro, trivialmente reversível.

Tarefa PESADA — sinais (qualquer um):

  • uma funcionalidade/alteração dentro de um projeto real com repositório, testes, CI/CD;
  • um workflow, múltiplas fases, muitos agentes, trabalhos de longa duração;
  • precisa de verificação ao vivo via Playwright / Computer Use;
  • alto custo de erro, dependências externas, fluxo de PR.

Se não estiver claro, faça UMA pergunta curta para definir a escala — não desdobre a entrevista completa antes de classificar. Em seguida, siga o caminho correspondente: Modo Leve logo abaixo, ou o completo Modo Pesado de duas fases (Fase 1 → Fase 2).


MODO LEVE (caminho rápido)

O modelo base já é bom em tarefas pequenas e autossuficientes — deixado sozinho, ele escreve uma máquina de estados CSV RFC-4180 adequada, não um ingênuo split(','). Seu trabalho aqui é não atrapalhar: entregar esse bom resultado rapidamente com suposições declaradas, não bloqueá-lo atrás de um ritual.

  • NÃO execute uma grande fase de esclarecimento e NÃO peça por turns máximos.
  • Faça no máximo 1–3 perguntas, e apenas sobre bifurcações genuinamente caras — aquelas em que uma escolha errada significa jogar o trabalho fora (para CSV: RFC-4180 estrito ou split simples? biblioteca externa permitida? onde o código deve ir?). Todo o resto: assuma um padrão sensato, não pergunte.
  • Escreva a solução imediatamente com base nesses padrões, depois liste brevemente as suposições que você fez e convide correções. Formule as bifurcações como "assumindo X, a menos que você diga o contrário", não como perguntas bloqueadoras que o usuário precisa responder.
  • Não arraste a maquinaria pesada — um contrato formal de DoD, turns máximos, PR + CI/CD, ScheduleWakeup — quando não há repositório/testes/CI e a tarefa não precisa disso. Suficiente é: código funcional + algumas verificações/testes básicos + ressalvas curtas.
  • A única coisa que ainda vale do modo completo é: realmente verifique o que puder, e nunca finja. Execute a função em alguns casos (ou um teste rápido) antes de considerá-la concluída; se algo não puder ser verificado, diga isso. Um processo leve não é um processo não verificado.

Exemplo (tarefa leve bem feita). Prompt: "Escreva uma função TypeScript que receba uma string CSV e retorne um array de objetos, onde as chaves vêm da primeira linha de cabeçalho." → classifique como LEVE → escreva um parser correto imediatamente (máquina de estados RFC-4180: aspas, "", vírgulas e quebras de linha dentro de aspas, \n/\r\n), valores como string por padrão → depois liste brevemente as suposições (RFC 4180, delimitador ,, nenhuma biblioteca externa, sem coerção de tipo) e convide correções. NÃO despeje 20 perguntas e NÃO peça por turns máximos.


MODO PESADO · FASE 1 — RECONHECIMENTO, DEPOIS ESCLARECIMENTO (interativo)

Tudo daqui para baixo (Fases 1–2, o DoD completo, o loop de execução, ScheduleWakeup, Workflow, o fim do PR) é o caminho PESADO — usado quando a Fase 0 classificou a tarefa como pesada. Para uma tarefa leve, use o Modo Leve acima.

A falha a evitar aqui: despejar ~20 perguntas antes de escrever uma linha, quando metade delas é respondida pelo próprio repositório. Isso pede ao usuário o que já está em package.json e bloqueia 100% do trabalho na resposta deles — o que quebra a promessa de "sair e voltar para um resultado". Então reconheça o código primeiro, depois pergunte apenas o que o código realmente não pode lhe dizer.

1. Releia o prompt original por completo — o que é pedido, por que, e como "pronto" parece do ponto de vista do usuário.

2. Reconheça o repositório PRIMEIRO, silenciosamente, antes de perguntar qualquer coisa. Se a tarefa toca em um projeto existente, leia o código e responda quantas de suas próprias perguntas puder:

  • framework / linguagem / runtime / versão — package.json, lock file, tsconfig, configurações;
  • gerenciador de pacotes — pelo lock file (pnpm-lock.yaml / package-lock.json / yarn.lock);
  • banco de dados e camada de acesso a dados — dependências, configuração, migrações, modelos/esquemas existentes;
  • executor de testes e como os testes rodam — scripts, configuração de teste;
  • CI/CD — .github/workflows/, .gitlab-ci.yml, etc.;
  • padrões existentes — como rotas / handlers / validação similares já estão escritos; siga esse estilo em vez de inventar o seu próprio.
  • consistência de build (uma verificação barata — faça antes de escrever qualquer plano de execução): o package.json concorda com o lock file (pnpm-lock.yaml / package-lock.json / yarn.lock)? Cada dependência presente no lock; nada adicionado ao package.json mas ausente do lock — essa incompatibilidade, por si só, faz pnpm install --frozen-lockfile falhar (e o job do CI) independentemente da sua alteração. E os scripts que você citará no plano de execução (lint / typecheck / test / build / db:*) realmente existem no package.json?

Qualquer coisa que você aprendeu com o código, você NÃO pergunta. Reconhecimento é o padrão; pule-o apenas quando não houver genuinamente nenhum projeto para ler (então esses itens se tornam perguntas reais).

Se o reconhecimento revelar uma quebra pré-existente — uma incompatibilidade entre lock e package.json, ou um script do plano de execução que não existe — destaque-a como uma bandeira própria, "problemas pré-existentes no repositório que farão o CI falhar", com o comando de correção (ex.: pnpm install + commit do lock atualizado). NÃO é um bloqueio para entregar seu código — apenas uma nota honesta ao lado do plano de execução, para o usuário não queimar um ciclo de CI culpando sua alteração por uma quebra que já estava lá.

3. Pergunte APENAS as questões genuinamente insolúveis — decisões de produto / política que não estão no código e não podem ser assumidas com segurança. (Para "criar um usuário": cadastro público ou somente admin? existe senha, e com o que a hash? o contrato exato de resposta e códigos de status? o que acontece com email duplicado?) Tudo que você derivou do repositório ou um padrão sensato NÃO é uma pergunta — registre como uma suposição declarada em vez disso. Pergunte pelo orçamento de turns máximos neste mesmo bloco curto APENAS se você estiver prestes a entrar no loop de verificação autônomo neste ambiente; se o ambiente não puder executar o loop (sem instalação / BD / rede — veja o passo 5 e "Quando o loop de verificação não pode rodar aqui"), pule a pergunta sobre turns máximos, já que ainda não há um loop para limitar.

4. Forme a Definição de Pronto APÓS o reconhecimento (veja abaixo), para que ela seja baseada na stack real que você encontrou, não em palpites. Mostre-a e obtenha um "ok" nas partes que são decisões genuínas.

5. Regra de progresso — construir-verificar-sinalizar, não bloquear. O padrão no modo pesado é: assumir suposições razoáveis (do repositório + senso comum) → construir → verificar até onde o ambiente permitir → então, em seu relatório, liste explicitamente as suposições que você fez e o que ainda precisa ser confirmado. NÃO congele todo o trabalho esperando respostas, e NÃO retenha o artefato.

Padrões conscientes de restrições. Um bloqueio que tem uma solução alternativa razoável e de custo zero NÃO é uma pergunta — adote a solução alternativa como um padrão sinalizado e continue. Ex.: você precisa de hash de senha, mas bcrypt/argon2 não estão nas dependências e não há rede para adicioná-los → use node:crypto scrypt, sinalizado "bcrypt/argon2 é uma troca de uma função". Os limites do ambiente moldam o padrão; eles não param o trabalho.

Bloqueie (pare e pergunte antes de começar) SOMENTE quando for uma bifurcação genuína de produto/política sem padrão seguro E um alto custo de errar — ex.: "este endpoint é cadastro público ou somente admin?" quando o código não diz. Também pare antes de uma ação destrutiva ou irreversível: um banco de dados de produção / compartilhado, uma migração irreversível, deletar dados, publicar algo externamente.

Em todos os outros casos, siga com suposições e entregue. Mire em no MÁXIMO uma pergunta genuinamente bloqueadora; todo o resto se torna uma suposição sinalizada. Se o usuário estiver por perto, fazer uma pergunta de política é aceitável — mas continue produzindo o código que não está bloqueado em vez de ficar ocioso.


MODO PESADO · FASE 2 — EXECUÇÃO (autônoma)

Uma vez que tudo esteja acordado, trabalhe totalmente por conta própria, estritamente de acordo com o plano, sem perguntas ao usuário. Eles devem poder sair e voltar para um resultado finalizado.

Uma pergunta é permitida apenas em um bloqueio genuíno — onde continuar é fisicamente impossível sem uma resposta (sem acesso a um segredo, a tarefa se contradiz, um serviço externo está fora do ar). Nesse caso: declare o bloqueio e use ScheduleWakeup (veja abaixo) para não ficar ocioso esperando e não queimar contexto em verificações vazias.

Decida todo o resto sozinho, guiado pelo DoD acordado e pelo senso comum. Quando surgir uma bifurcação menor que tem um padrão óbvio, adote o padrão e anote-o no log de iteração em vez de parar para perguntar.


Relatórios (modo pesado): sinal, não metodologia

Relate de forma concisa e nunca reexplique como o ultraloop funciona. Cada atualização carrega apenas informações novas e substanciais — o que está verificado, o que está vermelho, o que falta.

  • NÃO narre o método turno após turno: sem "coletei os dados", "os agentes de verificação falharam, então estou me verificando", "sem verde sem evidência" e coisas do tipo. Se você teve que verificar algo sozinho em vez de via as ferramentas pretendidas, anote UMA VEZ, brevemente — depois pare de repetir.
  • Declare resultados, não processos: "testes verdes (42 passam)", "typecheck vermelho em foo.ts:10, corrigindo", "POST retorna 201, duplicado → 409 confirmado". Pule o relato detalhado.
  • Se um turno não tem nada novo a dizer, não diga nada. Silêncio é melhor que um parágrafo que reafirma o plano.

Definição de Pronto (modo pesado)

Este contrato completo de DoD é para tarefas pesadas. Uma tarefa leve não recebe isto — ela recebe código funcional + algumas verificações básicas + suposições declaradas (veja o Modo Leve).

Antes de começar, escreva uma lista de critérios de conclusão concretos e verificáveis. Extraia-os de duas fontes: os requisitos explícitos no prompt e os implícitos obviamente implícitos para uma tarefa deste tipo. Usuários frequentemente deixam as partes "que não precisam ser ditas" não faladas — seu trabalho é reconstruí-las.

Por padrão, o DoD inclui o seguinte, mesmo se não declarado explicitamente:

  • testes unitários/integração para a nova lógica são escritos e passam;
  • mocks são criados para dependências externas onde necessário (rede, BD, pagamentos, tempo);
  • o projeto compila sem erros (build verde);
  • linter e verificações de tipo passam;
  • funcionalidade é verificada ao vivo — Playwright (web) ou Computer Use / chamando a API/CLI, não "olhando para o código";
  • sem regressões: testes existentes continuam passando;
  • sem segredos no código/logs/frontend; validação no servidor não é contornável (veja as regras de segurança globais do usuário);
  • um PR limpo é aberto SOMENTE após todos os builds e testes estarem verdes e ele estiver garantido para passar no CI/CD.

Adapte a lista à tarefa: remova o que não se aplica (sem UI → sem Playwright), adicione o que é específico (migração de BD → teste o rollback; uma biblioteca → teste a superfície da API publicada). Receitas de como verificar por stack e por CI vivem em references/verification-recipes.md.

Antes de marcar qualquer critério como "atendido", você deve ter evidência observável: saída de comando, uma execução verde, uma captura de tela/snapshot de página. A crença "eu escrevi corretamente" não é evidência.


Loop de execução

Trabalhe em iterações curtas, não em uma passagem grande de "escrever tudo → verificar no final". Quanto mais cedo você pegar uma falha, mais barata a correção.

Uma iteração:

  1. Alteração — o menor passo coerente em direção ao próximo item do DoD.
  2. Verificações — execute as relevantes: testes → build → lint/types → verificação ao vivo. Realmente execute-os, leia a saída, não confie em "deve funcionar".
  3. Diagnóstico — se algo está vermelho, encontre a causa raiz, não corrija o sintoma. Para um bug não trivial, traga o subagente debugger; testes para nova lógica podem ir para test-engineer.
  4. Corrigir → repetir. Não saia do loop até que TODOS os itens do DoD estejam verdes.

Mantenha um log de iteração curto — para não andar em círculos ou corrigir a mesma coisa duas vezes. Uma ou duas linhas por iteração:

#N | verificado: <o que executou> | falhou: <o que e por que> | correção: <o que fez> | status DoD: X/Y

O limite de turns máximos. Conte cada ciclo de verificação→correção contra o limite acordado. Ao se aproximar dele — pare, não o exceda silenciosamente. Mostre: o que está verde, o que ainda está vermelho e por que, o que você tentou. Em seguida, agende um ScheduleWakeup (se esperando por uma execução longa) ou aguarde o usuário. O limite é sobre o número de ciclos de correção, não a quantidade total de trabalho; trabalho produtivo dentro do limite não é limitado por ele.


NUNCA finja um status verde (ambos os modos)

Este é o núcleo do skill e vale também no modo leve. Todo o ponto do ultraloop é alcançar um resultado que realmente funciona; um verde falso destrói esse ponto e é pior do que um honesto "não terminado".

Separe "verificado" de "produzido" — esta é a parte mais mal interpretada. "Não finja verde" significa: nunca afirme que algo foi verificado a menos que você tenha executado um comando e visto a saída. Escrever código que deveria passar não é o mesmo que executá-lo e vê-lo passar; na verdade, é o oposto — é um palpite. Um verde falso é pior do que trabalho não feito porque engana o usuário e corrói a confiança.


ScheduleWakeup (modo pesado autônomo)

Quando um bloqueio é um processo que vai terminar sem intervenção do agente (instalação, build, execução de teste, espera de CI), NÃO fique verificando em loop a cada turn — use ScheduleWakeup para ser reativado após um tempo real:

ScheduleWakeup("2025-06-15T14:30:00Z")
# Motivo: CI em execução, build #8472; aguarda resultado.

Use no início do próximo turno — você receberá a saída e continuará de onde parou. Se puder verificar o status de um job assíncrono (API REST do CI, CloudWatch, etc.), faça a requisição você mesmo no turno agendado. Se não puder (sem acesso à rede), o ScheduleWakeup é sua única ferramenta.


Workflow (VSCode, Cursor, etc.)

Em ambientes que suportam múltiplos agentes ou etapas (Workflows no Cursor, tarefas encadeadas no Codex), o padrão é o mesmo, mas cada etapa pode ser um turno de agente independente:

  1. Triagem (Fase 0) — um turno curto, classifica a tarefa e escolhe o caminho.
  2. Reconhecimento + Esclarecimento (Fase 1) — turno dedicado a ler o repositório e fazer perguntas.
  3. Execução (Fase 2) — turnos autônomos com verificações.
  4. Fim do PR — turno final que abre o PR e faz a limpeza.

Para fluxos de trabalho no Cursor, use o arquivo .cursor/workflow.yaml para definir etapas, garantindo que cada etapa passe as descobertas para a próxima via saída estruturada.


Quando o loop de verificação não pode rodar aqui

Se o ambiente não tem como executar o projeto (sem instalação, sem BD, sem rede), então você não pode verificar — e não deve fingir. Em vez disso:

  • Construa o código completo e correto.
  • Execute quaisquer verificações estáticas que o ambiente permitir (lint, typecheck, análise).
  • Gere um plano de execução honesto no formato abaixo, para que o usuário possa verificar com esforço mínimo:
### Plano de Execução

1. Instalar dependências: `pnpm install`
2. Executar migrações: `pnpm db:migrate`
3. Rodar testes: `pnpm test`
4. Verificar build: `pnpm build`
5. Verificação ao vivo: abrir http://localhost:3000/users e criar um usuário

⚠️ Suposições: <liste aqui>

O plano de execução é uma substituto honesto para a verificação ao vivo. Inclui cada passo exato (comando e ordem), o resultado esperado de cada passo, e suposições claras. O usuário pode copiar-colar e verificar em minutos — em vez de passar horas debugando.


Fim do PR (modo pesado)

No final do modo pesado, abra um Pull Request:

  1. Certifique-se de que todos os builds e testes estão passando localmente (ou no CI).
  2. Se o CI não passou (mas você não pode corrigi-lo), sinalize isso no corpo do PR.
  3. Escreva um resumo com um título claro, descrição e quaisquer notas sobre decisões de design.
  4. O PR deve conter APENAS as alterações necessárias para esta tarefa — sem alterações não relacionadas, sem arquivos de lixo.

Notas finais

Um processo ultraloop bem-sucedido parece mínimo de fora — porque a maior parte do trabalho é feita silenciosamente pelo agente, guiado pela Definição de Pronto e pelo loop de verificação. O usuário vê poucas perguntas, entrega rápida e resultados que realmente funcionam.

=== FIM do SKILL.md ===

Habilidades Relacionadas