Cauda de cavalo: trate a “doença do overengineering” do seu AI Agent — menos 54% de código na prática

Repositório: https://github.com/DietrichGebert/ponytail

De baixa dificuldade: em 10 minutos você aprende, em 1 hora já roda seu primeiro benchmark. Trate, na prática, o seu hábito de o código do seu AI “não saber parar” na hora de escrever.

Introdução

Você já passou por algo assim? — Pedir a um Claude Code para criar um seletor de datas. Ele, muito sério, instala flatpickr, escreve um componente wrapper, adiciona um pouco de CSS, começa a discutir com você sobre tratamento de timezone… e no fim ele te entrega 287 linhas.

O que você queria era dizer: “Quero um input que selecione datas”. E ele entregou: “Um framework para selecionar datas”.

É isso que é a “doença do overengineering” de um AI Agent: o modelo foi treinado para “parecer profissional”, então ele automaticamente adiciona abstrações, itens de configuração, tratamento de erros, cobertura de testes… quando talvez o que você precisava era apenas um <input type="date">.

Ponytail existe para curar esse problema. Ele foi open-source por Dietrich Gebert e sua ideia central cabe em uma frase: “O melhor código é aquele que nunca foi escrito.”

Ponytail não é um modelo, nem um plug-in de IDE. É um conjunto de regras no estilo de “engenheiro sênior preguiçoso”. Ele coloca uma escada de 6 degraus no seu AI:

1. Isso precisa ser escrito mesmo?          → Não precisa: pule (YAGNI)
2. Dá para fazer com a biblioteca padrão? → Use-a
3. Dá para fazer com recursos nativos da plataforma? → Use-os
4. Dá para fazer com dependências já instaladas? → Use-as
5. Dá para fazer em uma linha?             → Faça em uma linha
6. Se ainda assim não der: escreva o menor código que atende ao requisito

Nos experimentos comparativos reais em tiangolo’s full-stack-fastapi-template, com 12 tickets de feature, n=4 e Haiku 4.5, o Ponytail obteve este resultado:

O Ponytail é a única solução em que todos os indicadores caem — e também a única em que cortar código não perde segurança. Um seletor de cores de 287 linhas vai para 23, e um seletor de datas de 404 linhas vai para 23 — porque ele usa diretamente o <input type="color"> e o ` nativos do navegador.

Ele é compatível com 14 ferramentas de programação com AI: Claude Code, Codex, Cursor, Windsurf, Cline, Copilot CLI, Aider, Kiro, Zed, CodeWhale, OpenCode, Pi, Gemini CLI e OpenClaw. Hoje, vamos colocar essas regras dentro do Claude Code e curar seu “overengineering disease” em 30 segundos.

Público-alvo

• Desenvolvedores com 1–5 anos que usam AI Agents para escrever código no dia a dia
• Achar “o código com AI fica grande demais e vem com um monte de dependências que não serão usadas”
• Querer padronizar o estilo da equipe, mas sem travar o time com regras ESLint engessadas
• Donos/Tech Leads que se preocupam com o custo de programação com AI — e que sentem dor no token bill

Dependências e ambiente

• Node.js 18+ (obrigatório: os hooks de lifecycle do Ponytail rodam com Node; usuários nvm: garantam que isso esteja no PATH de um shell não interativo)
• Um AI Agent suportado (para demonstração, Claude Code)
• Uma chave de API de LLM (para demonstração, usando a Claude Haiku 4.5 do Defapi, com metade do preço)
• Opcional: Python 3.10+ (usado ao rodar o benchmark com pandas)
• Opcional: Git (para clonar o repositório)

Estrutura completa do projeto

ponytail/
├── AGENTS.md                  # Regras centrais (a “filosofia de preguiçoso” lida por todos os agents)
├── README.md / README.es.md   # README em inglês + português/espanhol em três idiomas
├── package.json               # definição do pacote pi-agent
├── commands/                  # 6 comandos slash
│   ├── ponytail.toml          # /ponytail [lite|full|ultra|off]
│   ├── ponytail-review.toml   # /ponytail-review (corta o diff atual)
│   ├── ponytail-audit.toml    # /ponytail-audit (varre o repositório inteiro)
│   ├── ponytail-debt.toml     # /ponytail-debt (cobrança: ponytail: comentários)
│   ├── ponytail-gain.toml     # /ponytail-gain (ver o desempenho no benchmark)
│   └── ponytail-help.toml     # /ponytail-help
├── skills/                    # 6 imagens de skill
│   ├── ponytail/              # regras principais
│   ├── ponytail-review/ ...   # as outras 5
├── hooks/                     # hooks de lifecycle do Claude / Codex
│   ├── ponytail-config.js     # parsing de modo (env + config.json)
│   └── ponytail-instructions.js
├── ponytail-mcp/              # adaptação do servidor MCP (para hosts apenas com MCP)
│   ├── index.js
│   ├── instructions.js
│   └── test/
├── examples/                  # 12 comparações reais “overengineering vs uma linha”
│   ├── date-picker.md / color-picker.md（web embutido）
│   ├── deep-clone.md（structuredClone）
│   ├── debounce.md
│   ├── email-validation.md（75 linhas → 3 linhas）
│   └── ... 12 ao todo
├── benchmarks/                # promptfoo + benchmarks agentic
│   ├── promptfooconfig.yaml   # baseline de turno único
│   ├── benchmark-local.py     # benchmark agentic real do repositório
│   ├── agentic/               # scripts de 12 tickets
│   └── results/2026-06-18-agentic.md  # dados completos
├── docs/
│   ├── agent-portability.md   # qual agent instala qual arquivo
│   └── platform-native.md
├── .openclaw/                 # skill de adaptação para OpenClaw（gerada automaticamente）
├── .cursor/ .windsurf/        # arquivos de regras do Cursor / Windsurf
├── .clinerules/               # regras do Cline
├── .kiro/steering/            # regras do Kiro
└── tests/                     # testes de consistência das regras

---

Tutorial passo a passo

Passo 1: Instale Ponytail no Claude Code

No Claude Code, Ponytail é um plugin marketplace — resolve tudo em 30 segundos.

# Adiciona o repositório do Ponytail à lista de plugin marketplace
/plugin marketplace add DietrichGebert/ponytail

# Instala a skill principal (uma vez por sessão)
/plugin install ponytail@ponytail

Depois de instalar, abra uma nova sessão. O texto de startup exibirá o modo atual (padrão full). Você verá algo como isto:

Ponytail v0.1.0  [full]  Lazy senior dev mode active
1. Need to build?  2. Stdlib?  3. Platform?  4. Installed dep?
5. One line?       6. Minimum that works.

Se você quiser trocar a intensidade, digite:

/ponytail lite     # modo leve (protege 1–2 degraus)
/ponytail full     # padrão
/ponytail ultra    # modo agressivo (não deixa nem uma camada de abstração)
/ponytail off      # desligar
/ponytail          # sem parâmetros = mostra o modo atual

Você também pode persistir:

# padrão permanente ultra
export PONYTAIL_DEFAULT_MODE=ultra

Ou criar um arquivo de config:

// ~/.config/ponytail/config.json
// Windows: %APPDATA%\ponytail\config.json
{ "defaultMode": "ultra" }

Passo 2: Rode uma comparação com um contraexemplo

Vamos direto ao efeito. Prepare dois prompts totalmente iguais:

Prompt A (desligue Ponytail)：primeiro /ponytail off e depois pergunte:

Add a color picker to the settings page

Você receberá uma resposta com cerca de 287 linhas: instala um react-color ou cria um componente de 5 arquivos, adiciona validação de props, usa throttling no onChange, cria label para acessibilidade, adiciona variáveis CSS.

Prompt B (ligue Ponytail)：primeiro /ponytail full e depois repita a mesma pergunta.

Você vai receber:

// ponytail: browser has one
<input type="color" />

Uma linha. Pronto.

O AGENTS.md do Ponytail já traz essa regra central (trecho original):

Before writing any code, stop at the first rung that holds:
1. Does this need to be built at all? (YAGNI)
2. Does the standard library already do this? Use it.
3. Does a native platform feature cover it? Use it.
4. Does an already-installed dependency solve it? Use it.
5. Can this be one line? Make it one line.
6. Only then: write the minimum code that works.

Note a última linha: “Only then” — não é que ele não te deixa escrever, ele só quer que você percorra os 5 primeiros degraus antes.

Passo 3: Use Defapi para economizar metade dos tokens

O Ponytail corta quantidade de código, mas para rodar o AI Agent em si você precisa queimar tokens no Claude / GPT. Defapi fornece official meia-preço de Claude / GPT / Gemini, com interface totalmente compatível.

Vamos trocar para Defapi e rodar um benchmark:

Passo 3.1：pegue uma Defapi Key

Vá em defapi.org, registre-se e obtenha uma key que começa com dk-xxx. Coloque-a no .env do Ponytail:

# no diretório raiz do repositório ponytail
cat > .env <<'EOF'
ANTHROPIC_API_KEY=dk-uma-sua-defapi-key
ANTHROPIC_BASE_URL=https://api.defapi.org
EOF

Passo 3.2：valide usando curl direto

curl -s https://api.defapi.org/api/v1/messages \
  -H "Authorization: Bearer dk-uma-sua-defapi-key" \
  -H "content-type: application/json" \
  -d '{
    "model": "anthropic/claude-haiku-4.5",
    "max_tokens": 256,
    "messages": [
      {"role": "user", "content": "Use um emoji para descrever a palavra ponytail"}
    ]
  }'

Resposta:

{
  "id": "msg_01H...",
  "role": "assistant",
  "content": [{"type": "text", "text": "🦄 (isso nem deveria aparecer)"}],
  "usage": {"input_tokens": 22, "output_tokens": 12}
}

Passo 3.3：faça o promptfoo usar Defapi

O Ponytail já vem com um baseline de promptfoo. Edite benchmarks/promptfooconfig.yaml:

providers:
  - id: anthropic:messages:anthropic/claude-haiku-4.5
    config:
      baseURL: https://api.defapi.org
      apiKey: ${ANTHROPIC_API_KEY}

Rode:

npx promptfoo@latest eval -c benchmarks/promptfooconfig.yaml

Economia estimada（estimativa de volume: 12 tickets do Ponytail benchmark × n=4 = 48 rodadas）：

O Ponytail reduz 20% de custo, e o Defapi reduz mais 50%. Juntos, dá para chegar a uma conta real em 4x de desconto (40%).

Passo 4: Rode /ponytail-review para cortar o diff atual

Só colocar o Ponytail no momento de escrever não basta — você já tem uma pilha de código com “overengineering” acumulado. Use o comando de review:

# em um repositório que tenha mudanças
/ponytail-review

Ele revisa apenas o diff do git atual e o formato de saída é fixo:

L12: delete unused `cache` parameter; no caller passes it
L34: stdlib Array.prototype.sort is stable since ES2019; drop `lodash.orderby`
L88: native `URLSearchParams` covers this; remove custom `parseQuery`
L102: yagni `BaseRepository` has one implementation; inline it
L150: shrink loop into `arr.filter(x => x.active).map(x => x.id)`
---
Net removable: 47 lines, 1 dependency

Sistema de tags:

• delete — código morto / feature oportunista
• stdlib — reinventar a biblioteca padrão
• native — tarefa já resolvida por dependência / funcionalidade nativa da plataforma
• yagni — camada de abstração com apenas uma implementação
• shrink — mesma lógica, menos linhas

A última linha te dá as “linhas líquidas removíveis” — e é esse o indicador quantitativo do seu tech debt.

Se a saída for Lean already. Ship., significa que seu código já está magro o bastante e dá para fazer merge com tranquilidade.

Passo 5: Rode /ponytail-audit para varrer o repositório inteiro

O review olha o diff; o audit olha a árvore inteira.

/ponytail-audit

O formato é semelhante, mas ele é ordenado por “o que dá para cortar mais”:

delete src/utils/cache.ts (412 lines) — only used in 1 place; inline
stdlib src/utils/deep-clone.ts — use structuredClone
native src/components/DatePicker/ (287 lines) — <input type="date">
yagni src/repositories/BaseRepository.ts (180 lines) — 1 impl, inline
shrink src/api/users.ts:42-78 — same logic, 60 → 18 lines
---
Net removable: 1,247 lines, 4 dependencies

Dica prática: primeiro faça review, depois audit. O review ajusta o diff; após o merge, o audit define prioridades para a próxima limpeza.

Passo 6: Ative em outros Agents

A principal vantagem do Ponytail é: “uma vez configurado, vale em todo lugar”. Ele já prepara arquivos de adaptação para cada ferramenta popular de programação com AI:

Codex（modo CLI）

codex plugin marketplace add DietrichGebert/ponytail
codex
# abra /plugins → escolha Ponytail → instale
# abra /hooks → confie em dois lifecycle hooks → abra uma nova thread

Cursor

Copie direto .cursor/rules/ponytail.mdc para dentro do seu projeto:

cp .cursor/rules/ponytail.mdc ~/your-project/.cursor/rules/

Ou globalmente:

cp .cursor/rules/ponytail.mdc ~/.cursor/rules/

Windsurf

cp .windsurf/rules/ponytail.md ~/.codeium/windsurf/memories/

GitHub Copilot CLI

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

OpenClaw（se você já usa）

# melhor comando único
clawhub install ponytail

Ou copie manualmente:

cp -r .openclaw/skills/ponytail ~/.openclaw/skills/

Gemini CLI

gemini extensions install https://github.com/DietrichGebert/ponytail

Pi / Aider / Kiro / Zed / CodeWhale

Esses agents leem diretamente AGENTS.md:

# no nível do projeto
cp AGENTS.md ~/your-project/AGENTS.md

# global (pi / Aider / CodeWhale conseguem reconhecer)
cp AGENTS.md ~/.pi/AGENTS.md

Tabela completa de compatibilidade（extraída de docs/agent-portability.md do projeto）：

Passo 7: Rode seu próprio benchmark

Os dados reais do Ponytail não são “achismo”. Eles vêm do benchmarks/benchmark-local.py. Você também pode escolher 5 tarefas reais suas e reproduzir:

Passo 7.1：prepare prompts

Edite benchmarks/prompts.json（ou use os 5 prontos）：

[
  { "id": "date-picker", "task": "Add a date picker to the settings page" },
  { "id": "color-picker", "task": "Add a color picker to the settings page" },
  { "id": "email-validate", "task": "Write a Python function that validates email addresses" },
  { "id": "deep-clone", "task": "Deep clone this object: {sample}" },
  { "id": "debounce", "task": "Write a debounce function in JavaScript" }
]

Passo 7.2：rode os três braços de comparação

# baseline: sem adicionar nada
npx promptfoo@latest eval -c benchmarks/promptfooconfig.yaml

# ponytail: braço com plugin de skill
PONYTAIL_DEFAULT_MODE=full npx promptfoo@latest eval -c benchmarks/promptfooconfig.yaml

Passo 7.3：veja os resultados

A saída fica em benchmarks/output.json, contendo para cada prompt em cada braço:

• loc — número de linhas de código
• tokens — total de tokens
• cost — dólares
• time — tempo ponta a ponta
• passed_safety — se passou nos testes de segurança (validação de entrada, tratamento de erros, a11y)

Normalmente, os braços do ponytail têm 50–80% menos LOC do que o baseline.

Passo 8: Rode ponytail-mcp（avançado）

Se o seu AI host só consegue usar MCP (por exemplo, alguns apps desktop), o Ponytail também tem um servidor MCP compatível:

cd ponytail-mcp
npm install
node index.js    # inicia o stdio MCP server

No config do host MCP, adicione:

{
  "mcpServers": {
    "ponytail": {
      "command": "node",
      "args": ["ponytail-mcp/index.js"]
    }
  }
}

Ele expõe:

• Prompt ponytail：retorna o texto das regras, com parâmetro opcional mode (lite / full / ultra)
• Tool ponytail_instructions：o mesmo de cima, mas com structuredContent, para hosts no estilo “code-execution”

---

Solução de problemas (FAQ)

Q1：instalei e não funcionou, o startup não aparece?

99% é porque o Node não está no PATH em um shell não interativo. Valide:

# isto precisa rodar em um shell novo (simulando não interativo)
bash -lc 'node -v'      # bash
zsh -lc 'node -v'       # zsh

Se retornar command not found, adicione o source do nvm em ~/.bashrc / ~/.zshrc, ou instale um Node system:

# macOS
brew install node@20

# Windows
winget install OpenJS.NodeJS.LTS

Q2："quero aquele cache de 120 linhas" — e se eu tiver exigência forte?

Duas soluções:

# desliga temporariamente
/ponytail off

# ou libera localmente: fale diretamente no prompt
"Build a 120-line cache class, ignore ponytail for this task"

Ponytail é um conjunto de regras, não uma corrente. Se o modelo receber um override explícito, ele vai obedecer.

Q3：Ponytail conflita com ESLint / Prettier?

Não conflitam: são responsabilidades diferentes：

• Ponytail：decide “devemos escrever isso?” — existe essa abstração? existe essa dependência? existe esse wrapper?
• ESLint：decide “está certo?” — nomes, estilo, variáveis não usadas
• Prettier：decide “a formatação está boa?” — indentação, ponto e vírgula, quebras de linha

Quando os três rodam juntos, o resultado é melhor. O Ponytail define “como o código deve ser” no topo; ESLint / Prettier garantem os detalhes depois.

Q4：como padronizar as regras na equipe?

AGENTS.md é um arquivo no nível do repositório. Basta commitar no git:

# na raiz do repositório da sua equipe
curl -o AGENTS.md https://raw.githubusercontent.com/DietrichGebert/ponytail/main/AGENTS.md
git add AGENTS.md
git commit -m "chore: adopt ponytail team-wide coding rules"

Todos os agents que leem AGENTS.md (CodeWhale, Aider, Zed, Pi, Kiro, Codex extension) vão obedecer automaticamente.

Q5：o Ponytail vai degradar a segurança nos testes?

Não. Isso é a métrica mais crítica do Ponytail no benchmark. Na tabela, baseline / caveman / Ponytail são 100% seguros (passam). Apenas o prompt “YAGNI + uma linha” puro cai para 95%.

No AGENTS.md do Ponytail há uma seção específica:

Not lazy about: input validation at trust boundaries, error handling that prevents data loss, security, accessibility, the calibration real hardware needs.

Tradução: preguiçoso é “onde dá”. A lógica de negócio e o empacotamento de UI podem economizar; validação de entrada, tratamento de erros como proteção, segurança e a11y não podem.

Q6：como rodar no CI?

Transforme a lógica do /ponytail-review em um script independente (o benchmarks/correctness.test.js do repositório Ponytail dá um exemplo de implementação). Depois:

# .github/workflows/ponytail.yml
name: ponytail
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: node scripts/ponytail-review.js origin/main
        env:
          ANTHROPIC_API_KEY: ${{ secrets.DEFAPI_KEY }}
          ANTHROPIC_BASE_URL: https://api.defapi.org

Falhar em PR = seu diff atual fez o Ponytail pensar “ainda dá para deixar mais magro”.

Q7：modo MCP vs modo always-on: qual eu devo escolher?

Depende do seu host:

---

Leitura extra / direções avançadas

Raiz filosófica do Ponytail

• Palestra de Rich Hickey, “Simple Made Easy”（o pai do Clojure fala sobre a diferença entre “fácil” e “simples”）
• “The Magic Tricks of Testing” de Sandi Metz（princípio para minimizar cobertura de testes）
• “Thirty Years of 'WTF'” de Ted Neward（satiriza a inflação de código corporativa）
• Outro jeito de dizer o “outro lado” dos 6 degraus: Coad’s “Just Enough Architecture”

Escreva comentários no estilo ponytail

O comentário ponytail: é um bilhete para o “desenvolvedor do futuro que vai ler esse código”. Convenção de formato:

// ponytail: <razão>，<limitação conhecida / caminho de melhoria>

Exemplo:

# ponytail: o módulo re da stdlib já serve; não precisa instalar email-validator
# Limitações conhecidas: não valida todas as edge cases do RFC 5322; se precisar suportar o caso edge de [email protected], troque para email-validator
import re
def is_valid_email(email: str) -> bool:
    return bool(re.match(r'^[^@]+@[^@]+\.[^@]+$', email))

O comando /ponytail-debt varre todos os comentários ponytail: e gera um ledger de tech debt. “later” não vira “never”.

Integrar ao fluxo de code review da equipe

Use /ponytail-review como um lint. Adicione uma linha no template do PR:

## Ponytail review
- [ ] Rodei `/ponytail-review` neste diff
- [ ] Linhas removíveis líquidas: ___
- [ ] Se > 0, justificativa: ___

Dados completos do benchmark

benchmarks/results/2026-06-18-agentic.md contém o método completo e as limitações: 12 tickets × 3 braços × 4 rodadas. Vale a pena ler — especialmente a parte de “fair agentic baseline”. Antes, a taxa de “single-turn myth” estava inflada artificialmente pela linha conversacional; 54% é o número honesto.

Sobre os limites do Ponytail

O Ponytail corta código com base na premissa de que o código está “correto”. Ele não valida:

• se a lógica de negócio está certa (isso você precisa cobrir com testes)
• se o desempenho é suficiente (o ponytail vai marcar quando houver O(n²) nos comentários, mas não vai corrigir automaticamente)
• se as bordas (edge cases) estão cobertas (os comentários lazy listam; não adicionam testes por você)

Ele é um ponto de partida, não o fim. Depois de instalar o Ponytail, o código gerado por AI fica menor — e também diminui sua carga no review. Duas coisas da mesma moeda.

Frase final para resumir: o Ponytail não é “escrever menos código” — é “perguntar primeiro se precisa escrever”.

Próximo passo recomendado: usar Defapi para conseguir uma key Claude com meia-carteira e rodar o Ponytail em uma tarefa real sua. Você vai perceber que os 60% cortados na conta vêm 50% do Ponytail cortando tokens e 50% do Defapi cortando o preço por unidade.