Ponytail: reguły, które ograniczają kod agenta AI

Czym jest Ponytail

Ponytail to zestaw reguł, który skłania agenta AI do pisania mniejszej ilości kodu. Projekt opisuje się jednym zdaniem: „Sprawia, że agent AI myśli jak najbardziej leniwy starszy programista w zespole. Najlepszy kod to kod, którego nigdy nie napisano”. Projekt jest objęty licencją MIT. Nie zawiera własnego środowiska uruchomieniowego i nie wykonuje żadnych operacji. Jest tekstem dodawanym do instrukcji agenta. Jest udostępniany 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. Utworzono je 12 June 2026, a do 1 August 2026 uzyskało ponad 90,000 gwiazdek. Najnowsze oznaczone wydanie z 1 August 2026 to v4.8.4, opublikowane 29 June 2026. Na stronie wydań znajduje się dziesięć oznaczeń utworzonych wyłącznie w okresie od 14 do 29 June. Projekt rozwijany w takim tempie zmieni się do czasu lektury tego tekstu, dlatego przed zbudowaniem czegokolwiek na jego podstawie należy przypiąć oznaczenie.

Pomysł przed narzędziem: zatrzymanie się na pierwszym wystarczającym szczeblu

Podstawą Ponytail jest drabina decyzyjna. Agent przechodzi przez nią przed napisaniem czegokolwiek i zatrzymuje się na pierwszym szczeblu, który wystarcza.

1. Czy to w ogóle musi istnieć? To zasada YAGNI (nie będzie tego potrzebować). Jeśli odpowiedź brzmi „nie”, należy to pominąć.
2. Czy to już istnieje w tym kodzie? Należy ponownie użyć istniejącego pomocnika lub wzorca.
3. Czy biblioteka standardowa to obsługuje? Należy jej użyć.
4. Czy natywna funkcja platformy to obsługuje? Należy jej użyć.
5. Czy problem rozwiązuje już zainstalowana zależność? Należy jej użyć.
6. Czy można to zapisać w jednym wierszu? Należy użyć jednego wiersza.
7. Dopiero wtedy należy napisać minimalny działający kod.

To kolejność wykonuje pracę, a nie pojedynczy szczebel. Agent poproszony o selektor dat napisze selektor dat, ponieważ właśnie to polecono mu zrobić. Drabina wymusza sprawdzenie najpierw szczebla 4, a ten wskazuje, że przeglądarka ma już <input type="date">. Własne notatki z testów porównawczych projektu opisują dokładnie ten przypadek: selektor dat, który bez tej zasady miał 404 wiersze, z zasadą miał 23 wiersze, ponieważ agent użył natywnego pola zamiast budować komponent. Selektor kolorów zmniejszył się z 287 wierszy do 23 z tego samego powodu.

„Leniwy” nie oznacza tutaj niedbały, co reguły stwierdzają bezpośrednio. Ich lista obszarów, 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 wprost. Reguły wymagają również jednego małego, uruchamialnego testu dla każdego elementu nietrywialnej logiki. Zasada ogranicza wymyślanie rozwiązań. Nie ogranicza poprawności.

Co zawiera repozytorium

• AGENTS.md — zestaw reguł działający stale, który zawiera całą koncepcję w jednym pliku możliwym do przeczytania w pięć minut.
• skills/ponytail/SKILL.md — definicja umiejętności z podpowiedzią argumentu: lite, full lub ultra.
• Pliki reguł w katalogach specyficznych dla edytora, takich jak .cursor/rules/ i .windsurf/rules/, przeznaczone dla hostów, które odczytują reguły, ale nie ładują umiejętności.
• hooks/, benchmarks/, examples/ i scripts/.

Argument intensywności określa siłę egzekwowania reguły. lite tworzy wymagany wynik i w jednym wierszu wskazuje opcję wymagającą mniej pracy. full jest wartością domyślną i wymusza stosowanie kolejnych poziomów. ultra to skrajne ustawienie zgodne z zasadą YAGNI: preferuje usuwanie zamiast dodawania i kwestionuje nawet samo wymaganie.

Hosty obsługujące umiejętności otrzymują także polecenia slash. /ponytail ustawia poziom, /ponytail-review sprawdza diff pod kątem nadmiernej złożoności, /ponytail-audit sprawdza całe repozytorium, /ponytail-debt zbiera odroczone skróty, a /ponytail-gain wyświetla kartę wyników testu porównawczego. Hosty odczytujące wyłącznie pliki reguł otrzymują zestaw reguł bez poleceń.

Aby sprawdzić kod źródłowy przed jego użyciem, należy sklonować tag zamiast gałęzi:

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

W Claude Code projekt opisuje zamiast tego instalację wtyczki, a poniższe 2 wiersze są zgodne z dokumentacją z 1 August 2026:

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

Ścieżka wtyczki korzysta z gałęzi domyślnej, a nie z tagu. Oznacza to, że instrukcje sterujące agentem mogą zmienić się między sesjami bez dodatkowego ostrzeżenia. Jest to kompromis za wygodę korzystania z polecenia aktualizacji.

Dlaczego leniwy agent jest tańszy na VPS

Różnice w kodzie generowane przez agenta pozostają w kontekście rozmowy. W następnej turze model odczytuje je ponownie wraz z każdym plikiem, który otworzył w celu ich utworzenia. Zmiana obejmująca 500 wierszy obciąża więc każdą późniejszą turę sesji, a nie tylko turę, w której została wygenerowana. Dlatego niekontrolowana refaktoryzacja sprawia, że agent wydaje się coraz wolniejszy i mniej skuteczny w miarę trwania sesji: okno kontekstu zapełnia się własnym wyjściem agenta, więc pozostaje mniej miejsca na właściwy kod. Cały temat zarządzania oknem kontekstu agenta programistycznego polega na utrzymaniu tego pod kontrolą.

Tokeny są naliczane zarówno za dane wejściowe, jak i wyjściowe, dlatego różnica o połowę mniejsza kosztuje dwa razy mniej: raz podczas jej generowania, a następnie w każdej turze, w której jest ponownie odczytywana. W przypadku monitorowania kosztów konfiguracji hostowanej samodzielnie plik instrukcji jest narzędziem, którego użycie nic nie kosztuje. Kontrolowanie kosztów agenta AI należy rozpocząć od objętości wyjścia, a sposób wykorzystywania tokenów przez agenta programistycznego wyjaśnia, dlaczego ponowne odczytywanie ma większe znaczenie, niż się zwykle oczekuje.

Człowiek nadal analizuje różnice w kodzie. Zmiana obejmująca 400 wierszy, która powinna obejmować 20 wierszy, zużywa uwagę osoby wykonującej przegląd, a uwaga jest zasobem, który wyczerpuje się jako pierwszy. Nikt nie analizuje z taką samą starannością czwartej długiej różnicy tego dnia jak pierwszej, dlatego nadmierne rozbudowywanie kodu nie powoduje wyłącznie straty czasu. Obniża także po cichu jakość przeglądu, którego zadaniem jest wykrywanie błędów.

Na serwerze stawka jest wyższa, ponieważ agent często działa bez nadzoru. Agent pracujący w sesji tmux lub uruchamiany przez harmonogram ma wiele godzin na rozwijanie błędnej decyzji, zanim zostanie ona zauważona. To praktyczne ryzyko opisane w uruchamianiu agenta programistycznego na VPS, dlatego osoby zajmujące się inżynierią pętli poświęcają tak dużo uwagi instrukcjom stałym, a nie pojedynczym promptom. Reguła zapisana w pliku ładowanym przy każdym uruchomieniu obowiązuje w turze 200. Reguła wpisana na czacie obowiązuje w turze 3.

Nowe zależności to kolejny ukryty koszt. Punkt 5 mówi, aby używać tego, co jest zainstalowane. Każdy pakiet dodany samodzielnie przez agenta jest elementem, który później trzeba aktualizować, oraz który trafia do każdego obrazu kontenera tworzonego z tego repozytorium.

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

Projekt publikuje dwa zestawy wyników. Różnią się one znacznie. Oba zestawy pochodzą z opublikowanych danych projektu. Żaden nie jest niezależnym testem.

[
  {
    "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 testów podstawowego modelu odpowiadającego na mały zestaw promptów z regułą i bez niej. Wyniki przedstawiono jako mediany z powtarzanych uruchomień przeprowadzonych 13 i 17 June 2026. Kolumna agentic pochodzi z bezinterfejsowej sesji Claude Code, która modyfikowała full-stack-fastapi-template firmy tiangolo, czyli rzeczywiste repozytorium FastAPI i React, w ramach twelve zgłoszeń funkcjonalnych. Każde zgłoszenie uruchomiono four razy z użyciem Haiku 4.5. Oceniano zmiany pozostawione w git diff.

Należy odczytać drugą kolumnę. Wynik agentic oznacza 54 procent mniej wierszy kodu, 20 procent niższy koszt i 27 procent krótszy czas rzeczywisty względem 93 procent i 74 procent dla tych samych miar w konfiguracji single shot. README wyjaśnia przyczynę. Punkt odniesienia single shot to podstawowy model, który „udziela odpowiedzi z kilkoma opcjami i komentarzem”, a to łatwo przewyższyć. Po porównaniu z rzeczywistym agentem wykonującym rzeczywistą pracę przewaga jest mniejsza. Nadal jednak występuje, co jest bardziej użyteczną informacją.

Jedno zastrzeżenie pochodzi od samego projektu i decyduje o tym, czy rozwiązanie będzie pomocne w danym przypadku. Oszczędność jest największa tam, gdzie rzeczywiście występuje ryzyko nadmiernej implementacji. W przypadku kodu, który już jest minimalny, oszczędność jest bliska zeru. Twelve zgłoszeń w jednym repozytorium Python i TypeScript nie pozwala przewidywać wyników dla danego repozytorium. Jeżeli ta wartość ma znaczenie, należy przeprowadzić porównanie na własnych zgłoszeniach, z regułą i bez niej, a następnie samodzielnie policzyć wiersze.

Wzorzec, który można zastosować już dziś bez instalowania czegokolwiek

Drabina ma postać tekstu, więc do zastosowania tej koncepcji nie jest potrzebna wtyczka. Należy wkleić blok taki jak poniżej do pliku instrukcji, który agent już odczytuje, niezależnie od tego, czy jest to AGENTS.md, CLAUDE.md, czy plik reguł 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 zasługuje na osobne omówienie. Konwencja Ponytail polega na użyciu komentarza oznaczonego nazwą narzędzia:

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

Ten komentarz obejmuje dwa etapy pracy i rozstrzyga kwestię, która w przeciwnym razie wymagałaby dodatkowej iteracji przeglądu. Informuje kolejnego czytelnika, że prosta wersja była świadomą decyzją, oraz określa warunek, po którego spełnieniu decyzja przestaje obowiązywać. Bez tego komentarza osoba wykonująca przegląd nie może odróżnić przemyślanego uproszczenia od sytuacji, w której agent pominął wymaganie, dlatego musi zadać pytanie.

Znaczenie ma zarówno treść bloku, jak i jego umiejscowienie. Plik ładowany przez agenta przy każdym uruchomieniu wpływa na każde uruchomienie, także na te, których się nie monitoruje. Ta różnica jest tematem tworzenia pliku AGENTS.md, którego agent rzeczywiście przestrzega, a także powodem, dla którego ten wzorzec powinien znajdować się w wersjonowanym pliku, a nie w historii powłoki.

Kiedy zasada przestaje być właściwa

Ta drabina jest dostrojona do pracy nad funkcjami w istniejącej bazie kodu, w której ponowne użycie jest zwykle możliwe i zwykle właściwe. Słabo sprawdza się w projekcie greenfield, ponieważ szczebel 2 nie ma niczego do ponownego użycia, a na szczeblu 5 nic nie jest zainstalowane, więc agent za każdym razem przechodzi do szczebla 7. Słabo sprawdza się również wtedy, gdy rzeczywiście potrzebna jest abstrakcja. Jeśli ma zostać dodany czwarty użytkownik tego samego skopiowanego bloku, „najkrótszy diff” zapewni piątą kopię.

Poziom ultra zakwestionuje wymagania. Do tego właśnie służy ten poziom, a jego zastosowanie wiąże się z rzeczywistym kosztem, gdy decyzja została już podjęta i oczekuje się wykonania pracy. Do zwykłych zadań należy używać full, a po ultra sięgać wtedy, gdy podejrzewa się, że problemem jest samo żądanie funkcji.

Żaden blok instrukcji nie chroni przed błędną interpretacją problemu. Pierwszy punkt zestawu reguł również wymaga zrozumienia kodu przed podjęciem decyzji. Jest to najbardziej kosztowna część i właśnie tej części tekst nie może wykonać za użytkownika. Minimalny diff w niewłaściwej funkcji nadal oznacza niewłaściwą poprawkę, a teraz jest to mała, niewłaściwa poprawka, którą łatwo zaakceptować.

Uczciwe podsumowanie jest takie: Ponytail to starannie napisany prompt, dobrze rozpowszechniony i uzupełniony liczbami. Do jego użycia nie jest wymagany plugin. Wartością projektu jest to, że ktoś właściwie opracował tę listę, przetestował ją na rzeczywistym repozytorium i opublikował metodę obok rezultatu.

FAQ

Czy Ponytail działa z agentami innymi niż Claude Code?

Tak. Jest dostarczany jako skill dla hostów, które ładują skills. Do tej grupy należą Claude Code, Codex, OpenCode, Gemini i kilka innych wymienionych w pliku README. Edytory, które odczytują pliki reguł, ale nie ładują skills, takie jak Cursor, Windsurf, Cline i Copilot, pobierają reguły zawsze aktywne z odpowiedniego katalogu rules i nie udostępniają poleceń slash. Treść jest taka sama w obu przypadkach. Różnica polega na tym, czy host utrzymuje tę treść w kontekście przy każdej turze, czy tylko po uruchomieniu skill.

Czy agent działający bez zbędnych opóźnień pomija testy, walidację lub zabezpieczenia?

Nie. Reguły określają to bezpośrednio. Lista elementów, przy których agent „never lazy about”, obejmuje walidację danych wejściowych na granicach zaufania, obsługę błędów zapobiegającą utracie danych, bezpieczeństwo i dostępność. Reguły wymagają także jednego małego, wykonywalnego testu dla każdego fragmentu nietrywialnej logiki. Usuwana reguła dotyczy tworzenia niepotrzebnej struktury: abstrakcji, których nikt nie zamawiał, oraz zależności, których nikt nie potrzebował. Jeśli po instalacji agent zaczyna pomijać testy, przyczyną jest inna instrukcja w Twojej konfiguracji, która ma wyższy priorytet. Należy wtedy odczytać plik ładowany przez agenta jako ostatni.

Czy opublikowane wartości szybkości i kosztu są wiarygodne?

Są to własne pomiary projektu, opublikowane wraz z zastosowaną metodą, i tak należy je interpretować. Wartości dla pojedynczego wywołania porównują wynik z podstawowym modelem, który odpowiada opcjami i komentarzami. Sam plik README wskazuje, że jest to słaby punkt odniesienia. Wartości dla pracy agentowej pochodzą z bezgłowej sesji Claude Code przeprowadzonej na jednym repozytorium FastAPI i React, dla dwunastu zgłoszeń, po cztery uruchomienia każdego, z użyciem Haiku 4.5. Są to wiarygodne wartości dla tej konfiguracji. Nie stanowią prognozy dla Twojej bazy kodu, ponieważ projekt wskazuje również, że oszczędność spada niemal do zera w przypadku kodu, który już wcześniej był minimalny.

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

Nie. Drabina jest tekstem. Wklejenie równoważnego bloku do pliku instrukcji, który agent już odczytuje, zapewnia większość efektu. Plugin zapewnia utrzymywaną treść, poziomy intensywności, polecenia przeglądu oraz ścieżkę aktualizacji. Najpierw można wkleić skopiowany blok. Jest to odpowiedź na poziomie rung 1 na pytanie, czy instalacja w ogóle musi istnieć.

Jak uniemożliwić agentowi działającemu bez nadzoru nadmierne rozbudowywanie projektu w nocy?

Regułę należy umieścić w pliku instrukcji zawsze aktywnych, a nie w wiadomości czatu. Dzięki temu będzie stosowana w turze 200 długiego uruchomienia, a nie tylko w turze 3. Następnie należy osobno ograniczyć skutki działania: udostępnić agentowi checkout, który może zostać uszkodzony, zamiast jedynej kopii, oraz wymagać przeglądu różnic przez człowieka przed scaleniem zmian. Reguła minimalnych różnic ogranicza ilość kodu wymagającego odczytania. Nie decyduje jednak, które zmiany zostaną wprowadzone, i nie powinna tego robić.