From 3a8ed4fc3633466b3455c5db47ddb0ea0c352b56 Mon Sep 17 00:00:00 2001 From: Emeriko Date: Fri, 12 Jun 2026 04:05:20 +0200 Subject: [PATCH] docs: readme practices what it preaches --- README.md | 149 ++++++++++-------------------------------------------- 1 file changed, 26 insertions(+), 123 deletions(-) diff --git a/README.md b/README.md index 37abbfd..262a1b9 100644 --- a/README.md +++ b/README.md @@ -5,152 +5,55 @@

Ponytail

- A skill that makes your AI agent think like the laziest senior dev in the room —
- because the best code is the code you never wrote. + Makes your AI agent think like the laziest senior dev in the room.
+ The best code is the code you never wrote.

--- -## The Problem +AI agents over-deliver. Ask for a date picker, get a component library. -AI coding agents are overenthusiastic by default. Give them a simple task and they will: +With ponytail: -- Write 200 lines where 5 would work -- Build custom implementations when the standard library already has it -- Add dependencies when a native feature exists -- Generate boilerplate nobody asked for -- Abstract everything, over-engineer everything - -**Ponytail fixes this.** - -## What Ponytail Is - -Ponytail is an AI agent skill. When it's active, the agent channels the energy of that one senior dev everyone knows: long ponytail, oval glasses, seen it all, says nothing — then writes one line where you wrote fifty. - -Before writing any code, the agent walks this ladder and stops 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 this? → use it -4. Does an existing package solve this? → use it -5. Can this be done in one line? → do it -6. Only then: write the minimum code that works +```html + + ``` -Intentional simplifications are marked with a `ponytail:` comment, so simple reads as deliberate — not naive. +More before/afters in [examples/](examples/). -## Examples +## How it works -| Task | Without Ponytail | With Ponytail | -|---|---|---| -| [Email validation](examples/email-validation.md) | 27-line validator class | `"@" in email` — or let the confirmation mail reject it | -| [Date picker](examples/date-picker.md) | flatpickr + wrapper component | `` | -| [Sorting](examples/sorting.md) | hand-rolled quicksort | `arr.sort((a, b) => a - b)` | -| [Caching](examples/caching.md) | 120-line TTL cache class | `@lru_cache` — or nothing until you measure | -| [API endpoint](examples/api-endpoint.md) | 5 files of layers | 5 lines | +Before writing code, the agent stops at the first rung that holds: -Full before/after in [examples/](examples/). +``` +1. Does this need to exist? → no: skip it (YAGNI) +2. Stdlib does it? → use it +3. Native platform feature? → use it +4. Installed dependency? → use it +5. One line? → one line +6. Only then: the minimum that works +``` + +Never lazy about: validation at trust boundaries, error handling against data loss, security, accessibility. ## Install -**Claude Code — plugin (full integration)** +Claude Code: ``` /plugin marketplace add DietrichGebert/ponytail /plugin install ponytail@ponytail ``` -Auto-activation every session, `/ponytail` levels, `/ponytail-review`, `/ponytail-help`, `[PONYTAIL]` statusline badge. Restart Claude Code after install. +Active every session. `/ponytail lite|full|ultra|off` switches intensity, `/ponytail-review` hunts over-engineering, `/ponytail-help` explains the rest. -**Claude Code — skill only** +Cursor, Windsurf, Cline, Copilot, Aider: copy the matching rules file from this repo ([`.cursor/rules/`](.cursor/rules/), [`.windsurf/rules/`](.windsurf/rules/), [`.clinerules/`](.clinerules/), [`.github/copilot-instructions.md`](.github/copilot-instructions.md), [`AGENTS.md`](AGENTS.md)). -```bash -git clone https://github.com/DietrichGebert/ponytail.git -cp -r ponytail/skills/ponytail ~/.claude/skills/ # personal, all projects -# or: cp -r ponytail/skills/ponytail .claude/skills/ # this project only -``` +## Numbers -**Cursor** — copy [`.cursor/rules/ponytail.mdc`](.cursor/rules/ponytail.mdc) into your project. - -**Windsurf** — copy [`.windsurf/rules/ponytail.md`](.windsurf/rules/ponytail.md). - -**Cline** — copy [`.clinerules/ponytail.md`](.clinerules/ponytail.md). - -**Aider** — `aider --read AGENTS.md` with [`AGENTS.md`](AGENTS.md) in the repo root. - -**GitHub Copilot** — copy [`.github/copilot-instructions.md`](.github/copilot-instructions.md). - -## Levels - -| Level | Trigger | What changes | -|---|---|---| -| **lite** | `/ponytail lite` | Builds what's asked, names the lazier alternative in one line. | -| **full** | `/ponytail` | The ladder enforced. Questions necessity, stdlib first, shortest diff. Default. | -| **ultra** | `/ponytail ultra` | YAGNI extremist. Deletion before addition. Challenges the requirement before building. | - -Deactivate: say "stop ponytail" / "normal mode", or `/ponytail off`. - -## Commands - -| Command | What it does | -|---|---| -| `/ponytail [lite\|full\|ultra\|off]` | Switch level | -| `/ponytail-review` | Over-engineering review — `L42: yagni: factory, one product. Inline.` | -| `/ponytail-help` | Reference card | - -## Configure - -The plugin auto-activates at `full` every session. Change the default: - -```bash -export PONYTAIL_DEFAULT_MODE=ultra # env var, highest priority -``` - -or `~/.config/ponytail/config.json` (Windows: `%APPDATA%\ponytail\config.json`): - -```json -{ "defaultMode": "off" } -``` - -`off` = no auto-activation, `/ponytail` still works on demand. Statusline badge (`[PONYTAIL]`, `[PONYTAIL:ULTRA]`) offers to configure itself if no statusline is set. - -## Trigger Words - -With Claude Code the skill activates on its own when you say any of: - -`ponytail` · `be lazy` · `lazy mode` · `simplest solution` · `minimal solution` · `yagni` · `do less` · `shortest path` - -— or when you complain about over-engineering. Other tools apply rules files unconditionally. - -## Token Savings - -Ponytail saves tokens on two levels at once: - -1. **Shorter output** — less code written, fewer output tokens. -2. **Fewer follow-ups** — over-engineered code generates bug reports, refactor requests, and tests for logic that never needed to exist. Ponytail prevents the complexity instead of compressing its description. - -Measured (5 coding tasks, fresh agent per run, same model): - -| Config | Agent tokens | Time | Code written | -|---|---|---|---| -| No skill | 161,955 | 479s | ~293 lines | -| Caveman | 138,410 | 136s | ~117 lines | -| **Ponytail** | **135,709** | **127s** | **~47 lines** | - -The no-skill baseline produced a 190-line countdown "dashboard" where ponytail shipped 13 lines. Full data: [benchmarks/](benchmarks/). - -## Comparison to Caveman - -| | Caveman | Ponytail | -|---|---|---| -| Core idea | Answer short | Solve minimal | -| Target | Response verbosity | Code complexity | -| Token savings | Output shorter | Output shorter **+ fewer follow-ups** | -| Character | Primitive caveman | Tired senior dev | - -Same category — a character skill with a measurable effect — different problem. They stack nicely. +5 coding tasks, same agent with and without ponytail: **−16% tokens, ~4× faster, 293 → 47 lines of code.** Data: [benchmarks/](benchmarks/). ## License -[MIT](LICENSE). Ponytail would have chosen the shortest license anyway. +[MIT](LICENSE). The shortest license that works.