Ponytail: jak wymusić na agencie AI pisanie mniej kodu

Czym jest Ponytail

Ponytail to zestaw reguł, dzięki którym 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 zawiera żadnych wykonywalnych elementów. Jest to tekst włączany do instrukcji agenta, dostarczany 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. Zostało utworzone 12 czerwca 2026 roku i do 1 sierpnia 2026 roku przekroczyło próg 90 000 gwiazdek. Najnowsze oznaczone wydanie z 1 sierpnia 2026 roku to v4.8.4, opublikowane 29 czerwca 2026 roku, a strona wydań wymienia dziesięć tagów tylko w okresie między 14 a 29 czerwca. Projekt rozwijający się w takim tempie ulegnie zmianie do czasu, gdy będziesz czytać ten tekst, dlatego przed budowaniem czegokolwiek w oparciu o niego należy przypiąć konkretny tag.

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 już zainstalowana 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.

To kolejność wykonuje pracę, a nie żaden pojedynczy szczebel. Agent poproszony o selektor daty napisze selektor daty, ponieważ napisanie go jest tym, co mu polecono. Drabina sprawia, że najpierw sprawdza szczebel 4, a szczebel 4 mówi, że przeglądarka już posiada <input type="date">. Własny benchmark projektu odnotowuje dokładnie ten przypadek: selektor daty, który bez tej reguły miał 404 linie, po jej zastosowaniu miał 23 linie, ponieważ agent sięgnął po natywny input zamiast budować komponent. Selektor koloru skrócił się z 287 linii do 23 z tego samego powodu. 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, a zbiór reguł mówi o tym bezpośrednio. 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 poprosiłeś 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ł, który stanowi istotę rozwiązania i można go przeczytać w pięć minut.
• skills/ponytail/SKILL.md, definicja umiejętności z podpowiedzią argumentu lite, full lub ultra.
• Pliki reguł w katalogach specyficznych dla edytorów, takich jak .cursor/rules/ oraz .windsurf/rules/, przeznaczone 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 żądany wynik i w jednej linii wskazuje mniej restrykcyjną opcję. full jest ustawieniem domyślnym i wymusza hierarchię. ultra to ustawienie dla zwolenników zasady YAGNI: preferuje usuwanie zamiast dodawania i kwestionuje zasadność samego wymagania.

Hosty obsługujące umiejętności otrzymują również polecenia typu slash. /ponytail ustawia poziom, /ponytail-review sprawdza różnice pod kątem nadmiernej inżynierii, /ponytail-audit weryfikuje całe repozytorium, /ponytail-debt zbiera odroczone skróty, a /ponytail-gain wyświetla kartę wyników benchmarku. Hosty odczytujące wyłącznie pliki reguł otrzymują zestaw reguł bez poleceń.

Aby zapoznać się z kodem źródłowym przed jego zaufaniem, należy sklonować tag zamiast gałęzi:

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

W przypadku Claude Code projekt dokumentuje instalację wtyczki, a te dwie linie są zgodne z dokumentacją z dnia 1 sierpnia 2026:

/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ą ulec zmianie między sesjami. Jest to kompromis, na który użytkownik godzi 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, a nie tylko tę, w której powstała. Dlatego niekontrolowany refaktoryzacja 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 wysyłaniu i odbieraniu, więc diff o połowę mniejszy jest tańszy dwukrotnie: raz w momencie zapisu i ponownie w każdej turze, w której jest odczytywany. To, czy te oszczędności wpłyną na rachunek, zależy od modelu płatności, ponieważ płaska subskrypcja Pro lub Max absorbuje nadmiarowe tokeny, podczas gdy rozliczenie API za token obciąża użytkownika za każdy z nich. W przypadku monitorowania kosztów w konfiguracji self-hosted, 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 mieć 20, 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 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ą tak wiele uwagi stałym instrukcjom, zamiast pojedynczym promptom. 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, aby korzystać z tego, co jest zainstalowane. Każdy pakiet, który agent dodaje z własnej inicjatywy, jest czymś, co trzeba później aktualizować i co trafia do każdego obrazu kontenera budowanego z tego repozytorium.

Co mówią własne wyniki testów porównawczych Ponytail

Projekt publikuje dwa zestawy wyników, które znacząco się od siebie różnią. Oba są oficjalnymi danymi projektu. Żaden z nich nie stanowi niezależnego testu.

[
  {
    "label": "Lines of code",
    "single_shot_pct": 93,
    "agentic_pct": 54
  },
  {
    "label": "Cost per run",
    "single_shot_pct": 63,
    "agentic_pct": 20
  },
  {
    "label": "Wall clock time",
    "single_shot_pct": 74,
    "agentic_pct": 27
  }
]

Kolumna single shot pochodzi z surowego modelu odpowiadającego na mały zestaw promptów z regułą i bez niej, obliczonego jako mediana z powtarzanych uruchomień z 13 i 17 czerwca 2026. Kolumna agentic pochodzi z bezgłowej sesji Claude Code edytującej full-stack-fastapi-templatetiangolo's repository, rzeczywiste repozytorium FastAPI i React, w ramach dwunastu zgłoszeń funkcji z czterema uruchomieniami każde na Haiku 4.5, ocenianych na podstawie pozostawionego git diff.

Należy przeanalizować drugą kolumnę. Wynik agentic to o 54 procent mniej linii kodu, o 20 procent niższy koszt i o 27 procent krótszy czas rzeczywisty, w porównaniu do 93 procent i 74 procent dla tych samych miar w konfiguracji single shot. Plik README uczciwie wyjaśnia przyczynę: bazą dla single shot jest surowy model, który „odpowiada kilkoma opcjami oraz komentarzem”, co jest łatwe do przebicia. W zestawieniu z rzeczywistym agentem wykonującym realną pracę zysk maleje. Pozostaje on jednak realny, co jest bardziej użytecznym faktem.

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 występuje pułapka nadmiernej rozbudowy, a bliska zeru w przypadku kodu, który już był minimalny. Dwanaście zgłoszeń w jednym repozytorium Python i TypeScript nie stanowi prognozy dla Twojego repozytorium. Jeśli ta liczba ma znaczenie, przeprowadź porównanie na własnych zgłoszeniach, z regułą i bez niej, a następnie samodzielnie policz linie.

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

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

Ta ostatnia reguła jest warta zastosowania samodzielnie. Konwencja Ponytail to komentarz oznaczony nazwą narzędzia:

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

Komentarz to dwie linie pracy, które rozstrzygają kwestię, która w przeciwnym razie kosztowałaby cykl przeglądu. Informuje on kolejnego czytelnika, że uproszczona wersja była świadomą decyzją i określa warunek, w którym ta decyzja 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 ładuje przy każdym uruchomieniu, steruje każdym działaniem, 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 znajdować się w więcej niż jednym zatwierdzonym pliku, ponieważ plik AGENTS.md dla każdego pakietu utrzymuje reguły każdego katalogu w zwięzłej formie, zamiast zmuszać agenta do czytania konwencji całego drzewa przy każdym uruchomieniu. Umiejscowienie nie jest jednak gwarancją i warto wiedzieć, dlaczego agent pomija regułę, którą już załadował, zanim dojdziesz do wniosku, że drabina wymaga silniejszego sformułowania.

Gdzie zasada przestaje być słuszna

Drabina jest dostrojona do pracy nad funkcjonalnościami w istniejącej bazie kodu, gdzie ponowne wykorzystanie jest zazwyczaj możliwe i zazwyczaj poprawne. Słabo sprawdza się w projektach typu greenfield, ponieważ szczebel 2 nie ma czego ponownie wykorzystać, a na szczeblu 5 nic nie jest zainstalowane, więc agent za każdym razem spada na szczebel 7. Słabo sprawdza się również w momencie, gdy faktycznie potrzebna jest abstrakcja. Jeśli zamierzasz dodać czwarte wywołanie tego samego skopiowanego bloku, "najkrótszy diff" dostarczy ci piątą kopię.

Poziom ultra zakwestionuje twoje wymagania. Do tego właśnie służy ten poziom i stanowi to realny koszt, gdy decyzja została już podjęta, a ty chcesz, aby praca została wykonana. Używaj full do zwykłych zadań i sięgaj po ultra, gdy podejrzewasz, że problemem jest samo żądanie funkcjonalności.

Żaden blok instrukcji nie uchroni cię przed błędnym odczytaniem problemu. Pierwszym punktem zbioru zasad jest zrozumienie kodu przed podjęciem decyzji, co jest częścią kosztowną i taką, której tekst nie wykona za ciebie. Minimalny diff w niewłaściwej funkcji to nadal niewłaściwa poprawka, 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ść dla hostów obsługujących umiejętności; lista ta obejmuje Claude Code, Codex, OpenCode, Gemini oraz kilka innych wymienionych w pliku README. Edytory, które odczytują pliki reguł, ale nie ładują umiejętności, takie jak Cursor, Windsurf, Cline i 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 zapytaniu, 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 "nigdy nie bądź leniwy w kwestii" wymienia walidację danych wejściowych na granicach zaufania, obsługę błędów zapobiegającą utracie danych, bezpieczeństwo i dostępność, a także wymaga jednego małego, uruchamialnego testu dla każdego fragmentu nietrywialnej 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 agent zaczyna pomijać testy po instalacji, przyczyną jest inna instrukcja w Twojej konfiguracji, która ma wyższy priorytet niż ta; sprawdź plik, który agent ładuje jako ostatni.

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

Są to własne pomiary projektu, opublikowane wraz z metodologią, i należy je interpretować w ten sposób. Liczby dla pojedynczego zapytania porównują wynik z surowym modelem, który odpowiada z opcjami i komentarzem, co sam plik README oznacza jako słaby punkt odniesienia. Liczby dla agenta pochodzą z bezgłowej sesji Claude Code w jednym repozytorium FastAPI i React, dwunastu zgłoszeń, czterech przebiegów każde, na modelu Haiku 4.5. Są to uczciwe liczby dla tej konfiguracji. Nie stanowią one prognozy dla Twojej bazy kodu, ponieważ projekt zaznacza również, że oszczędności spadają niemal do zera w przypadku kodu, który już wcześniej był minimalny.

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

Nie. Drabinka jest tekstem, a wklejenie równoważnego bloku do pliku instrukcji, który Twój agent już odczytuje, zapewnia większość efektu. Wtyczka dostarcza utrzymywane sformułowania, poziomy intensywności, polecenia przeglądu oraz ścieżkę aktualizacji. Wypróbowanie skopiowanego bloku w pierwszej kolejności jest odpowiedzią na pytanie, czy instalacja jest w ogóle konieczna.

Jak powstrzymać nienadzorowanego agenta przed nadmierną rozbudową kodu w nocy?

Umieść regułę w pliku instrukcji zawsze aktywnych, a nie w wiadomości na czacie, aby obowiązywała w 200. kroku długiego procesu, a nie tylko w 3. kroku. Następnie ogranicz szkody w inny sposób: daj agentowi kopię roboczą, którą może zepsuć, zamiast pracować na jedynej kopii, i wymagaj przeglądu diff przez człowieka przed scaleniem zmian. Reguła minimalnego diffa zmniejsza ilość tekstu do przeczytania. Nie decyduje ona o tym, co zostanie wdrożone, i nie powinna tego robić.