Ponytail: como fazer o agente de código escrever menos

O que é o Ponytail

Ponytail é um conjunto de regras que faz um agente de programação com IA escrever menos código. O projeto descreve-se numa frase: "Faz o seu agente de IA pensar como o programador sénior mais preguiçoso da equipa. O melhor código é aquele que nunca escreveu." É distribuído sob a licença MIT. Não tem um runtime próprio e nada nele é executado. É texto que entra nas instruções do agente, empacotado como uma skill para hosts que carregam skills e como ficheiros de regras simples para hosts que não o fazem.

O repositório é DietrichGebert/ponytail. Foi criado em 12 June 2026 e ultrapassou 90,000 estrelas em 1 August 2026. A versão mais recente com tag em 1 August 2026 é v4.8.4, publicada em 29 June 2026, e a página de releases lista dez tags apenas entre 14 e 29 June. Um projeto que avança a esse ritmo terá mudado quando ler este texto. Por isso, fixe uma tag antes de criar algo baseado nele.

A ideia antes da ferramenta: pare no primeiro degrau que se aplica

O núcleo do Ponytail é uma escada de decisão. O agente sobe por ela antes de escrever qualquer coisa e para no primeiro degrau que se aplica.

1. Isto precisa mesmo de existir? Este é o YAGNI (you are not going to need it). Se a resposta for não, ignore.
2. Isto já existe nesta base de código? Reutilize o helper ou o padrão que já está lá.
3. A biblioteca padrão faz isto? Use-a.
4. Existe uma funcionalidade nativa da plataforma que resolva isto? Use-a.
5. Uma dependência já instalada resolve isto? Use-a.
6. Isto pode ser feito numa linha? Faça-o numa linha.
7. Só depois escreva o código mínimo que funciona.

A ordem é que faz o trabalho, não um único degrau. Se for pedido a um agente um date picker, ele escreverá um date picker, porque foi isso que lhe pediram. A escada faz com que verifique primeiro o degrau 4, e o degrau 4 indica que o browser já tem <input type="date">. As notas de benchmark do projeto registam exatamente este caso: um date picker que tinha 404 linhas sem a regra passou a ter 23 linhas com ela, porque o agente escolheu o input nativo em vez de criar um componente. Um colour picker passou de 287 linhas para 23 pelo mesmo motivo. O degrau 2 é o que falha silenciosamente, porque um agente que não consegue ver o helper que já existe escreverá sem hesitar um segundo, que é precisamente a lacuna que um mapa consultável da sua base de código pretende eliminar.

Aqui, lazy não significa descuidado, e o ruleset diz isso diretamente. A lista de aspetos sobre os quais nunca se deve ser lazy inclui compreender o problema antes de decidir, validar entradas nos limites de confiança, tratar erros para evitar perda de dados, garantir segurança e acessibilidade, bem como tudo o que foi pedido explicitamente. Também exige uma pequena verificação executável para cada parte de lógica não trivial. A regra reduz a invenção. Não reduz a correção.

O que o repositório realmente fornece

• AGENTS.md, o conjunto de regras sempre ativo, que concentra toda a ideia num único ficheiro que pode ler em cinco minutos.
• skills/ponytail/SKILL.md, a definição da competência, com uma indicação de argumento de lite, full ou ultra.
• Ficheiros de regras em diretórios específicos de cada editor, como .cursor/rules/ e .windsurf/rules/, para hosts que leem regras mas não carregam competências.
• hooks/, benchmarks/, examples/ e scripts/.

O argumento de intensidade altera o rigor com que a regra é aplicada. lite cria o que pediu e indica uma opção mais permissiva numa linha. full é o valor predefinido e aplica a progressão. ultra é a configuração extremista do YAGNI: prefere eliminar a adicionar e questiona o próprio requisito.

Os hosts compatíveis com competências também recebem comandos slash. /ponytail define o nível, /ponytail-review verifica um diff à procura de engenharia excessiva, /ponytail-audit verifica um repositório inteiro, /ponytail-debt reúne os atalhos que adiou e /ponytail-gain apresenta a tabela de resultados do benchmark. Os hosts que apenas leem ficheiros de regras recebem o conjunto de regras sem comandos.

Para ler o código-fonte antes de confiar nele, clone a tag em vez do branch:

git clone --depth 1 --branch v4.8.4 https://github.com/DietrichGebert/ponytail.git

No Claude Code, o projeto documenta antes uma instalação como plugin, e estas duas linhas correspondem à documentação de 1 August 2026:

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

O caminho do plugin segue o branch predefinido em vez de uma tag. Por isso, as instruções que orientam o seu agente podem mudar sem aviso entre sessões. Esta é a contrapartida pela conveniência de um comando de atualização.

Por que um agente preguiçoso custa menos numa VPS

O diff que um agente escreve não sai da conversa. Na interação seguinte, ele passa a fazer parte do contexto que o modelo lê novamente, juntamente com todos os ficheiros que abriu para o produzir. Por isso, uma alteração de 500 linhas penaliza todas as interações seguintes da sessão, e não apenas a interação em que foi produzida. É por isso que uma refatoração descontrolada faz o agente parecer mais lento e menos competente à medida que a sessão avança: a janela fica preenchida com a própria saída do agente, reduzindo o espaço disponível para o seu código. Controlar esse aspeto é o tema de gerir a janela de contexto de um agente de programação.

Os tokens são cobrados tanto na entrada como na saída. Por isso, um diff com metade do tamanho custa menos duas vezes: uma quando é escrito e outra em cada interação que o lê novamente. A poupança aparecerá ou não na sua fatura, dependendo da forma de pagamento, porque uma subscrição Pro ou Max de preço fixo absorve os tokens adicionais, enquanto a faturação da API por token cobra cada um deles. Se estiver a acompanhar os custos numa instalação autoalojada, o ficheiro de instruções é uma alavanca que não custa nada utilizar. Controlar quanto um agente de IA lhe custa começa pelo volume da saída, e como um agente de programação gasta os seus tokens explica por que motivo a releitura tem mais impacto do que é habitual esperar.

Uma pessoa continua a ler o diff. Uma alteração de 400 linhas que deveria ter 20 linhas consome a atenção de quem faz a revisão, e a atenção é o recurso que se esgota primeiro. Ninguém revê o quarto diff longo do dia com o mesmo cuidado dedicado ao primeiro. Por isso, construir mais do que o necessário não desperdiça apenas tempo. Reduz discretamente a qualidade da revisão que deveria detetar os erros.

Num servidor, o risco é diferente, porque muitas vezes o agente é executado sem ninguém a observá-lo. Um agente a trabalhar numa sessão tmux ou através de um temporizador tem horas para desenvolver uma decisão errada antes de você a detetar. Esse é o risco prático de executar um agente de programação numa VPS, e é por isso que as pessoas que fazem engenharia de loops dedicam tanta atenção às instruções permanentes, em vez de se concentrarem apenas nos prompts individuais. Uma regra no ficheiro sempre ativo aplica-se à interação 200. Uma regra que escreveu no chat aplica-se à interação 3. Também se aplica à segunda sessão que iniciar na mesma máquina, que lê o ficheiro versionado mas não herda nada do que escreveu na primeira, mesmo quando as duas sessões conseguem enviar mensagens entre si.

As novas dependências são o outro custo discreto. O nível 5 diz para utilizar o que já está instalado. Cada pacote que um agente adiciona por iniciativa própria é algo que terá de atualizar mais tarde e que acabará incluído em todas as imagens de contentor que criar a partir desse repositório.

O que os próprios números de benchmark do Ponytail mostram

O projeto publica dois conjuntos de resultados, e eles divergem bastante. Ambos são números publicados pelo próprio projeto. Nenhum deles resulta de um teste independente.

[
  {
    "label": "Lines of code",
    "single_shot_pct": 93,
    "agentic_pct": 54
  },
  {
    "label": "Cost per run",
    "single_shot_pct": 63,
    "agentic_pct": 20
  },
  {
    "label": "Wall clock time",
    "single_shot_pct": 74,
    "agentic_pct": 27
  }
]

A coluna de execução única vem de um modelo básico que responde a um pequeno conjunto de prompts com e sem a regra. Os valores são medianas de execuções repetidas realizadas em 13 e 17 June 2026. A coluna agêntica vem de uma sessão headless do Claude Code que edita full-stack-fastapi-template de tiangolo, um repositório real de FastAPI e React, ao longo de doze tickets de funcionalidades, com quatro execuções em Haiku 4.5. A avaliação baseia-se no git diff deixado no final.

Leia a segunda coluna. O resultado agêntico usa 54 por cento menos linhas de código, custa 20 por cento menos e demora 27 por cento menos tempo de relógio, contra 93 por cento e 74 por cento para as mesmas medidas na configuração de execução única. O README explica isso de forma honesta: o baseline de execução única é um modelo básico que "responde com várias opções e comentários", o que é fácil de superar. Quando a comparação é feita com um agente real a executar trabalho real, a vantagem diminui. Ainda assim, o resultado continua sendo real, e esse é o facto mais útil.

Há uma ressalva do próprio projeto, e é ela que determina se isto será útil para si. A poupança é maior quando existe um risco real de implementar mais do que o necessário e é quase nula em código que já era mínimo. Doze tickets num único repositório Python e TypeScript não permitem prever o comportamento no seu repositório. Se este número for importante para si, execute a comparação nos seus próprios tickets, com e sem a regra, e conte as linhas pessoalmente.

O padrão que pode copiar hoje sem instalar nada

A escada é texto, por isso não precisa do plugin para aplicar a ideia. Cole um bloco como este no ficheiro de instruções que o seu agente já lê, seja AGENTS.md, CLAUDE.md ou o ficheiro de regras do seu editor.

## Before you write code

Climb this list in order. Stop at the first line that applies.

1. Does this need to exist? If not, say so and stop.
2. Does this repo already have it? Reuse the helper.
3. Does the standard library do it? Use it.
4. Does the platform do it natively? Use it.
5. Does an installed dependency do it? Use it.
6. Can it be one line? Write one line.
7. Otherwise write the minimum that works.

Never take the shortcut on: reading the code before changing it, validating
input that crosses a trust boundary, error handling that would otherwise lose
data, security, accessibility, or anything I asked for by name.

Do not add an abstraction I did not ask for. Do not add a dependency without
saying why in one line. Prefer deleting code to adding it.

Mark a deliberate simplification with a comment naming its ceiling and the
upgrade path.

Vale a pena analisar esta última regra isoladamente. A convenção do Ponytail é um comentário identificado com o nome da ferramenta:

# ponytail: global lock, per-account locks if throughput matters

O comentário requer duas linhas de trabalho e resolve uma questão que, de outra forma, consumiria um ciclo de revisão. Informa o leitor seguinte de que a versão simples foi uma decisão e indica a condição em que essa decisão deixa de ser válida. Sem ele, um revisor não consegue distinguir um atalho ponderado de algo que o agente esqueceu, por isso tem de perguntar.

O local onde coloca o bloco é tão importante como o conteúdo. Um ficheiro que o agente carrega em todas as execuções influencia todas as execuções, incluindo aquelas que não está a acompanhar. Essa diferença é o tema de escrever um AGENTS.md que o seu agente realmente segue, e é a razão pela qual este padrão deve ficar num ficheiro versionado, e não no histórico da shell. Num monorepo, deve ficar em mais do que um ficheiro versionado, porque um AGENTS.md por pacote mantém as regras de cada diretório curtas, em vez de obrigar o agente a ler as convenções de toda a árvore em cada execução. A localização não é uma garantia, porém, e vale a pena saber por que motivo um agente ignora uma regra que já carregou antes de concluir que a escada precisa de uma formulação mais rigorosa.

Onde a regra deixa de ser adequada

A escala foi ajustada para trabalhar em funcionalidades de uma base de código existente, onde normalmente há reutilização disponível e correta. Ela se adapta mal a um projeto greenfield, porque o nível 2 não tem nada para reutilizar e o nível 5 não tem nada instalado. Assim, o agente cai sempre no nível 7. Ela também se adapta mal quando você realmente quer uma abstração. Se estiver prestes a adicionar o quarto chamador do mesmo bloco copiado, o "diff mais curto" dará a você uma quinta cópia.

O nível ultra questionará seus requisitos. É para isso que o nível existe, e esse é um custo real quando você já tomou a decisão e quer que o trabalho seja feito. Use full no trabalho comum e recorra a ultra quando suspeitar que o pedido de funcionalidade é o problema.

Nenhum bloco de instruções evita uma interpretação errada do problema. O primeiro item do próprio conjunto de regras é entender o código antes de decidir. Essa é a parte mais cara e a parte que o texto não pode fazer por você. Um diff mínimo na função errada continua sendo a correção errada. Agora ele é uma correção errada pequena e fácil de aprovar.

O resumo honesto é que Ponytail é um prompt cuidadosamente escrito, bem distribuído e acompanhado de números. Nada nele exige o plugin. O que o projeto oferece é o fato de alguém ter escrito a lista corretamente, testado o método em um repositório real e publicado o método junto com o resultado.

FAQ

O Ponytail funciona com agentes além do Claude Code?

Sim. É distribuído como uma skill para hosts que carregam skills, uma lista que inclui Claude Code, Codex, OpenCode, Gemini e vários outros indicados no README. Editores que leem ficheiros de regras, mas não carregam skills, como Cursor, Windsurf, Cline e Copilot, usam o conjunto de regras sempre ativo do diretório de regras correspondente e não recebem comandos de barra. O texto é o mesmo nos dois casos. A diferença real é saber se o host mantém esse texto no contexto em cada turno ou apenas quando uma skill é acionada.

Um agente preguiçoso vai ignorar testes, validação ou segurança?

Não. O conjunto de regras afirma isso diretamente. A lista de aspetos que nunca devem ser tratados com preguiça inclui a validação de entradas nos limites de confiança, o tratamento de erros que evita perda de dados, a segurança e a acessibilidade. Também pede uma verificação pequena e executável para cada parte de lógica não trivial. A regra remove estruturas inventadas: abstrações que ninguém pediu e dependências de que ninguém precisava. Se o agente começar a remover testes depois da instalação, a causa é outra instrução da sua própria configuração que tem precedência sobre esta. Nesse caso, leia o ficheiro que o agente carrega por último.

Os números publicados de velocidade e custo são fiáveis?

São medições do próprio projeto, publicadas com o respetivo método, e devem ser interpretadas dessa forma. Os valores de execução única comparam o resultado com um modelo simples que responde com opções e comentários. O próprio README identifica esse modelo como uma referência fraca. Os valores agentic resultam de uma sessão headless do Claude Code num repositório FastAPI e React, com doze tickets e quatro execuções por ticket, usando Haiku 4.5. São números honestos para essa configuração. Não são uma previsão para a sua base de código, porque o projeto também afirma que a poupança tende para zero em código que já era mínimo.

Preciso de instalar alguma coisa para obter o benefício?

Não. A ladder é texto, e colar um bloco equivalente no ficheiro de instruções que o seu agente já lê produz a maior parte do efeito. O plugin fornece o texto mantido, os níveis de intensidade, os comandos de revisão e um processo de atualização. Experimentar primeiro o bloco copiado é a resposta de rung 1 à questão de saber se a instalação precisa de existir.

Como impeço um agente não supervisionado de construir demasiado durante a noite?

Coloque a regra no ficheiro de instruções sempre ativo, e não numa mensagem de chat. Assim, aplica-se no turno 200 de uma execução longa, e não apenas no turno 3. Depois, limite o impacto separadamente: forneça ao agente um checkout que ele possa danificar em vez da sua única cópia e exija uma revisão humana do diff antes de qualquer merge. Uma regra de diff mínimo reduz a quantidade de alterações que precisa de ler. Não decide o que entra, nem deve decidir.