Ponytail: cura la "enfermedad de sobrediseño" de los AI Agent; en pruebas, reduce un 54% el código

Repositorio: https://github.com/DietrichGebert/ponytail

Baja dificultad, empiezas en 10 minutos y en 1 hora ya has corrido tu primer benchmark. Cura el hábito de que tu IA para programar "no sepa frenar".

Prefacio

¿Te ha pasado esto alguna vez: le pides a Claude Code que haga un selector de fecha, y, muy serio, instala flatpickr, escribe un componente wrapper, añade una hoja CSS, empieza a hablarte del manejo de zonas horarias y, al final, te entrega 287 líneas?

Lo que querías decir era: "quiero un campo de entrada que permita elegir fechas"; lo que te entrega es un "framework para selección de fechas".

Eso es la "enfermedad de sobrediseño" de los AI Agent: el modelo ha sido entrenado para "parecer muy profesional", así que automáticamente añade capas de abstracción, opciones de configuración, manejo de errores, cobertura de pruebas... cuando quizá tú solo querías un <input type="date">.

Ponytail viene a curar eso. Lo ha publicado en open source Dietrich Gebert, y su idea central se resume en una frase: "El mejor código es el código que nunca llega a escribirse".

Ponytail no es un modelo ni un plugin de IDE; es un conjunto de reglas con estilo de "ingeniero senior perezoso". Le pone a la IA una escalera de 6 peldaños:

1. ¿De verdad hay que construir esto?      → Si no: saltar (YAGNI)
2. ¿Puede hacerlo la librería estándar?    → Úsala
3. ¿Puede hacerlo una capacidad nativa?    → Úsala
4. ¿Puede hacerlo una dependencia ya instalada? → Úsala
5. ¿Puede hacerse con una línea?           → Escríbela en una línea
6. Si no queda más remedio: escribe el código mínimo que satisfaga el requisito

En un experimento comparativo sobre un repositorio real, tiangolo's full-stack-fastapi-template, con 12 tickets de features, n=4 y Haiku 4.5, Ponytail obtuvo este resultado:

Ponytail es la única opción que reduce todos los indicadores; también es la única que recorta código sin perder seguridad. El selector de color pasó de 287 líneas a 23, y el selector de fecha de 404 líneas a 23, porque simplemente usó <input type="color"> y <input type="date"> integrados en el navegador.

Es compatible con 14 herramientas de programación con IA: Claude Code, Codex, Cursor, Windsurf, Cline, Copilot CLI, Aider, Kiro, Zed, CodeWhale, OpenCode, Pi, Gemini CLI y OpenClaw. Hoy vamos a meter este conjunto de reglas en Claude Code y curar en 30 segundos la "enfermedad de sobrediseño" de tu agent.

Público objetivo

• Desarrolladores con 1-5 años de experiencia que usan agentes de IA para programar a diario
• Quienes sienten que "la IA escribe código demasiado largo y mete un montón de dependencias que no hacen falta"
• Personas que quieren unificar el estilo de codificación del equipo sin escribir reglas rígidas de ESLint
• Quienes se preocupan por el coste de la programación con IA y sufren al ver la factura de tokens

Dependencias y entorno principales

• Node.js 18+ (obligatorio; los lifecycle hooks de Ponytail se ejecutan con Node; si usas nvm, asegúrate de que esté en el PATH de un shell no interactivo)
• Un AI Agent compatible (Claude Code para la demo)
• Una API key de LLM (para la demo se usa Claude Haiku 4.5 de Defapi, a mitad de precio)
• Opcional: Python 3.10+ (se usa pandas al ejecutar el benchmark)
• Opcional: Git (para clonar el repositorio)

Estructura completa del proyecto

ponytail/
├── AGENTS.md                  # Reglas centrales (la "filosofía del perezoso" que todos los agents leen)
├── README.md / README.es.md   # README en chino, inglés y español
├── package.json               # definición del paquete pi-agent
├── commands/                  # 6 slash commands
│   ├── ponytail.toml          # /ponytail [lite|full|ultra|off]
│   ├── ponytail-review.toml   # /ponytail-review (recorta el diff actual)
│   ├── ponytail-audit.toml    # /ponytail-audit (escanea todo el repositorio)
│   ├── ponytail-debt.toml     # /ponytail-debt (cobrar la deuda: comentarios ponytail:)
│   ├── ponytail-gain.toml     # /ponytail-gain (ver la hoja de resultados del benchmark)
│   └── ponytail-help.toml     # /ponytail-help
├── skills/                    # 6 espejos de skills
│   ├── ponytail/              # reglas principales
│   ├── ponytail-review/ ...   # los otros 5
├── hooks/                     # hooks de ciclo de vida para Claude / Codex
│   ├── ponytail-config.js     # resolución de modo (env + config.json)
│   └── ponytail-instructions.js
├── ponytail-mcp/              # adaptación de servidor MCP (para hosts que solo usan MCP)
│   ├── index.js
│   ├── instructions.js
│   └── test/
├── examples/                  # 12 comparativas reales "sobrediseño vs una línea"
│   ├── date-picker.md / color-picker.md (nativo de web)
│   ├── deep-clone.md (structuredClone)
│   ├── debounce.md
│   ├── email-validation.md (75 líneas → 3 líneas)
│   └── ... total 12
├── benchmarks/                # benchmark con promptfoo + agentic
│   ├── promptfooconfig.yaml   # benchmark de una sola ronda
│   ├── benchmark-local.py     # benchmark agentic sobre repositorios reales
│   ├── agentic/               # scripts de 12 tickets
│   └── results/2026-06-18-agentic.md  # datos completos
├── docs/
│   ├── agent-portability.md   # qué agent instala qué archivo
│   └── platform-native.md
├── .openclaw/                 # skill de adaptación para OpenClaw (generado automáticamente)
├── .cursor/ .windsurf/        # archivos de reglas para Cursor / Windsurf
├── .clinerules/               # reglas de Cline
├── .kiro/steering/            # reglas de Kiro
└── tests/                     # pruebas de coherencia de las reglas

---

Tutorial paso a paso

Paso 1: Instalar Ponytail en Claude Code

En Claude Code, Ponytail es como un plugin marketplace; se hace en 30 segundos.

# Añade el repositorio de Ponytail a tu lista de plugin marketplace
/plugin marketplace add DietrichGebert/ponytail

# Instala el skill principal (una vez por sesión)
/plugin install ponytail@ponytail

Abre una sesión nueva después de instalarlo, y el texto de startup mostrará el modo actual (por defecto full). Verás una salida parecida a esta:

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.

Si quieres cambiar la intensidad, escribe:

/ponytail lite     # modo suave (protege los peldaños 1-2)
/ponytail full     # por defecto
/ponytail ultra    # modo recorte agresivo (no deja pasar ni una capa de abstracción)
/ponytail off      # desactivado
/ponytail          # sin parámetros = muestra el nivel actual

También puedes persistirlo:

# ultra por defecto permanente
export PONYTAIL_DEFAULT_MODE=ultra

O escribir un archivo de configuración:

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

Paso 2: Probar un ejemplo contrario

Vamos a ver el efecto directamente. Prepara dos prompts exactamente iguales:

Prompt A (Ponytail desactivado): primero /ponytail off, luego pregunta

Add a color picker to the settings page

Obtendrás una respuesta de unas 287 líneas: instalar react-color o construir un componente de 5 archivos por tu cuenta, añadir validación de props, throttle en onChange, etiqueta de accesibilidad y variables CSS.

Prompt B (Ponytail activado): primero /ponytail full, y vuelve a hacer la misma pregunta.

Obtendrás:

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

Una línea. Y listo.

En el AGENTS.md de Ponytail está escrita esta regla central (texto 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.

Fíjate en la última línea: Only then — no dice que no puedas escribirlo; dice que primero debes recorrer los 5 pasos anteriores.

Paso 3: Ejecutarlo con Defapi y ahorrar la mitad en tokens

Ponytail te ayuda a recortar código, pero para ejecutar el AI Agent en sí, tienes que gastar tokens en Claude / GPT. Defapi ofrece Claude / GPT / Gemini oficiales a mitad de precio, con compatibilidad total.

Vamos a cambiar a Defapi y correr un benchmark:

Paso 3.1: Obtener la API key de Defapi

Regístrate en defapi.org, consigue una key que empiece por dk- y guárdala en el .env de Ponytail:

# En la raíz del repositorio ponytail
cat > .env <<'EOF'
ANTHROPIC_API_KEY=dk-tu-defapi-key
ANTHROPIC_BASE_URL=https://api.defapi.org
EOF

Paso 3.2: Verificar directamente con curl que funciona

curl -s https://api.defapi.org/api/v1/messages \
  -H "Authorization: Bearer dk-tu-defapi-key" \
  -H "content-type: application/json" \
  -d '{
    "model": "anthropic/claude-haiku-4.5",
    "max_tokens": 256,
    "messages": [
      {"role": "user", "content": "Describe la palabra ponytail con un emoji"}
    ]
  }'

Respuesta:

{
  "id": "msg_01H...",
  "role": "assistant",
  "content": [{"type": "text", "text": "🦄 (ni siquiera debería aparecer)"}],
  "usage": {"input_tokens": 22, "output_tokens": 12}
}

Paso 3.3: Hacer que promptfoo use Defapi

Ponytail incluye un benchmark con promptfoo; edita benchmarks/promptfooconfig.yaml:

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

Ejecuta:

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

Dinero ahorrado (estimado según el volumen del benchmark de Ponytail: 12 tickets × n=4 = 48 ejecuciones):

Ponytail reduce un 20% el coste, Defapi otro 50%; si usas ambos, la factura real queda en 40%.

Paso 4: Ejecutar /ponytail-review para recortar el diff actual

No basta con que Ponytail controle lo que se escribe; seguramente ya tienes una masa de código de "sobrediseño" acumulada. Para eso está el comando review:

# En un repositorio con cambios
/ponytail-review

Solo revisa el git diff actual y su formato de salida es fijo:

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 etiquetas:

• delete — código muerto / feature especulativa
• stdlib — reinventar la librería estándar
• native — trabajo que ya resuelve una dependencia / una capacidad nativa de la plataforma
• yagni — capa de abstracción con una sola implementación
• shrink — misma lógica, pero con menos líneas

La última línea te da el "número neto de líneas eliminables"; ese es tu indicador cuantificado de deuda técnica.

Si la salida es Lean already. Ship., significa que tu código ya está bastante delgado y puedes hacer merge con tranquilidad.

Paso 5: Ejecutar /ponytail-audit para escanear todo el repositorio

review mira el diff; audit mira todo el árbol.

/ponytail-audit

La salida es parecida, pero ordenada por lo que más se puede recortar:

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

Recomendación práctica: primero review, luego audit. review corrige el diff y lo mergea; audit te ayuda a priorizar la siguiente ronda de limpieza.

Paso 6: Activarlo en otros Agents

La gran ventaja de Ponytail es que es "una sola regla, efecto en todas partes". Tiene archivos de adaptación preparados para cada herramienta principal de IA para programar:

Codex (modo CLI)

codex plugin marketplace add DietrichGebert/ponytail
codex
# Abre /plugins → elige Ponytail → instala
# Abre /hooks → confía en los dos lifecycle hooks → abre un nuevo hilo

Cursor

Copia directamente .cursor/rules/ponytail.mdc a tu proyecto:

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

O a nivel global:

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 (si ya lo usas)

# El comando más elegante
clawhub install ponytail

O copia manualmente:

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

Gemini CLI

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

Pi / Aider / Kiro / Zed / CodeWhale

Estos agents leen directamente AGENTS.md:

# A nivel de proyecto
cp AGENTS.md ~/your-project/AGENTS.md

# Global (pi / Aider / CodeWhale también lo reconocen)
cp AGENTS.md ~/.pi/AGENTS.md

Tabla de compatibilidad completa (extraída de docs/agent-portability.md del proyecto):

Paso 7: Ejecutar tu propio benchmark

Los datos reales de Ponytail no salen de la nada; los genera benchmarks/benchmark-local.py. También puedes reproducirlo con 5 tareas reales tuyas:

Paso 7.1: Preparar prompts

Edita benchmarks/prompts.json (o usa los 5 ya preparados):

[
  { "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" }
]

Paso 7.2: Ejecutar la comparación de tres arms

# baseline: no añadir nada
npx promptfoo@latest eval -c benchmarks/promptfooconfig.yaml

# ponytail: arm del plugin con el skill añadido
PONYTAIL_DEFAULT_MODE=full npx promptfoo@latest eval -c benchmarks/promptfooconfig.yaml

Paso 7.3: Ver resultados

Genera benchmarks/output.json, que incluye para cada prompt y cada arm:

• loc — líneas de código
• tokens — tokens totales
• cost — dólares
• time — tiempo end-to-end
• passed_safety — si supera las pruebas de seguridad (validación de entradas, manejo de errores, a11y)

Normalmente, el arm de Ponytail reduce el LOC entre un 50% y un 80% frente al baseline.

Paso 8: Ejecutar ponytail-mcp (avanzado)

Si tu host de IA solo admite MCP (por ejemplo, algunas apps de escritorio), Ponytail también tiene adaptación como servidor MCP:

cd ponytail-mcp
npm install
node index.js    # inicia el servidor MCP por stdio

En la configuración MCP del host, añade:

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

Expone:

• Prompt ponytail: devuelve el texto de las reglas, con parámetro opcional mode (lite / full / ultra)
• Tool ponytail_instructions: igual que arriba, pero con structuredContent, para hosts de estilo code-execution

---

Solución de problemas frecuentes

Q1: Después de instalarlo no pasa nada, no aparece el texto de startup?

En el 99% de los casos, Node no está en el PATH del shell no interactivo. Verifica:

# Esto hay que ejecutarlo en un shell nuevo (simulando uno no interactivo)
bash -lc 'node -v'      # bash
zsh -lc 'node -v'       # zsh

Si devuelve command not found, añade el source de nvm a ~/.bashrc / ~/.zshrc, o instala directamente Node del sistema:

# macOS
brew install node@20

# Windows
winget install OpenJS.NodeJS.LTS

Q2: "Yo quiero esa clase cache de 120 líneas" — ¿qué hago cuando es un requisito fuerte?

Dos soluciones:

# Desactívalo temporalmente
/ponytail off

# O permite algo localmente: dilo directamente en el prompt
"Build a 120-line cache class, ignore ponytail for this task"

Ponytail es un conjunto de reglas, no un grillete; si el modelo recibe una override explícita, la obedecerá.

Q3: ¿Ponytail entra en conflicto con ESLint / Prettier?

No entra en conflicto; hacen cosas distintas:

• Ponytail: controla "si debería escribirse" — si existe esa abstracción, si hace falta esa dependencia, si hace falta ese wrapper
• ESLint: controla "si está bien escrito" — nombres, estilo, variables sin usar
• Prettier: controla "si tiene buen formato" — indentación, punto y coma, saltos de línea

Los tres juntos funcionan mejor. Ponytail decide la forma del código en la capa más alta; ESLint / Prettier garantizan los detalles en capas posteriores.

Q4: ¿Cómo unificamos las reglas en el equipo?

AGENTS.md es un archivo a nivel de repositorio; basta con subirlo a git:

# En la raíz del repositorio de tu equipo
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 los agents que leen AGENTS.md (CodeWhale, Aider, Zed, Pi, Kiro, la extensión de Codex) lo seguirán automáticamente.

Q5: ¿Ponytail degrada las pruebas de seguridad?

No, esta es una de las métricas más importantes del benchmark de Ponytail. En la tabla comparativa, baseline / caveman / Ponytail alcanzan 100% de éxito en seguridad; solo el prompt desnudo "YAGNI + una línea" baja al 95%.

En el AGENTS.md de Ponytail hay una sección que dice específicamente:

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

Traducción: la pereza depende del lugar. La lógica de negocio y los wrappers de UI se pueden simplificar todo lo posible; la validación de entradas, los fallback de errores, la seguridad y la accesibilidad no se pueden recortar.

Q6: ¿Cómo lo ejecuto en CI?

Extrae la lógica de /ponytail-review a un script independiente (el repositorio de Ponytail ofrece una implementación de referencia en benchmarks/correctness.test.js) y luego:

# .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

Si falla en el PR, significa que el diff actual hace que Ponytail piense que "todavía se puede adelgazar más".

Q7: Modo MCP vs modo always-on, ¿cuál elijo?

Depende de tu host:

---

Lecturas ampliadas / siguientes pasos

Raíces filosóficas de Ponytail

• La charla "Simple Made Easy" de Rich Hickey (el padre de Clojure sobre la diferencia entre "fácil" y "simple")
• "The Magic Tricks of Testing" de Sandi Metz (principio de minimizar la cobertura de pruebas)
• "Thirty Years of 'WTF'" de Ted Neward (sátira sobre el crecimiento desmedido del código empresarial)
• Otra formulación de la escalera de 6 peldaños: "Just Enough Architecture" de Coad

Escribir tus propios comentarios al estilo Ponytail

Los comentarios ponytail: son una nota para el desarrollador que leerá ese código en el futuro. Formato acordado:

// ponytail: <razón>, <limitación conocida / ruta de mejora>

Ejemplo:

# ponytail: el módulo stdlib re es suficiente; no hace falta instalar email-validator
# limitación conocida: no valida todos los casos límite de RFC 5322; si necesitas soportar el edge case [email protected], cambia a email-validator
import re
def is_valid_email(email: str) -> bool:
    return bool(re.match(r'^[^@]+@[^@]+\.[^@]+$', email))

El comando /ponytail-debt escanea todos los comentarios ponytail: y genera un ledger de deuda técnica; el "later" no se convierte en "never".

Integrarlo en el flujo de Code Review del equipo

Usa /ponytail-review como si fuera un lint, y añade esta línea a la plantilla del PR:

## Ponytail review
- [ ] He ejecutado `/ponytail-review` sobre este diff
- [ ] Líneas netas eliminables: ___
- [ ] Si > 0, justificación: ___

Datos completos del benchmark

benchmarks/results/2026-06-18-agentic.md contiene la metodología completa y las limitaciones de 12 tickets × 3 arms × 4 rondas. Merece la pena leerlo, especialmente la parte de "fair agentic baseline": el supuesto "mito de una sola ronda" del 80-94% era una amplificación artificial del conversational baseline; 54% es el número honesto.

Sobre los límites de Ponytail

La premisa para recortar código con Ponytail es que "el código sea correcto". No verifica:

• Si la lógica de negocio es correcta (eso debes cubrirlo tú con tests)
• Si el rendimiento es suficiente (si hay un O(n²), la nota ponytail lo señalará, pero no lo corregirá automáticamente)
• Si se cubren todos los edge cases (la nota perezosa los listará, pero no añadirá tests por ti)

Es un punto de partida, no el destino. Después de instalar Ponytail, la IA escribe menos código, pero tu carga de revisión también se aligera; esas dos cosas son las dos caras de la misma moneda.

En una frase final: Ponytail no consiste en "escribir menos código", sino en "preguntar primero si hace falta escribirlo".

Siguiente paso recomendado: consigue una key Claude a mitad de precio con Defapi y corre tus propias tareas reales junto con Ponytail; verás que de ese 60% que recortas de la factura, la mitad viene de que Ponytail reduce tokens y la otra mitad de que Defapi baja el precio unitario.