Ponytail: jak wymusić minimalizm kodu u agenta AI

Czym jest Ponytail

Ponytail to zestaw reguł, który sprawia, że agent programistyczny AI pisze mniej kodu. Projekt opisuje się jednym zdaniem: „Sprawia, że Twój agent AI myśli jak najbardziej leniwy starszy programista w zespole. Najlepszy kod to ten, którego nigdy nie napisałeś”. Projekt jest udostępniony na licencji MIT. Nie posiada własnego środowiska uruchomieniowego i nie wykonuje żadnego kodu. Jest to tekst wstawiany do instrukcji agenta, spakowany jako umiejętność dla hostów obsługujących umiejętności oraz jako zwykłe pliki reguł dla hostów, które ich nie obsługują.

Repozytorium znajduje się pod adresem DietrichGebert/ponytail. Powstało 12 czerwca 2026 roku i do 1 sierpnia 2026 roku przekroczyło 90 000 gwiazdek. 1 sierpnia 2026 roku najnowszym otagowanym wydaniem było v4.8.4, opublikowane 29 czerwca 2026 roku, a strona wydań wymieniała dziesięć tagów tylko między 14 a 29 czerwca. Tempo nie spadło: 17 października 2026 roku najnowszym wydaniem jest v5.3.2, opublikowane późno 16 października, trzecie wydanie tego dnia po v5.3.0 i v5.3.1. Wcześniej pojawiło się v5.2.0 w dniu 13 października, pięć dni po tym, jak v5.0.0 oraz v5.1.0 zostały opublikowane 8 października, a repozytorium wykazuje ponad 165 000 gwiazdek. Projekt rozwijający się w takim tempie zmieni się do czasu przeczytania tego tekstu, dlatego należy przypiąć tag przed budowaniem czegokolwiek w oparciu o niego.

Koncepcja przed narzędziem: zatrzymaj się na pierwszym szczeblu, który wytrzyma

Rdzeniem Ponytail jest drabina decyzyjna. Agent wspina się po niej przed napisaniem czegokolwiek i zatrzymuje się na pierwszym szczeblu, który wytrzyma.

1. Czy to w ogóle musi istnieć? To zasada YAGNI (you are not going to need it). Jeśli odpowiedź brzmi nie, pomiń to.
2. Czy to już istnieje w tej bazie kodu? Użyj ponownie pomocnika lub wzorca, który już tam jest.
3. Czy biblioteka standardowa to obsługuje? Użyj jej.
4. Czy natywna funkcja platformy to pokrywa? Użyj jej.
5. Czy zainstalowana już zależność to rozwiązuje? Użyj jej.
6. Czy może to być jedna linia? Zrób to w jednej linii.
7. Dopiero wtedy napisz minimalny kod, który działa.

Tak wygląda drabina opisana w v4.8.4, a numery szczebli w dalszej części artykułu są z nią zgodne. Obecna główna gałąź łączy szczeble 3 i 4 w jeden: "Biblioteka standardowa lub funkcja platformy? Użyj jej, chyba że projekt ma własną", dodając, że "komponent własny jest lepszy niż natywny widget", więc ma ona sześć szczebli. Kolejność pozostaje taka sama.

To kolejność wykonuje pracę, a nie pojedynczy szczebel. Agent poproszony o selektor daty napisze selektor daty, ponieważ napisanie go jest tym, co mu zlecono. Drabina zmusza go do sprawdzenia, co już istnieje, zanim cokolwiek zbuduje: szczebel 2 pyta, czy repozytorium ma już taki komponent, a szczebel 4 mówi, że przeglądarka ma już <input type="date">. Obecny benchmark projektu odnotowuje dokładnie ten przypadek: selektor daty, który bez tej reguły zajmował 335 linii, z Ponytail 5 zajął 10 linii, ponieważ agent użył ponownie własnego komponentu Input z repozytorium za pomocą type="date" i pozwolił przeglądarce dostarczyć kalendarz. Selektor kolorów skurczył się mniej, ze 135 linii do 26. Szczebel 2 jest tym, który zawodzi po cichu, ponieważ agent, który nie widzi pomocnika, którego już posiadasz, z radością napisze drugiego, co jest luką, którą ma wypełnić przeszukiwalna mapa Twojej bazy kodu.

Leniwy w tym kontekście nie oznacza niedbały, co zbiór zasad wprost potwierdza. Lista rzeczy, w których "nigdy nie należy być leniwym", obejmuje zrozumienie problemu przed podjęciem decyzji, walidację danych wejściowych na granicach zaufania, obsługę błędów zapobiegającą utracie danych, bezpieczeństwo, dostępność oraz wszystko, o co poproszono z nazwy. Wymaga również jednego małego, uruchamialnego testu dla każdego fragmentu nietrywialnej logiki. Reguła ogranicza inwencję. Nie ogranicza poprawności.

Co faktycznie zawiera repozytorium

• AGENTS.md, stale aktywny zestaw reguł, będący całą ideą zawartą w jednym pliku, który można przeczytać w pięć minut.
• skills/ponytail/SKILL.md, definicja umiejętności, z podpowiedzią argumentu lite, full, ultra lub off.
• Pliki reguł w katalogach specyficznych dla edytora, takich jak .cursor/rules/ oraz .windsurf/rules/, dla hostów, które odczytują reguły, ale nie ładują umiejętności.
• hooks/, benchmarks/, examples/ oraz scripts/.

Argument intensity zmienia stopień rygorystyczności reguł. lite buduje to, o co poproszono, i w jednej linii wskazuje bardziej leniwą opcję. full jest ustawieniem domyślnym i wymusza stosowanie drabinki priorytetów. ultra to ustawienie ekstremalne YAGNI: preferuje usuwanie zamiast dodawania i kwestionuje sam wymóg.

Hosty obsługujące umiejętności otrzymują również polecenia typu slash. /ponytail ustawia poziom, /ponytail-review sprawdza diff pod kątem nadmiernej inżynierii, /ponytail-audit sprawdza całe repozytorium, /ponytail-debt zbiera skróty, które odłożono na później, a /ponytail-gain drukuje kartę wyników benchmarku. Hosty odczytujące tylko pliki reguł otrzymują zestaw reguł bez poleceń. Od wersji v5.3.0, wydanej 16 października 2026 roku, Claude Code otrzymuje również pasek nad promptem, który pokazuje koszt zadania, ponowne wykorzystanie kodu i status testów. Wymaga to Claude Code 2.1.290 lub nowszego; nie pojawia się on w panelu czatu VS Code, sesjach w chmurze ani claude -p, a /ponytail band off go ukrywa. Od wersji v5.3.2, /ponytail band import jednorazowo odczytuje poprzednie sesje Claude Code i dodaje je do tablicy wraz z ich kosztem, czasem pracy agenta i liczbą tokenów, co pozwala na porównanie ich z sesjami uruchomionymi zgodnie z regułami.

Aby zapoznać się z kodem źródłowym przed obdarzeniem go zaufaniem, należy sklonować tag, a nie gałąź. Jest to tag, z którego pochodzi powyższa drabinka; należy podstawić v5.3.2, najnowszy na dzień 17 października 2026 roku, aby przeczytać aktualne brzmienie:

git clone --depth 1 --branch v4.8.4 https://github.com/DietrichGebert/ponytail.git

W przypadku Claude Code projekt dokumentuje zamiast tego instalację wtyczki, a te dwie linie są udokumentowane na dzień 17 października 2026 roku:

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

Ścieżka wtyczki podąża za domyślną gałęzią, a nie za tagiem, więc instrukcje sterujące agentem mogą zmienić się między sesjami. Jest to kompromis, na który zgadzasz się w zamian za wygodę polecenia aktualizacji.

Dlaczego oszczędny agent jest tańszy na VPS

Różnice (diff), które zapisuje agent, nie opuszczają konwersacji. W kolejnej turze stanowią one kontekst, który model odczytuje ponownie, wraz z każdym plikiem otwartym w celu ich wygenerowania. Zmiana obejmująca 500 linii obciąża zatem każdą kolejną turę sesji, dopóki kompresja nie zastąpi starszych tur podsumowaniem – dotyczy to nie tylko tury, w której zmiana powstała. Dlatego niekontrolowany refaktoryzing sprawia, że agent wydaje się wolniejszy i mniej inteligentny w miarę trwania sesji: okno kontekstowe wypełnia się danymi wyjściowymi agenta, przez co ilość miejsca na właściwy kod maleje. Utrzymanie tego procesu pod kontrolą jest głównym tematem zarządzania oknem kontekstowym agenta programistycznego.

Tokeny są rozliczane przy wejściu i wyjściu, więc diff o połowę mniejszy jest dwukrotnie tańszy: raz w momencie zapisu i ponownie w każdej turze, która go odczytuje. To, czy te oszczędności wpłyną na rachunek, zależy od modelu płatności, ponieważ subskrypcja Pro lub Max pokrywa dodatkowe tokeny tylko do określonych limitów użycia, po przekroczeniu których pobierane są opłaty za dodatkowe kredyty, podczas gdy rozliczenie API typu per-token obciąża użytkownika za każdy z nich. W przypadku samodzielnie hostowanej konfiguracji plik instrukcji jest dźwignią, której użycie nic nie kosztuje. Kontrolowanie kosztów agenta AI zaczyna się od objętości danych wyjściowych, a sposób, w jaki agent programistyczny zużywa tokeny wyjaśnia, dlaczego ponowne odczytywanie ma większe znaczenie, niż się powszechnie uważa.

Diff nadal musi zostać przeczytany przez człowieka. Zmiana na 400 linii, która powinna obejmować 20 linii, kosztuje uwagę recenzenta, a uwaga jest zasobem, który wyczerpuje się najszybciej. Nikt nie analizuje czwartego długiego diffa w ciągu dnia z taką samą starannością jak pierwszego, więc nadmierna rozbudowa kodu nie tylko marnuje czas. Po cichu obniża ona jakość przeglądu, który ma na celu wyłapanie błędów.

Na serwerze stawka rośnie, ponieważ agent często pracuje bez nadzoru. Agent działający w sesji tmux lub uruchamiany czasowo ma godziny na budowanie rozwiązań w oparciu o błędną decyzję, zanim zostanie ona zauważona. Jest to praktyczne ryzyko związane z uruchamianiem agenta programistycznego na VPS i dlatego osoby zajmujące się inżynierią pętli poświęcają tyle uwagi stałym instrukcjom, zamiast skupiać się na pojedynczych promptach. Reguła zawarta w pliku stałych instrukcji ma zastosowanie w turze 200. Reguła wpisana na czacie ma zastosowanie w turze 3. Dotyczy ona również drugiej sesji uruchomionej na tej samej maszynie, która odczytuje zatwierdzony plik, ale nie dziedziczy niczego, co zostało wpisane w pierwszej sesji, nawet jeśli obie sesje mogą się ze sobą komunikować.

Nowe zależności to kolejny ukryty koszt. Zasada 5 mówi: używaj tego, co jest zainstalowane. Każdy pakiet, który agent dodaje z własnej inicjatywy, jest elementem, który trzeba później poprawiać i który trafia do każdego obrazu kontenera budowanego z tego repozytorium.

Co mówią własne liczby benchmarkowe Ponytail

Projekt opublikował dwa rodzaje wyników, które znacząco się od siebie różnią. Oba są oficjalnymi danymi projektu. Żaden z nich nie jest niezależnym testem.

[
  {
    "label": "Lines of code",
    "v4_13_pct": 48,
    "v5_pct": 53
  },
  {
    "label": "Cost per run",
    "v4_13_pct": 16,
    "v5_pct": 26
  },
  {
    "label": "Wall clock time",
    "v4_13_pct": 38,
    "v5_pct": 41
  }
]

Wykres przedstawia aktualny benchmark agentowy projektu z dnia 7 października 2026 roku. Sesje bezinterfejsowego Claude Code 2.1.288 na modelu Opus 5.5 przy domyślnym wysiłku przetworzyły 39 zadań, pięć uruchomień na zadanie i gałąź, łącznie 585 sesji bez umiejętności, z Ponytail v4.13.0 oraz Ponytail 5. Dwanaście zadań to zgłoszenia funkcji w full-stack-fastapi-template autorstwa tiangolo, rzeczywistym repozytorium FastAPI i React, oceniane na podstawie pozostawionego git diff. Reszta to 18 zadań chirurgicznych z ukrytymi testami, sześć próśb o małe aplikacje i trzy prośby typu „pokaż mi przykład”. Bash był wyłączony dla każdej gałęzi. Liczba tokenów wyjściowych spadła o 45 procent przy użyciu Ponytail 5.

Należy zestawić to z danymi dla pojedynczego zapytania (single shot), które projekt opublikował w czerwcu 2026 roku. Pochodziły one z surowego modelu odpowiadającego na pięć codziennych poleceń z regułą i bez niej, raportowane jako mediany z powtarzanych uruchomień. Wykazały one od 80 do 94 procent mniej kodu w modelach Haiku, Sonnet i Opus, a weryfikacja kosztów z 17 czerwca 2026 roku wykazała, że Haiku jest o 63 procent tańszy. Aktualny wynik agentowy dla Ponytail 5 to 53 procent mniej linii kodu, 26 procent niższy koszt i 41 procent krótszy czas rzeczywisty. Projekt szybko skorygował liczbę dla pojedynczego zapytania. Do v4.8.4, 29 czerwca 2026 roku, plik README zawierał już wynik agentowy: „~54% mniej kodu (do 94%)”, z notatką, że wcześniejsze 80 do 94 procent to „sufit dla zadania, a nie średnia”, a liczby dla pojedynczego zapytania przeniesiono do zwiniętej sekcji zatytułowanej „Starsze liczby single-shot”. Sekcja ta szczerze wyjaśniała przyczynę różnicy: bazą dla pojedynczego zapytania jest surowy model, który „wypełnia odpowiedź prozą i opcjami”, co łatwo przebić. W pomiarze z udziałem rzeczywistego agenta wykonującego realną pracę zysk maleje. Pozostaje on jednak prawdziwy, co jest bardziej użytecznym faktem. Czerwcowe uruchomienie agentowe, dwanaście zgłoszeń na Haiku 4.5 z czterema uruchomieniami każde, osiągnęło wynik zbliżony do dzisiejszego, czyli 54 procent mniej linii, a obecny plik README w ogóle nie zawiera już liczb dla pojedynczego zapytania.

Jedno zastrzeżenie pochodzi od samego projektu i to ono decyduje, czy rozwiązanie to będzie przydatne. Oszczędność jest największa tam, gdzie istnieje realna pułapka przekombinowania, a bliska zeru w przypadku kodu, który już był minimalny. Potwierdza to październikowa tabela zadań, w której kilka zadań chirurgicznych osiągnęło taką samą liczbę linii we wszystkich trzech gałęziach. Trzydzieści dziewięć zadań na jednym modelu i jednym hoście, z wyłączonym Bashem, nie stanowi prognozy dla Twojego repozytorium. Jeśli ta liczba ma znaczenie, należy przeprowadzić porównanie na własnych zgłoszeniach, z regułą i bez niej, oraz samodzielnie policzyć linie.

Wzorzec, który można skopiować już dziś bez instalacji czegokolwiek

Drabinka jest tekstem, więc nie potrzeba wtyczki, aby skorzystać z tego pomysłu. Wklej blok taki jak ten do pliku instrukcji, który Twój agent już odczytuje, niezależnie od tego, czy jest to AGENTS.md, CLAUDE.md, czy plik reguł Twojego edytora.

## Before you write code

Climb this list in order. Stop at the first line that applies.

1. Does this need to exist? If not, say so and stop.
2. Does this repo already have it? Reuse the helper.
3. Does the standard library do it? Use it.
4. Does the platform do it natively? Use it.
5. Does an installed dependency do it? Use it.
6. Can it be one line? Write one line.
7. Otherwise write the minimum that works.

Never take the shortcut on: reading the code before changing it, validating
input that crosses a trust boundary, error handling that would otherwise lose
data, security, accessibility, or anything I asked for by name.

Do not add an abstraction I did not ask for. Do not add a dependency without
saying why in one line. Prefer deleting code to adding it.

Mark a deliberate simplification with a comment naming its ceiling and the
upgrade path.

Ostatnia reguła jest warta zastosowania samodzielnie. Konwencja Ponytail w obecnych wydaniach to komentarz oznaczony shortcut:, który określa limit oraz termin aktualizacji (wydania czerwcowe, w tym v4.8.4, oznaczały go jako ponytail:):

# shortcut: global lock, per-account locks if throughput matters

Komentarz to dwie linie pracy, które rozstrzygają kwestię wymagającą inaczej cyklu przeglądu. Informuje on kolejnego czytelnika, że uproszczona wersja była świadomą decyzją, oraz wskazuje warunek, po którego spełnieniu decyzja ta przestaje obowiązywać. Bez tego recenzent nie jest w stanie odróżnić przemyślanego skrótu od czegoś, o czym agent zapomniał, więc musi o to zapytać.

Miejsce umieszczenia bloku jest równie ważne, co jego treść. Plik, który agent wczytuje przy każdym uruchomieniu, steruje każdym przebiegiem, w tym tymi, których nie monitorujesz. Ta różnica jest tematem pisania pliku AGENTS.md, którego Twój agent faktycznie przestrzega i jest powodem, dla którego ten wzorzec powinien znaleźć się w zatwierdzonym pliku, a nie w historii powłoki. W monorepo powinien on znaleźć się w więcej niż jednym zatwierdzonym pliku, ponieważ plik AGENTS.md dla każdego pakietu pozwala zachować zwięzłość reguł w każdym katalogu, zamiast zmuszać agenta do odczytywania konwencji całego drzewa przy każdym uruchomieniu. Umieszczenie nie jest jednak gwarancją i warto wiedzieć, dlaczego agent pomija regułę, którą już wczytał, zanim dojdziesz do wniosku, że drabinka wymaga silniejszego sformułowania.

Gdzie zasada przestaje być słuszna

Drabina jest dostosowana do pracy nad funkcjonalnościami w istniejącej bazie kodu, gdzie ponowne wykorzystanie komponentów jest zazwyczaj możliwe i zazwyczaj poprawne. Gorzej sprawdza się w projektach typu greenfield, ponieważ na szczeblu 2 nie ma czego ponownie użyć, a na szczeblu 5 nie ma nic zainstalowanego. Agent nadal może zatrzymać się na szczeblu 1, bibliotece standardowej, funkcji platformy lub rozwiązaniu jednowierszowym, jednak dwie z najtańszych ścieżek wyjścia są niedostępne, przez co więcej zadań kończy się pisaniem nowego kodu. Metoda ta słabo sprawdza się również w momencie, gdy faktycznie potrzebna jest abstrakcja. Jeśli zamierzasz dodać czwarte wywołanie tego samego skopiowanego bloku, zasada "najkrótszego diffa" dostarczy Ci piątą kopię.

Poziom ultra podda w wątpliwość Twoje wymagania. Do tego właśnie służy ten poziom i stanowi on realny koszt, gdy decyzja została już podjęta, a oczekuje się wykonania pracy. Używaj full do typowych zadań i sięgaj po ultra, gdy podejrzewasz, że problemem jest samo zgłoszenie funkcjonalności.

Żaden blok instrukcji nie uchroni przed błędną interpretacją problemu. Pierwszym punktem zbioru zasad jest zrozumienie kodu przed podjęciem decyzji, co jest najbardziej kosztownym etapem i częścią, której tekst nie wykona za Ciebie. Minimalny diff w niewłaściwej funkcji nadal jest błędną poprawką, a teraz jest to mała, błędna poprawka, którą łatwo zatwierdzić.

Uczciwe podsumowanie jest takie, że Ponytail to starannie napisany prompt, dobrze rozpowszechniony i opatrzony numerami. Nic w nim nie wymaga wtyczki. To, co daje projekt, to fakt, że ktoś poprawnie sporządził listę, przetestował ją w rzeczywistym repozytorium i opublikował metodę obok rezultatu.

FAQ

Czy Ponytail współpracuje z innymi agentami niż Claude Code?

Tak. Jest dostarczany jako umiejętność (skill) dla hostów obsługujących wczytywanie umiejętności, do których należą Claude Code, Codex, OpenCode, Gemini oraz kilka innych wymienionych w README. Edytory, które odczytują pliki reguł, ale nie wczytują umiejętności, takie jak Cursor, Windsurf, Cline czy Copilot, pobierają zawsze aktywny zestaw reguł z odpowiedniego katalogu reguł i nie obsługują poleceń typu slash. Tekst pozostaje taki sam w obu przypadkach, więc rzeczywista różnica polega na tym, czy host utrzymuje ten tekst w kontekście przy każdym kroku, czy tylko po wywołaniu umiejętności.

Czy leniwy agent pominie testy, walidację lub bezpieczeństwo?

Nie, a zestaw reguł stwierdza to wprost. Lista elementów, w których nie wolno być leniwym, obejmuje walidację danych wejściowych na granicach zaufania, obsługę błędów zapobiegającą utracie danych, bezpieczeństwo oraz dostępność. Wymaga również jednego małego, uruchamialnego testu dla każdego nietrywialnego fragmentu logiki. Reguła eliminuje wymyśloną strukturę: abstrakcje, o które nikt nie prosił, oraz zależności, które nie były potrzebne. Jeśli po instalacji agent zaczyna pomijać testy, przyczyną jest inna instrukcja w Twojej konfiguracji, która ma wyższy priorytet – sprawdź plik, który agent wczytuje jako ostatni.

Czy opublikowane dane dotyczące szybkości i kosztów są wiarygodne?

Są to własne pomiary projektu, opublikowane wraz z metodologią, i należy je traktować jako takie. Wyniki jednorazowe z czerwca 2026 roku porównano z modelem bazowym, który uzupełniał odpowiedzi opisami i opcjami, co sam README w tamtym czasie oznaczył jako słaby punkt odniesienia. Obecne dane dotyczące agentów pochodzą z sesji headless Claude Code na modelu Opus 5.5, obejmujących 39 zadań po pięć uruchomień każde, z czego dwanaście to zgłoszenia funkcji w jednym repozytorium FastAPI i React. Są to rzetelne liczby dla tej konfiguracji. Nie stanowią one prognozy dla Twojej bazy kodu, ponieważ wyniki projektu dla poszczególnych zadań pokazują, że oszczędności spadają niemal do zera w przypadku kodu, który już był minimalny.

Czy muszę coś instalować, aby uzyskać korzyści?

Nie. Drabinka to tekst, a wklejenie równoważnego bloku do pliku instrukcji, który Twój agent już odczytuje, zapewnia większość efektu. Wtyczka dostarcza utrzymywaną treść, poziomy intensywności, polecenia przeglądu oraz ścieżkę aktualizacji. Wypróbowanie skopiowanego bloku jest pierwszym krokiem, aby sprawdzić, czy instalacja jest w ogóle konieczna.

Jak powstrzymać bezobsługowego agenta przed nadmierną rozbudową kodu w nocy?

Umieść regułę w pliku instrukcji zawsze aktywnych (always-on), a nie w wiadomości na czacie, aby obowiązywała również w 200. kroku długiego zadania, a nie tylko w 3. kroku. Następnie ogranicz potencjalne szkody: przydziel agentowi kopię roboczą (checkout), którą może zepsuć, zamiast pracować na jedynej kopii, i wymagaj przeglądu różnic (diff) przez człowieka przed scaleniem zmian. Reguła minimalnego diffu ogranicza ilość tekstu do przeczytania. Nie decyduje ona jednak o tym, co trafi do repozytorium i nie powinna tego robić.