Queue de cheval : soignez le « syndrome de sur-conception » de votre AI Agent — au final, 54 % de code en moins

Dépôt : https://github.com/DietrichGebert/ponytail

Difficulté faible : prise en main en 10 minutes, premier benchmark en 1 heure. Pour soigner, une bonne fois pour toutes, le défaut de votre AI qui « n’arrive jamais à s’arrêter » quand elle code.

Introduction

Avez-vous déjà vécu ça : faire en sorte que Claude Code vous génère un sélecteur de date. Et là, il installe flatpickr de façon tout à fait sérieuse, ajoute un composant wrapper, une touche de CSS… puis se met à vous parler de gestion des fuseaux horaires, et, finalement, vous livrer 287 lignes.

Vous vouliez dire : « Je veux juste un champ permettant de choisir une date. » Et il vous a livré : « Un framework complet pour sélectionner des dates. »

C’est le « syndrome de sur-conception » des AI Agents : les modèles sont entraînés à « paraître très professionnels » ; du coup ils ajoutent automatiquement des couches d’abstraction, des options de configuration, de la gestion d’erreurs, et des tests — alors que votre besoin réel est peut-être juste un <input type="date">.

Ponytail est là pour soigner ce problème. Développé en open source par Dietrich Gebert, son idée centrale tient en une phrase : « Le meilleur code est celui qu’on n’écrit jamais. »

Ponytail n’est ni un modèle, ni une extension d’IDE. C’est un ensemble de règles au style « ingénieur senior paresseux ». Il met à l’AI une échelle à 6 barreaux :

1. Faut-il vraiment écrire ça ?          → Non : passer (YAGNI)
2. La bibliothèque standard peut-elle faire ?  → L’utiliser
3. Les capacités natives de la plateforme peuvent-elles faire ?  → Les utiliser
4. Les dépendances déjà installées peuvent-elles faire ?  → Les utiliser
5. Peut-on le faire en une seule ligne ?  → En une seule
6. Sinon : écrire le minimum qui marche

Dans une expérience comparative sur le vrai dépôt de tiangolo avec full-stack-fastapi-template, avec 12 tickets feature, n=4, Haiku 4.5, Ponytail obtient ce tableau de résultats :

Ponytail est le seul schéma où tous les indicateurs baissent, et le seul où l’on supprime du code sans perdre en sécurité. Le sélecteur de couleurs passe de 287 lignes à 23, et le sélecteur de dates de 404 lignes à 23 — parce qu’il utilise directement les <input type="color"> et ` intégrés au navigateur.

Il est compatible avec 14 outils d’AI pour programmer : Claude Code, Codex, Cursor, Windsurf, Cline, Copilot CLI, Aider, Kiro, Zed, CodeWhale, OpenCode, Pi, Gemini CLI, OpenClaw. Aujourd’hui, on installe cet ensemble de règles dans Claude Code, et on guérit en 30 secondes le « syndrome de sur-conception » de votre Agent.

Public cible

• Développeurs qui écrivent du code au quotidien avec des AI Agents (1 à 5 ans d’expérience)
• Ceux qui ont « la sensation » que l’AI code trop long et installe des tonnes de dépendances inutiles
• Ceux qui veulent uniformiser le style de codage de l’équipe, sans pour autant verrouiller des règles ESLint trop rigides
• Chefs d’équipe / Tech Leads qui suivent le coût de l’AI et souffrent avec la facture tokens

Dépendances clés et environnement

• Node.js 18+ (indispensable : les hooks de lifecycle de Ponytail s’exécutent via Node ; utilisateurs nvm : pensez à l’ajouter au PATH du shell non interactif)
• Un AI Agent supporté (Claude Code pour la démo)
• Une clé d’API LLM (démo : Defapi pour Claude Haiku 4.5, moitié prix)
• Optionnel : Python 3.10+ (utile pour exécuter les benchmarks avec pandas)
• Optionnel : Git (pour cloner le dépôt)

Structure complète du projet

ponytail/
├── AGENTS.md                  # Règles centrales (la « philosophie paresseuse » lue par tous les agents)
├── README.md / README.es.md   # README en trois langues (EN/ES)
├── package.json               # définition du package pi-agent
├── commands/                  # 6 commandes slash
│   ├── ponytail.toml          # /ponytail [lite|full|ultra|off]
│   ├── ponytail-review.toml   # /ponytail-review (couper le diff actuel)
│   ├── ponytail-audit.toml    # /ponytail-audit (balayer tout le dépôt)
│   ├── ponytail-debt.toml     # /ponytail-debt (encaisser Ponytail : commenter)
│   ├── ponytail-gain.toml     # /ponytail-gain (voir le tableau de scores)
│   └── ponytail-help.toml     # /ponytail-help
├── skills/                    # 6 images de skills
│   ├── ponytail/              # règles principales
│   ├── ponytail-review/ ...   # les 5 autres
├── hooks/                     # hooks de lifecycle Claude / Codex
│   ├── ponytail-config.js     # parsing du mode (env + config.json)
│   └── ponytail-instructions.js
├── ponytail-mcp/              # adaptation serveur MCP (pour hôtes « MCP-only »)
│   ├── index.js
│   ├── instructions.js
│   └── test/
├── examples/                  # 12 vrais comparatifs « sur-conception vs une ligne »
│   ├── date-picker.md / color-picker.md（intégré côté web）
│   ├── deep-clone.md（structuredClone）
│   ├── debounce.md
│   ├── email-validation.md（75 lignes → 3 lignes）
│   └── ... au total 12
├── benchmarks/                # promptfoo + benchmarks « agentic »
│   ├── promptfooconfig.yaml   # benchmark mono-tour
│   ├── benchmark-local.py     # benchmark agentic sur dépôt réel
│   ├── agentic/               # scripts pour 12 tickets
│   └── results/2026-06-18-agentic.md  # données complètes
├── docs/
│   ├── agent-portability.md   # quel agent installe quel fichier
│   └── platform-native.md
├── .openclaw/                 # skill OpenClaw (généré automatiquement)
├── .cursor/ .windsurf/        # fichiers de règles Cursor / Windsurf
├── .clinerules/               # règles Cline
├── .kiro/steering/            # règles Kiro
└── tests/                     # tests d’uniformité des règles

---

Tutoriel pas à pas

Étape 1 : installer Ponytail dans Claude Code

Dans Claude Code, Ponytail apparaît comme un « marketplace de plugins ». En 30 secondes, c’est fait.

# Ajouter le dépôt Ponytail à votre liste de marketplace
/plugin marketplace add DietrichGebert/ponytail

# Installer le skill principal (une fois par session)
/plugin install ponytail@ponytail

Une fois installé, ouvrez une nouvelle session : le texte de startup affiche le mode courant (par défaut full). Vous verrez une sortie comme ceci :

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.

Pour changer la puissance, saisissez :

/ponytail lite     # mode léger (protège 1-2 barreaux)
/ponytail full     # par défaut
/ponytail ultra    # mode « suppression radicale » (n’épargne même aucune couche d’abstraction)
/ponytail off      # désactiver
/ponytail          # sans paramètre = afficher le mode actuel

On peut aussi persister :

# Mode ultra par défaut (définitivement)
export PONYTAIL_DEFAULT_MODE=ultra

Ou écrire un fichier de config :

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

Étape 2 : lancer une comparaison avec un contre-exemple

On regarde le résultat. Préparez deux prompts parfaitement identiques :

Prompt A (Ponytail désactivé) : commencez par /ponytail off, puis demandez

Add a color picker to the settings page

Vous obtiendrez environ 287 lignes : installer un react-color ou créer vos 5 fichiers de composant, ajouter la validation des props, mettre du throttling sur onChange, ajouter des labels d’accessibilité, et des variables CSS.

Prompt B (Ponytail activé) : commencez par /ponytail full, puis redemandez exactement la même chose.

Vous obtenez :

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

Une ligne. C’est fini.

Dans AGENTS.md de Ponytail, cette règle centrale est écrite telle quelle (texte 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.

Notez la dernière ligne : « Only then » — ce n’est pas « ne pas écrire », c’est « d’abord passer les 5 étapes ».

Étape 3 : passer par Defapi pour réduire la facture tokens de moitié

Ponytail réduit la quantité de code, mais pour faire tourner un AI Agent lui-même, il faut faire brûler des tokens à Claude / GPT. Defapi fournit officialement une offre à moitié prix pour Claude / GPT / Gemini, avec une compatibilité totale.

On bascule sur Defapi et on lance un benchmark :

Étape 3.1 : récupérer une Defapi Key

Allez sur defapi.org, enregistrez-vous et prenez une clé commençant par dk-xxx, puis écrivez-la dans le fichier .env de Ponytail :

# à la racine du dépôt ponytail
cat > .env <<'EOF'
ANTHROPIC_API_KEY=dk-xxxx-votre-defapi-key
ANTHROPIC_BASE_URL=https://api.defapi.org
EOF

Étape 3.2 : vérifier directement avec curl

curl -s https://api.defapi.org/api/v1/messages \
  -H "Authorization: Bearer dk-xxxx-votre-defapi-key" \
  -H "content-type: application/json" \
  -d '{
    "model": "anthropic/claude-haiku-4.5",
    "max_tokens": 256,
    "messages": [
      {"role": "user", "content": "用一个 emoji 描述 ponytail 这个词"}
    ]
  }'

Retour :

{
  "id": "msg_01H...",
  "role": "assistant",
  "content": [{"type": "text", "text": "🦄 (il ne devrait jamais apparaître)"}],
  "usage": {"input_tokens": 22, "output_tokens": 12}
}

Étape 3.3 : faire passer promptfoo par Defapi

Ponytail embarque promptfoo. Éditez benchmarks/promptfooconfig.yaml :

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

Lancez :

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

L’argent économisé (estimation sur la base du volume : 12 tickets × n=4 = 48 exécutions du benchmark de Ponytail) :

Ponytail réduit les coûts de 20 %, Defapi de 50 % : ensemble, vous obtenez une facture réelle à 40 % (soit 4 fois moins).

Étape 4 : exécuter /ponytail-review pour couper le diff actuel

Se contenter de contrôler à l’écriture avec Ponytail ne suffit pas : il vous reste une grosse quantité de « sur-conception » déjà présente dans le code. À ce stade, utilisez la commande review :

# dans un dépôt avec des modifications
/ponytail-review

Elle ne relit que le git diff actuel et sort avec un format fixe :

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

Système de tags :

• delete — code mort / features opportunistes
• stdlib — réinventer la bibliothèque standard
• native — une dépendance fait déjà le travail / la plateforme peut le faire
• yagni — une couche d’abstraction avec une seule implémentation
• shrink — même logique, mais moins de lignes

La dernière ligne vous donne le « nombre net de lignes supprimables » : c’est votre indicateur de quantification de la tech debt.

Si le résultat est Lean already. Ship., cela signifie que votre code est déjà assez léger : vous pouvez merge en toute sérénité.

Étape 5 : exécuter /ponytail-audit pour balayer tout le dépôt

review regarde le diff, audit regarde tout l’arbre.

/ponytail-audit

La sortie ressemble, mais elle est triée par ordre décroissant de suppression possible :

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

Conseil pratique : faire review puis audit. review coupe le diff, merge, puis audit vous aide à prioriser la vague de nettoyage suivante.

Étape 6 : activer dans d’autres Agents

Le principal atout de Ponytail, c’est « une seule fois les règles, partout ». Pour chaque outil d’AI programming populaire, il y a des fichiers d’adaptation préparés :

Codex (mode CLI)

codex plugin marketplace add DietrichGebert/ponytail
codex
# Ouvrir /plugins → choisir Ponytail → installer
# Ouvrir /hooks → faire confiance aux deux lifecycle hook → ouvrir un nouvel thread

Cursor

Copiez directement .cursor/rules/ponytail.mdc dans votre projet :

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

Ou en 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 vous l’utilisez déjà)

# la commande la plus élégante
clawhub install ponytail

Ou en copiant manuellement :

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

Gemini CLI

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

Pi / Aider / Kiro / Zed / CodeWhale

Ces agents lisent directement AGENTS.md :

# au niveau projet
cp AGENTS.md ~/your-project/AGENTS.md

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

Tableau de correspondance complet (extrait du fichier docs/agent-portability.md) :

Étape 7 : lancer votre propre benchmark

Les données réelles de Ponytail ne sont pas sorties de nulle part : elles viennent de l’exécution de benchmarks/benchmark-local.py. Vous pouvez aussi choisir 5 tâches réelles à vous et les reproduire :

Étape 7.1 : préparer les prompts

Éditez benchmarks/prompts.json (ou utilisez les 5 existants) :

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

Étape 7.2 : lancer les trois arm de comparaison

# baseline : ne rien ajouter
npx promptfoo@latest eval -c benchmarks/promptfooconfig.yaml

# ponytail : arm avec plugin skill
PONYTAIL_DEFAULT_MODE=full npx promptfoo@latest eval -c benchmarks/promptfooconfig.yaml

Étape 7.3 : regarder les résultats

Le fichier benchmarks/output.json contient, pour chaque prompt et chaque arm :

• loc — nombre de lignes de code
• tokens — tokens totaux
• cost — en dollars
• time — temps end-to-end
• passed_safety — succès aux tests de sécurité (validation des entrées, gestion d’erreurs, a11y)

En général, l’arm ponytail a une baisse de 50 à 80 % sur le LOC vs baseline.

Étape 8 : lancer ponytail-mcp (avancé)

Si votre hôte AI ne peut utiliser que MCP (par ex. certaines applis desktop), Ponytail propose aussi une adaptation via un serveur MCP :

cd ponytail-mcp
npm install
node index.js    # démarrer le serveur MCP stdio

Ajoutez dans la configuration MCP de votre host :

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

Il expose :

• Prompt ponytail : retourne le texte des règles, avec paramètre optionnel mode (lite / full / ultra)
• Tool ponytail_instructions : identique, mais avec structuredContent, utile pour les hôtes orientés « exécution de code »

---

Diagnostic des problèmes fréquents

Q1 : aucune réaction après installation, le texte de startup ne s’affiche pas ?

Dans 99% des cas : Node n’est pas présent sur le PATH du shell non interactif. Vérifiez :

# à exécuter dans un nouveau shell (simuler un shell non interactif)
bash -lc 'node -v'      # bash
zsh -lc 'node -v'       # zsh

Si vous obtenez command not found, faites : soit écrire nvm source dans ~/.bashrc / ~/.zshrc, soit installer Node system :

# macOS
brew install node@20

# Windows
winget install OpenJS.NodeJS.LTS

Q2 : « Je veux absolument le cache de 120 lignes » — que faire en cas d’exigence forte ?

Deux solutions :

# fermer temporairement
/ponytail off

# ou autoriser localement : le dire explicitement dans le prompt
"Build a 120-line cache class, ignore ponytail for this task"

Ponytail est un ensemble de règles, pas une cage. Avec une override explicite, le modèle suivra.

Q3 : Ponytail est-il en conflit avec ESLint / Prettier ?

Aucun conflit, ils ne font pas la même chose :

• Ponytail : gère « faut-il écrire ça » — y a-t-il cette abstraction, cette dépendance installée, ce wrapper
• ESLint : gère « est-ce correct » — nommage, style, variables inutilisées
• Prettier : gère « est-ce bien formaté » — indentation, points-virgules, retours à la ligne

Ensemble, ça marche le mieux. Ponytail décide en amont à quoi ressemble la taille du code ; ESLint / Prettier vérifient en aval les détails.

Q4 : comment uniformiser les règles dans une équipe ?

AGENTS.md est un fichier au niveau du dépôt : il suffit de le committer dans git.

# à la racine de votre dépôt d’équipe
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"

Tous les agents qui lisent AGENTS.md (CodeWhale, Aider, Zed, Pi, Kiro, Codex extension) respecteront automatiquement.

Q5 : Ponytail dégrade-t-il les tests de sécurité ?

Non : c’est même l’indicateur le plus crucial du benchmark. Dans le tableau, baseline / caveman / Ponytail sont à 100% de succès, seul le prompt nu « YAGNI + une ligne » tombe à 95%.

Dans AGENTS.md, Ponytail écrit spécialement :

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

Traduction : la paresse dépend de l’endroit. On peut économiser sur la logique métier et l’habillage UI si ça va ; mais la validation d’entrée, les garde-fous d’erreurs, la sécurité et l’a11y ne se négocient pas.

Q6 : comment l’exécuter dans un CI ?

Extrayez la logique de /ponytail-review en un script autonome (un exemple d’implémentation de référence est fourni par benchmarks/correctness.test.js dans le dépôt), puis :

# .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 le PR échoue, c’est que le diff actuel donne encore à Ponytail l’impression que « ça peut être encore plus léger ».

Q7 : Mode MCP vs mode always-on : lequel choisir ?

Regardez votre hôte :

---

Lecture complémentaire / pistes d’approfondissement

La racine philosophique de Ponytail

• Conférence de Rich Hickey : « Simple Made Easy » (le fondateur de Clojure parle de la différence entre « facile » et « simple »)
• Sandi Metz : « The Magic Tricks of Testing » (principe de minimisation de la couverture de tests)
• Ted Neward : « Thirty Years of 'WTF' » (satire de la croissance du code en entreprise)
• L’autre formulation de l’échelle à 6 barreaux : « Just Enough Architecture » de Coad

Écrire des commentaires au style ponytail

Les commentaires ponytail: sont des notes laissées aux « développeurs qui liront ce code plus tard ». Format de convention :

// ponytail: <raison>, <limite connue / chemin d’évolution>

Exemple :

# ponytail: la regex de la stdlib suffit, pas besoin d’installer email-validator
# Limite connue : ne valide pas tous les cas limites du RFC 5322 ; si vous devez gérer un cas edge type [email protected], passez à email-validator
import re
def is_valid_email(email: str) -> bool:
    return bool(re.match(r'^[^@]+@[^@]+\.[^@]+$', email))

La commande /ponytail-debt balaye toutes les annotations ponytail: pour générer un ledger de tech debt : « later » ne deviendra pas « never ».

Intégrer au flux de code review de l’équipe

Traitez /ponytail-review comme un lint : dans le template PR, ajoutez une ligne :

## Ponytail review
- [ ] Ran `/ponytail-review` on this diff
- [ ] Net removable lines: ___
- [ ] If > 0, justification: ___

Données complètes du benchmark

benchmarks/results/2026-06-18-agentic.md contient la méthodologie complète + les limites : 12 tickets × 3 arm × 4 exécutions. Ça vaut le coup de lire, en particulier la partie « fair agentic baseline » — auparavant, les « mythes en une seule passe » (80-94%) étaient gonflés artificiellement parce qu’ils utilisaient une baseline conversationnelle ; 54% est le chiffre honnête.

À propos des limites de Ponytail

Ponytail coupe du code à condition que le code soit « correct ». Il ne vérifie pas :

• si la logique métier est correcte (ce que vous devez tester vous-même)
• si les performances sont suffisantes (les commentaires ponytail marquent les cas O(n²), mais ne modifient pas automatiquement)
• si les cas limites sont couverts (les commentaires « lazy » les listent, mais n’ajoutent pas de tests pour vous)

C’est un point de départ, pas un point final. Une fois Ponytail installé, l’AI écrit moins de code, mais votre charge de review diminue aussi : ce sont deux faces d’une même pièce.

Dernière phrase pour résumer : Ponytail ne veut pas dire « écrire moins », mais « d’abord se demander s’il faut écrire ».

Prochaine étape recommandée : utilisez Defapi pour obtenir une clé Claude à moitié prix, puis faites tourner Ponytail sur une de vos tâches réelles — vous verrez que les 60% coupés viennent pour moitié de Ponytail qui réduit les tokens, et pour moitié de Defapi qui réduit le prix unitaire.