Ponytail ou suas próprias regras no AGENTS.md: qual a diferença na prática?

Você passou meses lapidando um arquivo de regras que finalmente faz o agente parar de super-construir, e aí a timeline inteira instala o Ponytail no mesmo dia 🙂

A pergunta que sobra é bem específica: vale trocar o que já funciona por um ruleset pronto de minimalismo? Esse comparativo entre o Ponytail e as suas próprias regras olha três coisas que decidem na prática: custo de manutenção, consistência entre projetos e a mecânica de injeção das regras (quando elas entram no contexto do agente, e quantas vezes)

O que cada caminho realmente é

O Ponytail é um ruleset de minimalismo, baseado em YAGNI, mantido no repositório DietrichGebert/ponytail pelo DietrichGebert

O núcleo dele é uma escada de decisão de seis degraus, onde o agente para no primeiro degrau que resolve a tarefa:

1. pular (YAGNI)
2. usar a stdlib
3. usar recurso nativo da plataforma
4. usar dependência já instalada
5. resolver em uma linha
6. só então escrever o mínimo que funciona

Sacou a lógica? Não é "escreva pouco código", é "prove que precisa escrever alguma coisa antes de escrever"

E tem um detalhe que eu acho o mais inteligente do conjunto: quando o agente simplifica de propósito, a regra manda deixar um comentário ponytail: nomeando o teto daquela solução e o caminho de upgrade

Ou seja, a gambiarra consciente fica documentada como gambiarra consciente, com a saída anotada

O ruleset também lista exceções explícitas ao minimalismo, e isso importa MUITO pra não virar desculpa de código porco: não vale ser preguiçoso quanto a entender o problema, validação de entrada em fronteiras de confiança, tratamento de erro que evita perda de dados, segurança, acessibilidade e o que foi pedido explicitamente

Formação Recomendada

Formação Vibe Coding

Do Prompt ao Produto: Crie Software Real com IA

• 474 aulas
• 20 projetos
• 39h 27min

Conhecer formação

E a terceira via, que quase ninguém comenta:

Existe um caminho no meio, que é copiar SÓ o texto das regras

O repositório publica um AGENTS.md na raiz, além de arquivos de regras por editor em .cursor/rules/, .windsurf/rules/ e .clinerules/

O mapa completo de portabilidade fica em docs/agent-portability.md

Esse caminho é chamado de instruction-only: o ruleset fica always-on pelo arquivo de instruções do host, e você abre mão de comandos, hooks e troca de modo

O comportamento central vive em skills/ e os arquivos específicos de cada host são adaptadores, com instalação documentada pra Claude Code, Codex, Gemini CLI, Copilot CLI, Grok e opencode, entre outros

E aqui vale marcar uma diferença pra não te confundir lá na frente: a lista de instalação documentada cita o Codex, enquanto a lista de editores que ficam no caminho instruction-only cita a extensão Codex do VS Code

São entradas diferentes na documentação de portabilidade, então confere em qual das duas o teu setup se encaixa antes de escolher o caminho

Reinjeção a cada turno x carregamento no início da sessão

Aqui mora a diferença técnica que muda o comportamento no dia a dia, e não é sobre o texto das regras: é sobre QUANDO elas entram

No Claude Code, o Ponytail é instalado como plugin por dois comandos de marketplace:

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

Esse plugin roda dois hooks de ciclo de vida em Node.js

O primeiro é o UserPromptSubmit, que dispara o hooks/ponytail-mode-tracker.js e reinjeta o ruleset a cada turno, no nível ativo

O segundo é o SubagentStart, que dispara o hooks/ponytail-subagent.js e mantém o ruleset ativo quando o Claude Code abre subagentes

Tome cuidado com um pré-requisito bobo que derruba muita gente: os hooks são Node.js, então o node precisa estar disponível no PATH, inclusive no PATH do shell não interativo (o clássico caso de quem usa Nix ou nvm)

O plugin ainda registra os comandos de intensidade: /ponytail lite, /ponytail full, /ponytail ultra e /ponytail off, sendo full o padrão

E /ponytail sozinho reporta o nível ativo em vez de resetá-lo, o que é um cuidado de usabilidade bem pensado

Além do SKILL.md principal em skills/ponytail/, o plugin traz as skills auxiliares ponytail-audit, ponytail-debt e ponytail-gain

E do outro lado, o seu arquivo de regras:

No Claude Code, o CLAUDE.md é carregado na janela de contexto no início de toda sessão, e consome tokens junto com a conversa

Ele é carregado por inteiro, independentemente do tamanho, mas a documentação é explícita num ponto: arquivos mais curtos produzem melhor aderência

E aquela ideia de quebrar tudo em imports @caminho pra "economizar contexto"? Organiza, sim, mas os arquivos importados carregam no launch, então o custo de contexto continua ali

A hierarquia é a de sempre: escopo de projeto no repo (CLAUDE.md na raiz e .claude/ dentro do repo) e escopo global em ~/.claude/, valendo pra todos os projetos

Um aviso importante pra quem já padronizou tudo em AGENTS.md: o Claude Code não usa esse arquivo como memória por padrão

Existem caminhos específicos pra trazê-lo: com CLAUDE_CODE_NEW_INIT=1 o /init também lê AGENTS.md, .devin/rules/, .windsurf/rules/ ou .windsurfrules e .clinerules

E o /import anexa uma cópia única de arquivos de instrução como o AGENTS.md ao CLAUDE.md correspondente

Se esse ponto é o seu problema real, eu já detalhei em outro post a ideia de manter um só arquivo de regras pra Claude Code e Codex

Uma honestidade necessária aqui: a documentação afirma o carregamento no início de cada sessão, e não fala em reinjeção por turno

Então a comparação justa é essa: o plugin reinjeta a cada turno por hook, o arquivo próprio entra na sessão e segue a vida junto com o resto do contexto

Ponytail x suas próprias regras: comparativo linha a linha

Os números do Ponytail e a crítica das sete palavras

Agora a parte que separa hype de evidência, e essa história é boa demais pra resumir em uma linha

O benchmark oficial revisado aponta cerca de 54% menos código, média em 12 tarefas de feature (Haiku 4.5, n=4) num repo real FastAPI + React, contra o mesmo agente sem a skill

E o mais interessante é a distribuição: chega a 94% onde o agente super-constrói, e fica perto de zero onde o código já é mínimo

Ou seja, o ganho não é mágica, é corte de excesso… onde não tem excesso, não tem o que cortar

O mesmo benchmark reporta 22% menos tokens, 20% menos custo e 27% mais rápido, nas medianas das 12 tarefas

De onde veio o número de 94% que todo mundo repetiu:

A manchete original era 94%, e ela caiu por mérito do próprio mantenedor

A medição original comparava contra um chat model puro, que enche a resposta de prosa e de implementações alternativas

Depois da crítica de um contribuidor, o mantenedor achou o problema, refez o benchmark e trocou a manchete de 94% pelo número defensável de ~54%

Isso pra mim vale mais que o número em si: projeto que corrige o próprio benchmark em público ganha pontos

E tem a crítica que dói de propósito: Colin Eberhardt, CTO da Scott Logic, mostrou que trocar o Ponytail por sete palavras ("Follow YAGNI principles, and one-liner solutions") bateu o score do Ponytail no benchmark ORIGINAL

A mesma análise apontou que, sob um repositório de 6.232 linhas, havia cerca de 100 linhas de markdown reafirmando YAGNI

Vale o asterisco honesto: esse teste rodou contra o benchmark original, que depois foi corrigido, então ele não é uma comparação com o número atual

Mas o recado continua de pé pra quem já tem arquivo próprio: uma instrução curta e sua, bem colocada, não é um adversário fraco

E a adoção?

O repositório foi criado em 12 de junho de 2026, e juntou cerca de 44.000 estrelas e mais de 2.100 forks em menos de 9 dias

Hoje ele é um dos repositórios mais estrelados da categoria de skills pra agentes, com cerca de 106 mil estrelas segundo o agregador SkillsLLM em agosto de 2026 (número vivo, muda todo dia)

Quando cada opção faz mais sentido

Agora o que interessa: qual caminho pro SEU cenário

• Muitos projetos e vários agentes diferentes: plugin ou instruction-only, pela consistência. O comportamento central é o mesmo e os arquivos por host são adaptadores, então você para de manter cinco versões da mesma filosofia
• Um único repo com regras já afinadas ao domínio: arquivo próprio, sem dúvida. Suas regras sabem coisas que nenhum ruleset genérico sabe, tipo o padrão de erro da sua base e as manias do seu time
• Time que precisa afrouxar o minimalismo por fase do projeto: plugin, por causa dos níveis. Protótipo em ultra, entrega em full, e off quando a fase pede outra coisa
• Editor que não roda skills: instruction-only é o caminho documentado pra Cursor, Windsurf, Cline, Kiro, Antigravity, Aider e a extensão Codex do VS Code. O ruleset fica always-on, mas você perde comandos, hooks e troca de modo
• Ambiente sem node no PATH: o plugin depende de Node.js pros dois hooks, então instruction-only ou arquivo próprio evitam a dor de cabeça
• O caso híbrido (meu favorito): puxar a escada de seis degraus e o comentário ponytail: pra dentro do seu arquivo, sem instalar nada. Você fica com o melhor pedaço da ideia e com o texto sob seu controle

O que eu penso sobre terceirizar a decisão para um ruleset

Todo dia eu recebo mensagem de gente pedindo que eu decida por ela: qual a melhor linguagem, qual faculdade de TI fazer, se vai pro front ou pro back, onde tem mais vaga de Java

Eu não me incomodo em ajudar, de verdade

Mas quem SEMPRE pergunta vai criando um nível alto de dependência, e perde a capacidade de decidir sozinho na própria carreira

Instalar ruleset pronto é a mesma dinâmica, só que em forma de arquivo

É conveniência, e conveniência é ótima… só não é isenção de critério

O risco real não é o Ponytail estar errado (a escada de seis degraus é boa), é você virar o dev que só executa o que o ruleset mandou, sem saber por que aquele degrau existe

A minha recomendação de sempre vale aqui: testa e experimenta na prática

Abre o editor, roda um projeto de verdade com o ruleset ligado, roda o mesmo tipo de tarefa com as suas regras, e vê o que funciona, o que te agrada e o que não te agrada

Entender como as coisas se correlacionam antes de escolher é diferente de aceitar a escolha pronta de outra pessoa

Ter preferência é normal e é aceitável, beleza? O que importa é a opinião ser formada pela SUA experiência

E tem o outro lado da moeda: quem decide assume as rédeas do próprio destino, e responde pelos próprios atos

Decidir sozinho vira hábito, e as decisões vão melhorando com o tempo

Quem estuda os pontos positivos e negativos e decide sozinho evolui mais do que quem só seguiu o que um influenciador falou

No vídeo abaixo eu falo exatamente sobre isso, e o argumento serve tanto pra escolha de carreira quanto pra escolha de ferramenta:

Veredito: vale trocar as suas próprias regras pelo Ponytail?

Sem ficar em cima do muro, vamo lá

Se você já tem arquivo próprio funcionando: não troque

O ganho em substituir é pequeno, e o ganho em roubar as duas melhores ideias é grande: a escada de decisão de seis degraus e o comentário ponytail: nomeando teto e caminho de upgrade

Esse comentário sozinho já vale a leitura do repo, porque ele resolve o problema de "por que essa solução é assim?" seis meses depois

Se você quer consistência entre muitos projetos e cobertura de subagentes: o plugin ganha

A reinjeção a cada turno pelo UserPromptSubmit e o SubagentStart cobrindo subagentes fazem um trabalho que arquivo de memória não faz, e os níveis lite, full, ultra e off te dão um botão que texto estático não tem

Se você odeia depender de plugin e de runtime: instruction-only

Você fica com o ruleset always-on, sem node no PATH e sem hook, aceitando perder comandos e troca de modo

Pra quem NÃO vale: quem tem um repo pequeno, com código já enxuto, e espera ver os 54% aparecerem

O próprio benchmark diz que o ganho fica perto de zero onde o código já é mínimo, então o que você vai colher é mais regra no contexto e pouca mudança no resultado

E também não vale pra quem quer instalar e nunca mais olhar: regra que você não leu é regra que você não sabe desligar quando ela atrapalhar

Conclusão

A escolha entre o Ponytail e o seu próprio arquivo de regras não é briga de time: é escolher entre um ruleset mantido por outra pessoa, com hooks e níveis, e um texto seu que carrega no início da sessão e que você controla linha a linha

O próximo passo prático é bem simples

Lê o AGENTS.md da raiz do repositório do Ponytail ANTES de instalar qualquer coisa, porque a leitura leva minutos e já te entrega a escada de seis degraus e as exceções ao minimalismo

Depois escolhe um projeto de teste, roda uma tarefa de feature com o ruleset e compara com o que as suas regras atuais já produzem hoje

Aí a decisão deixa de ser sobre estrela no GitHub e passa a ser sobre o SEU código 😀

até o próximo post!