Ponytail: regras para agentes de código escreverem menos

O que é o Ponytail

O Ponytail é um conjunto de regras que faz um agente de programação com IA escrever menos código. O projeto descreve-se numa linha: "Faz o seu agente de IA pensar como o programador sénior mais preguiçoso da sala. O melhor código é aquele que nunca escreveu." É licenciado 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 as carregam.

O repositório é DietrichGebert/ponytail. Foi criado em 12 June 2026 e ultrapassou 90,000 stars em 1 August 2026. Em 1 August 2026, a versão mais recente com tag era v4.8.4, publicada em 29 June 2026, e a página de releases listava dez tags apenas entre 14 e 29 June. O ritmo não abrandou: em 17 October 2026, a release mais recente é v5.3.2, publicada no fim de 16 October, a terceira release desse dia depois de v5.3.0 e v5.3.1. Antes disso veio v5.2.0 em 13 October, cinco dias depois de v5.0.0 e v5.1.0 terem sido lançadas, ambas em 8 October, e o repositório mostra mais de 165,000 stars. Um projeto que avança a esse ritmo terá mudado quando ler este texto, por isso fixe uma tag antes de criar qualquer coisa sobre ele.

A ideia antes da ferramenta: parar 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-o.
2. Isto já existe nesta base de código? Reutilize o helper ou o padrão que já existe.
3. A biblioteca padrão faz isto? Use-a.
4. Uma funcionalidade nativa da plataforma resolve o problema? Use-a.
5. Uma dependência já instalada resolve o problema? Use-a.
6. Pode ser uma linha? Faça-o numa linha.
7. Só depois escreva o código mínimo que funciona.

Essa é a escada tal como está definida em v4.8.4, e os números dos degraus no restante deste artigo seguem essa definição. A branch principal atual combina os degraus 3 e 4 num só, "Biblioteca padrão ou funcionalidade da plataforma? Use-a, a menos que o projeto tenha a sua própria", e acrescenta que "um componente da casa é melhor do que um widget nativo", ficando assim com seis degraus. A ordem é a mesma.

É a ordem que faz o trabalho, não um degrau isolado. Se for pedido a um agente um seletor de datas, ele escreverá um seletor de datas, porque foi isso que lhe pediram. A escada obriga-o a verificar o que já existe antes de construir qualquer coisa: o degrau 2 pergunta se o repositório já tem um componente para isso, e o degrau 4 indica que o browser já fornece <input type="date">. As notas do benchmark atual do projeto registam exatamente este caso: um seletor de datas que tinha 335 linhas sem a regra passou a ter 10 linhas com o Ponytail 5, porque o agente reutilizou o componente Input do próprio repositório com type="date" e deixou o browser fornecer o calendário. Um seletor de cores diminuiu menos, de 135 linhas para 26. O degrau 2 é o que falha silenciosamente, porque um agente que não consegue ver o helper que já existe escreverá facilmente um segundo, que é precisamente a lacuna que um mapa consultável da sua base de código pretende fechar.

Aqui, ser preguiçoso não significa ser descuidado, e o conjunto de regras diz isso diretamente. A lista "nunca seja preguiçoso quanto a" inclui compreender o problema antes de decidir, validar entradas nos limites de confiança, tratar erros para evitar perda de dados, segurança, acessibilidade e tudo o que foi pedido explicitamente. Também exige uma verificação pequena e 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 disponibiliza

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

O argumento de intensidade altera a força com que a regra atua. lite constrói o que pediu e nomeia uma opção mais preguiçosa numa linha. full é o padrão e impõe a hierarquia. ultra é a configuração extremista do YAGNI: prefere a eliminação à adição e questionará o próprio requisito.

Hosts com capacidade para skills também recebem slash commands. /ponytail define o nível, /ponytail-review verifica um diff à procura de excesso de engenharia, /ponytail-audit verifica um repositório inteiro, /ponytail-debt recolhe os atalhos que adiou e /ponytail-gain imprime o cartão de pontuação de benchmark. Hosts que apenas leem ficheiros de regras recebem o conjunto de regras sem comandos. Desde o v5.3.0, lançado a 16 de outubro de 2026, o Claude Code também recebe uma barra acima do prompt que mostra o custo da tarefa, a reutilização de código e o estado dos testes. Requer o Claude Code 2.1.290 ou posterior; não aparece no painel de chat do VS Code, em sessões na cloud ou no claude -p, e o /ponytail band off oculta-o. Desde o v5.3.2, o /ponytail band import lê as suas sessões anteriores do Claude Code uma vez e adiciona-as ao quadro com o respetivo custo, tempo de agente e tokens, para que as possa comparar com as sessões executadas sob a regra.

Para ler o código-fonte antes de confiar nele, clone a tag em vez do branch. Esta é a tag de onde provém a hierarquia acima; substitua pelo v5.3.2, o mais recente a 17 de outubro de 2026, para ler a redação atual:

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

No Claude Code, o projeto documenta uma instalação de plugin, e estas duas linhas estão conforme documentado a 17 de outubro de 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 entre sessões. Esse é o compromisso que aceita pela conveniência de um comando de atualização.

Por que um agente preguiçoso custa menos numa VPS

O diff escrito pelo agente não sai da conversa. Na interação seguinte, o modelo volta a lê-lo como contexto, 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 até a compactação substituir as interações antigas por um resumo, e não apenas a interação que a produziu. É 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, por isso sobra menos espaço para o seu código. Manter isto sob controlo é 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 todas as interações em que volta a ser lido. O impacto dessa poupança na fatura depende da forma de pagamento, porque uma subscrição Pro ou Max absorve os tokens adicionais apenas até aos limites de utilização. Depois disso, os créditos de utilização ativados pelo utilizador são cobrados separadamente. Na faturação da API por token, cada token é cobrado. Se estiver a acompanhar os custos numa configuração self-hosted, o ficheiro de instruções é uma alavanca que não custa nada utilizar. Controlar quanto custa um agente de IA 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 se espera.

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 é necessário não desperdiça apenas tempo. Também reduz silenciosamente a qualidade da revisão que deveria detetar os erros.

Num servidor, os riscos são diferentes, 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 ser detetado. Esse é o risco prático de executar um agente de programação numa VPS, e é por isso que quem trabalha com engenharia de ciclo dedica tanta atenção às instruções permanentes, em vez de se concentrar apenas nos prompts individuais. Uma regra no ficheiro sempre ativo aplica-se à interação 200. Uma regra escrita no chat aplica-se à interação 3. Também se aplica à segunda sessão iniciada no mesmo servidor, que lê o ficheiro versionado, mas não herda nada do que foi escrito na primeira, mesmo quando as duas sessões podem trocar mensagens.

As novas dependências são outro custo silencioso. A regra 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 acaba incluído em todas as imagens de contentor criadas a partir desse repositório.

O que dizem os números do próprio benchmark do Ponytail

O projeto publicou dois tipos de resultados e eles divergem significativamente entre si. Ambos são números publicados pelo próprio projeto. Nenhum é um teste independente.

[
  {
    "label": "Lines of code",
    "v4_13_pct": 48,
    "v5_pct": 53
  },
  {
    "label": "Cost per run",
    "v4_13_pct": 16,
    "v5_pct": 26
  },
  {
    "label": "Wall clock time",
    "v4_13_pct": 38,
    "v5_pct": 41
  }
]

O gráfico é o benchmark agentic atual do projeto, datado de 7 de outubro de 2026. Sessões do Claude Code 2.1.288 headless no Opus 5.5 com esforço padrão processaram 39 tarefas, cinco execuções por tarefa e braço, 585 sessões no total entre sem skill, Ponytail v4.13.0 e Ponytail 5. Doze das tarefas são tickets de funcionalidades no full-stack-fastapi-template do tiangolo, um repositório real de FastAPI e React, pontuado com base no git diff resultante. O resto são 18 tarefas cirúrgicas com verificações ocultas, seis pedidos de pequenas aplicações e três pedidos do tipo "mostra-me um exemplo". O Bash foi desativado para todos os braços. Os tokens de saída caíram 45 por cento com o Ponytail 5.

Compare isto com os números de "single shot" que o projeto publicou em junho de 2026. Esses vieram de um modelo base a responder a cinco prompts do dia a dia com e sem a regra, reportados como medianas de execuções repetidas. Mostraram 80 a 94 por cento menos código no Haiku, Sonnet e Opus, e a verificação de custos datada de 17 de junho de 2026 colocou o Haiku 63 por cento mais barato. O resultado agentic atual para o Ponytail 5 é 53 por cento menos linhas de código, 26 por cento menos custo e 41 por cento menos tempo de relógio. O projeto corrigiu rapidamente o número de "single shot". A v4.8.4, a 29 de junho de 2026, o README já destacava o resultado agentic, "~54% menos código (até 94%)", com uma nota de que os 80 a 94 por cento anteriores eram "o teto por tarefa, não a média", e tinha movido os números de "single shot" para uma secção colapsada intitulada "Números antigos de single-shot". Essa secção era honesta sobre a razão da existência da lacuna: a linha de base de "single shot" é um modelo base que "enche a sua resposta com prosa e opções", o que é algo fácil de superar. Meça contra um agente real a fazer trabalho real e a vantagem diminui. Também permanece real, o que é o facto mais útil. Essa execução agentic de junho, doze tickets no Haiku 4.5 com quatro execuções cada, tinha ficado próxima do número de hoje, com 54 por cento menos linhas, e o README atual já não contém os números de "single shot".

Uma ressalva é a do próprio projeto, e é ela que decide se isto o ajuda. A poupança é maior onde existe uma armadilha genuína de construção excessiva e quase zero em código que já era mínimo, e a tabela por tarefa de outubro confirma isso, com várias tarefas cirúrgicas a terminarem com a mesma contagem de linhas nos três braços. Trinta e nove tarefas num modelo e num host, com o Bash desligado, não preveem o seu repositório. Se o número for importante para si, execute a comparação nos seus próprios tickets, com e sem a regra, e conte as linhas você mesmo.

O padrão que pode copiar hoje sem instalar nada

A escada é texto, por isso não precisa do plugin para usar 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.

Essa última regra merece ser analisada isoladamente. A convenção do Ponytail nas versões atuais é um comentário marcado com shortcut: que indica o limite e quando fazer a atualização (nas versões de junho, incluindo v4.8.4, a marcação era ponytail:):

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

O comentário representa duas linhas de trabalho e resolve uma questão que, de outro modo, consumiria um ciclo de revisão. Informa o próximo leitor 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 seu conteúdo. Um ficheiro que o agente carrega em todas as execuções orienta todas as execuções, incluindo as 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 de 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, contudo, 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 forte.

Quando a regra deixa de funcionar

A hierarquia foi ajustada para trabalho de desenvolvimento numa base de código existente, onde normalmente é possível reutilizar código e essa reutilização costuma ser adequada. Adapta-se pior 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. O agente ainda pode parar no nível 1, na biblioteca padrão, numa funcionalidade da plataforma ou numa solução de uma linha, mas desaparecem duas das opções mais baratas. Por isso, mais tarefas acabam por exigir código novo. Também se adapta mal ao momento em que realmente pretende criar a abstração. Se está prestes a adicionar o quarto utilizador do mesmo bloco copiado, o "diff mais curto" entrega-lhe uma quinta cópia.

O nível ultra vai questionar os seus requisitos. É essa a finalidade do nível, e isso representa um custo real quando já tomou a decisão e quer que o trabalho seja feito. Use full para trabalho normal e recorra a ultra quando suspeitar que o pedido de funcionalidade é o problema.

Nenhum bloco de instruções o protege de interpretar mal o problema. O primeiro item do próprio conjunto de regras é compreender o código antes de decidir. Essa é a parte dispendiosa e a parte que o texto não pode fazer por si. Um diff mínimo na função errada continua a ser a correção errada. Agora é apenas 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 fornece é uma lista escrita corretamente por alguém, testada num repositório real e publicada juntamente com o resultado.

FAQ

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

Sim. É disponibilizado como uma skill para hosts que carregam skills, incluindo Claude Code, Codex, OpenCode, Gemini e vários outros indicados no README. Os 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 seu 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 sobre os quais nunca deve ser preguiçoso 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 seu agente começar a remover testes depois de o instalar, a causa é outra instrução da sua própria configuração que tem prioridade sobre esta. Leia o ficheiro que o agente carrega por último.

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

São as medições do próprio projeto, publicadas com o respetivo método, e devem ser interpretadas dessa forma. Os valores de execução única de June 2026 foram comparados com um modelo básico que acrescentava prosa e opções à resposta. O próprio README identificava esse modelo como uma referência fraca na altura. Os valores agentic atuais resultam de sessões headless do Claude Code no Opus 5.5, com 39 tarefas e cinco execuções por tarefa. Doze dessas tarefas eram feature tickets num único repositório FastAPI e React. São números honestos para essa configuração. Não são uma previsão para a sua base de código, porque os resultados por tarefa do próprio projeto mostram que a poupança cai para perto de zero em código que já era minimalista.

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

Não. A ladder é texto. 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 caminho de atualização. Experimentar primeiro o bloco copiado é a resposta de rung 1 à questão de saber se a instalação precisa sequer de existir.

Como impeço um agente sem supervisão 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: dê 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 o que tem de ler. Não decide o que entra, nem deve decidir.