Como usar o /ponytail-debt em código legado (e o que ele realmente entrega)

Tem base de código que ninguém abre por vontade própria, só por chamado urgente

E a promessa do /ponytail-debt aqui não é a de sempre: ele não vai te ajudar a escrever menos código

O que ele faz é mostrar o que já foi adiado de propósito e continua lá, parado, esperando alguém lembrar

O ponytail é um projeto open source mantido no GitHub por DietrichGebert, com a tagline "Makes your AI agent think like the laziest senior dev in the room. The best code is the code you never wrote"

O repositório acumula em torno de 107 mil estrelas (arredondamento que o GitHub mostrava em agosto de 2026), então não é experimento de fim de semana

E já adianto o mais importante antes de você criar expectativa: o /ponytail-debt é read only, ele lê e reporta, não altera uma linha sequer

Antes de rodar: o que você precisa ter instalado

No Claude Code o ponytail entra como plugin, pelo marketplace do próprio repositório

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

São dois comandos, um depois do outro:

/plugin marketplace add DietrichGebert/ponytail
/plugin install ponytail@ponytail

Depois disso o plugin adiciona seis comandos na tua sessão:

• /ponytail
• /ponytail-review
• /ponytail-audit
• /ponytail-debt
• /ponytail-gain
• /ponytail-help

E os níveis de intensidade?

Essa é a parada que muita gente instala e nem descobre que existe

O ponytail trabalha em quatro níveis: lite, full, ultra e off, sendo full o padrão

Tu define isso pela variável de ambiente PONYTAIL_DEFAULT_MODE ou pelo campo defaultMode no arquivo ~/.config/ponytail/config.json

Não usa Claude Code? Também dá

O projeto tem instalação para outros agentes, cada um com o seu jeitinho:

codex plugin marketplace add DietrichGebert/ponytail
copilot plugin install ponytail@ponytail
gemini extensions install github.com/DietrichGebert/ponytail
pi install git:github.com/DietrichGebert/ponytail

Massa, né? 🙂

Como usar o /ponytail-debt em uma base legada, passo a passo

1. Rode o comando dentro do repositório

O caminho óbvio é digitar /ponytail-debt na sessão

Mas a skill também dispara por frase em linguagem natural, tipo "ponytail debt", "what did ponytail defer", "list the shortcuts", "ponytail ledger" e "what did we mark to do later"

O erro comum deste passo: entrar em base legada achando que o comando vai descobrir dívida sozinho

Ele colhe MARCADOR, não intuição: se ninguém escreveu comentário ponytail: nesse projeto, não tem o que colher

2. Entenda o que ele varre (e o que ele ignora)

A skill acha os marcadores por grep no repositório, pulando node_modules, .git e saída de build

A busca é basicamente essa:

grep -rnE '(#|//) ?ponytail:'

Cada ocorrência encontrada vira uma linha do ledger

O erro comum deste passo: imaginar que ele faz leitura semântica do teu código inteiro, tipo uma revisão profunda

Não faz: aqui é coleta de marcador, e ponto

3. Leia cada linha do ledger

Cada entrada vem com file:line e três informações: o que foi simplificado, o teto (o limite nomeado) e o upgrade (o gatilho pra revisitar aquilo)

Isso funciona porque a convenção do comentário já carrega essas duas partes:

// ponytail: <ceiling>, <upgrade path>

Ou seja: o teto e o gatilho saem direto do que você escreveu no comentário

O erro comum deste passo: escrever o marcador fora do formato, só com um texto solto do tipo "depois eu melhoro isso"

Aí o ledger até lista, mas sem teto e sem gatilho ele vira um post-it velho na parede

4. Olhe a tag no-trigger e o fechamento do relatório

Todo comentário ponytail: que não nomeia upgrade nem gatilho recebe a tag no-trigger

Essa é a marcação de risco de apodrecimento: é o adiamento que ninguém sabe quando revisitar

E o relatório fecha com o total de marcadores e quantos deles estão sem gatilho

Se você mantém código antigo, esse número final é o mais útil da tela toda

5. Persista o ledger em um arquivo

A skill pode gravar o resultado em um arquivo, por exemplo PONYTAIL-DEBT.md

Aí o levantamento para de morrer junto com a sessão e vira material de conversa com o time

O erro comum deste passo: rodar em base virgem, receber a saída No ponytail: debt. Clean ledger e achar que deu ruim na instalação

Não deu: ledger vazio é comportamento esperado quando não existe nenhum marcador no repositório

Ledger vazio? Então o comando certo é o /ponytail-audit

Aqui mora o ponto que separa expectativa de realidade

O /ponytail-debt organiza o que foi adiado de propósito, com teto e gatilho

Em código que ninguém marcou (que é exatamente o caso do legado que você herdou), ele não tem matéria-prima

Quem ataca o excesso que JÁ está lá é o /ponytail-audit

Ele varre a codebase inteira em vez de um diff e devolve uma lista ranqueada do que dá pra deletar, simplificar ou trocar por stdlib e recurso nativo

A ordenação é pelo maior corte primeiro, e o relatório fecha com um resumo no formato net: -N lines, -M deps possible

O que o audit procura de verdade

A lista de alvos é bem concreta:

• dependência que a stdlib ou a plataforma já entregam
• interface com uma única implementação
• factory com um único produto
• wrapper que só delega
• arquivo que exporta uma coisa só
• flag e config mortas
• stdlib reimplementada na mão

Se você já passou por um projeto onde tem UserServiceFactory pra criar um serviço só, tu sabe do que eu tô falando haha

E tem um terceiro na família: o /ponytail-review, focado em over-engineering nas MUDANÇAS, com uma linha por achado (local, o que cortar, o que entra no lugar) e as tags delete, stdlib, native, yagni e shrink

Cuidado com o escopo

Esses comandos olham complexidade e over-engineering, só isso

Bug de correção, falha de segurança e problema de performance estão explicitamente fora de escopo e devem ir pra uma revisão normal

Tome cuidado pra não trocar tua revisão de código por isso aqui: são coisas diferentes

E os números? Expectativa realista

O ponytail viralizou com número de redução de código entre 80% e 94%

Em agosto de 2026 o próprio mantenedor corrigiu isso depois que um contributor apontou que a comparação era injusta: o número vinha de um teste contra um modelo puro que enche a resposta de prosa

Ele rodou tudo de novo contra uma baseline agêntica justa e reescreveu o README, o que eu acho MUITO massa como postura de manutenção

Mesmo assim, um teste independente da JetBrains mediu ganhos bem menores:

A JetBrains também não detectou degradação de qualidade, o que é um dado importante: cortar código sem piorar o resultado já vale a conversa

E o mais honesto de tudo: nenhum dos três comandos aplica correção

O audit é relatório one-shot, o review só lista, o debt é read only

Apontar não é refatorar

Trabalhar com legado: o que a lista não resolve

Relatório de excesso é fácil de gerar

Difícil é decidir o que fazer com ele numa base que sustenta o faturamento da empresa

Eu já falei sobre isso em vídeo, e a minha leitura continua a mesma: empresa com stack legada normalmente está GANHANDO dinheiro com aquela stack, e é por isso que o legado permanece

Tem uma base de confiança construída em cima daquelas tecnologias, e ninguém joga isso fora porque saiu um relatório dizendo que dá pra cortar N linhas

No vídeo eu mostro os dois caminhos que considero viáveis pra quem quer sair da stack legada: propor a modernização dentro da empresa de forma bem fundamentada, seja num projeto novo ou no próprio legado, ou procurar outro emprego com a stack que você quer

E reforço uma coisa que vale MUITO aqui: proposta com opinião solta, sem embasamento, não convence empresa nenhuma

É justamente aí que um ledger ou um audit ajuda: ele vira insumo de conversa, não ordem de serviço

Você chega com "esses três wrappers só delegam e essa dependência a stdlib já entrega" em vez de "esse código tá feio"

O mesmo raciocínio vale pro que já apodreceu de outro jeito, tipo modelo aposentado ainda no código, que é dívida de configuração e não de arquitetura

E se o teu plano é ir mexendo aos poucos com agente de IA, vale combinar isso com respeitar o padrão do projeto antigo, senão a refatoração vira um Frankenstein de dois estilos

E a crítica de que é só YAGNI reempacotado?

Ela existe e é pública: uma análise crítica aponta que o projeto é um arquivo markdown de cerca de 100 linhas descrevendo o YAGNI dos anos 1990

E olha, ela não está errada no conteúdo

Só que na prática de quem mantém código antigo isso muda pouco: o valor não está na novidade da ideia, está em ter alguém (no caso, o agente) aplicando o princípio de forma sistemática e devolvendo uma lista com arquivo e linha

Princípio a gente conhece há décadas, o que faltava era a varredura

Se você tá naquela dúvida de "fico e modernizo ou saio", esse vídeo te dá os dois caminhos com os prós de cada um, antes de você tomar decisão no impulso

Conclusão

Resumindo o que dá pra esperar de cada um:

• /ponytail-debt: organiza o que foi adiado DE PROPÓSITO, com file:line, teto e gatilho, e marca com no-trigger o que ninguém sabe quando revisitar
• /ponytail-audit: esse sim ataca o excesso que já existe na base inteira, ranqueado pelo maior corte primeiro
• nenhum dos dois refatora por você

Então o próximo passo concreto na tua base antiga é este:

Rode o /ponytail-audit primeiro, porque é ele que enxerga o que já está lá

A partir de agora, marque os adiamentos no formato com teto e caminho de upgrade

E volte no /ponytail-debt quando o ledger finalmente tiver o que colher 😀

até o próximo post!