Jak działa unlazy i metoda Depth Tree

Na czym polega działanie unlazy

Umiejętność unlazy to narzędzie agenta stworzone w celu wyeliminowania jednego błędu: sytuacji, w której agent programistyczny zgłasza wykonanie zadania, zanim faktycznie je ukończy. Jej podstawą jest Depth Tree, czyli metoda dzielenia zadania na warstwy, w której tylko najniższa warstwa jest traktowana jako rzeczywista praca. Wersja 2 przeniosła mechanizm egzekwowania z opisu tekstowego do plików, dzięki czemu agent musi udowodnić ukończenie zadania poprzez listę uruchamialnych poleceń, zamiast jedynie deklarować jego zakończenie.

Narzędzie jest publikowane przez Leonxlnx pod adresem github.com/Leonxlnx/unlazy na licencji MIT. Niniejszy przewodnik dotyczy wersji 2.0.0, wydanej 2026-08-10. Umiejętności w tym obszarze zmieniają się szybko, dlatego przed wdrożeniem tych rozwiązań w środowisku produkcyjnym należy zapoznać się z plikiem CHANGELOG w repozytorium.

Pojęcie umiejętności (skill) oznacza tutaj standardowy element: plik SKILL.md, który środowisko uruchomieniowe (harness) wczytuje do kontekstu modelu, gdy zadanie pasuje do opisu. Jeśli ten mechanizm jest nieznany, należy zacząć od lektury czym jest umiejętność agenta i jak harness ją wczytuje. unlazy składa się ze zwykłych plików markdown oraz kilku skryptów Node, więc nie wymaga własnego serwera ani klucza API.

Dlaczego agenci zatrzymują się na 80 procentach i pomijają trzecią instrukcję

To zachowanie ma rozpoznawalny schemat. Użytkownik prosi o cztery rzeczy. Odpowiedź obejmuje pierwszą, drugą i czwartą. Podsumowanie końcowe wymienia wszystkie cztery jako wykonane. Żaden element nie wygenerował błędu, więc nic nie zostało oznaczone, a lukę odkrywa się tydzień później.

Dokumentacja unlazy README opiera to na opublikowanych pracach dotyczących lenistwa modeli, cytując „przedwczesne ucinanie odpowiedzi i częściowe spełnianie wieloczęściowych żądań” (cytowanie arXiv 2512.20662). To samo README jasno określa założenie projektowe: tekst nie jest w stanie wymusić tekstu. Polecenie agentowi, aby bardziej się postarał, jest kolejnym tekstem dodanym do tego samego kontekstu, który spowodował niedociągnięcia.

Dlatego wersja 2 przechowuje swój stan w plikach. Pole wyboru w GATES.md znajduje się poza zakresem uznaniowości modelu. Albo pod polem znajduje się linia z dowodem, albo jej nie ma, a skrypt może to zweryfikować bez pytania agenta.

Drzewo głębokości, warstwa po warstwie

Drzewo głębokości (Depth Tree) to dekompozycja z określoną zasadą dotyczącą miejsca wykonywania pracy. Zgodnie z dokumentacją metody:

Dziel w naturalnych punktach podziału, binarnie tam, gdzie pozwalają na to naturalne punkty, do N warstw głębokości.

Liście są jedynymi miejscami, w których odbywa się właściwa praca; każda warstwa powyżej nich służy dekompozycji i integracji.

Liść jest większy niż pojedynczy punkt listy. Dokumentacja wyznacza dolny limit wielkości:

Liść to realna jednostka pracy. Dziesięć lub więcej minut skupionego wysiłku, jeden spójny produkt końcowy, jeden plik typu gates.

Ten limit zapobiega przekształceniu głębokiego drzewa w zajmowanie się pozorami pracy. Jeśli liść brzmi „zmień nazwę zmiennej”, nie spełnia testu, a podział powyżej niego był zbyt głęboki o jedną warstwę.

Każdy liść przechodzi następnie cztery etapy: pełna implementacja bez użycia symboli zastępczych, ponowne odczytanie w sposób, w jaki zrobiłby to ekspert w danej dziedzinie, poszukiwanie defektów oraz dopracowanie tam, gdzie jest to bezkosztowe. Te etapy to drugi powód, dla którego liść musi mieć określony limit wielkości. Wykonywanie czterech etapów dla dwuminutowej zmiany to tylko teatr.

Głębokość wybiera się w momencie wywołania umiejętności:

/unlazy tree 5 refactor the payment module

Język naturalny również działa, ponieważ opis umiejętności dopasowuje się do intencji, a nie do konkretnej komendy typu slash:

tree 3 build the landing page and do not stop until every gate is checked

Dokumentacja podaje zakresy głębokości. tree 2 lub 3 to funkcja, usuwanie błędu lub dokument, realizowane samodzielnie w jednej sesji w ramach 2 do 4 liści. tree 4 lub 5 to podsystem, refaktoryzacja lub poważny przegląd, gdzie 8 do 16 liści to „więcej, niż jeden kontekst jest w stanie dobrze pomieścić”. tree 6 lub 7 to cały projekt, prowadzony w trybie orkiestrowanym, z liśćmi przypisanymi do rozłącznych jednostek pracy.

Jeśli nie określisz głębokości, umiejętność otrzymuje polecenie „wybierz najmniejsze N, którego liście odpowiadają naturalnym częściom zadania” i ma wyraźny zakaz domyślnego schodzenia o poziom głębiej. Głębokość opisuje pracę, więc zawyżanie tej liczby nie przekłada się na jakość.

Jak wygląda plik bramek

Przed rozpoczęciem jakichkolwiek prac agent zapisuje kryteria akceptacji w pliku bramek (gates file). Każda bramka to pole wyboru z przypisanym poleceniem.

# Gates: pricing section

- [ ] G1: three tiers render with real copy
  CHECK: node check.js pricing --tiers
  EXPECT: 3/3 tiers ok
  EVIDENCE: pending

- [ ] G2: annual toggle changes both price and label
  CHECK: node check.js pricing --toggle
  EXPECT: toggle ok
  EVIDENCE: pending

CHECK to polecenie. EXPECT to wynik, który jest uznawany za zaliczenie. EVIDENCE zaczyna się od pending i musi zostać zastąpione tym, co faktycznie wyświetliło polecenie. Narzędzie dostarcza scripts/gate-check.mjs do skanowania tych plików i raportowania, które bramki są nadal otwarte, co oznacza, że można przeprowadzić audyt wykonania bez czytania transkrypcji.

Filozofia ta mieści się w jednym wierszu, a SKILL.md zapisuje ją w następujący sposób:

Raport to zestaw twierdzeń popartych rejestrem, a nie subiektywne odczucie ukończenia pracy.

Obowiązuje zasada „brak raportu, dopóki rejestr nie jest pełny”, wraz z regułą raportowania, że każda liczba w podsumowaniu końcowym jest ponownie mierzona w momencie tworzenia raportu lub oznaczana jako niezweryfikowana. Bramka nie może zostać zamknięta tylko dlatego, że agent uważa pracę za zakończoną, ponieważ jej zamknięcie oznacza wklejenie wyniku, który albo jest zgodny z EXPECT, albo nie.

Należy tworzyć bramki, które może uruchomić osoba trzecia. „Wygląda dobrze” nie jest weryfikacją. test -s dist/index.html && echo ok wyświetlające ok jest weryfikacją, ponieważ kończy się wyraźnym błędem w przypadku pustego lub brakującego pliku.

Kontrakt PLAN.md przed rozpoczęciem prac równoległych

Gdy drzewo zadań staje się na tyle rozbudowane, że poszczególne gałęzie działają w odrębnych kontekstach, przestają one współdzielić założenia. Odniesienie do metody wprowadza kontrakt przed fazą rozproszenia (fan-out):

Kontrakty przed rozproszeniem. Interfejsy, własność danych, nazewnictwo oraz konwencje obsługi błędów muszą zostać zawarte w pliku PLAN.md, zanim jakakolwiek gałąź rozpocznie pracę.

Powód jest konkretny. Dwóm podagentom, z których każdy otrzyma polecenie "dodaj obsługę błędów", stworzy dwa różne formaty błędów. Obie gałęzie przejdą własne testy, ponieważ każda z nich jest poprawna lokalnie. Awaria pojawi się dopiero w miejscu ich połączenia. Bramki gałęzi (branch gates) istnieją właśnie na tę okoliczność: bramki gałęzi dowodzą, że "dzieci zostały scalone, interfejsy są zgodne, zachowanie end-to-end jest poprawne, a regresje u rodzeństwa nie występują".

W trybie orkiestrowanym sterownik przekazuje każdemu podagentowi sekcję kontraktu z pliku PLAN.md, a nie cały plik ani historię sterownika, wraz z plikiem bramek danego podagenta w wersji oryginalnej. Gdy podagent kończy pracę, sterownik samodzielnie ponownie uruchamia testy. Podagent, który "odznaczył własne pola bez dowodów", jest odsyłany z powrotem ze wskazaniem konkretnych niespełnionych bramek.

Orkiestracja posiada próg opłacalności. Jeśli praca zajmuje mniej niż około pół godziny, dokumentacja zaleca pracę w trybie jednoosobowym. Każdy podagent musi od podstaw zbudować zrozumienie zadania, a koszt tej konfiguracji przewyższa zysk z dodatkowej uwagi.

Jak zainstalować umiejętność unlazy?

Zalecaną metodą jest użycie CLI dla umiejętności:

npx skills add Leonxlnx/unlazy

Instalacja ręczna polega na sklonowaniu repozytorium do katalogu umiejętności agenta:

git clone https://github.com/Leonxlnx/unlazy ~/.claude/skills/unlazy

git clone https://github.com/Leonxlnx/unlazy ~/.codex/skills/unlazy

Następnie należy sprawdzić, czy pliki zostały poprawnie umieszczone:

ls ~/.claude/skills/unlazy/SKILL.md

Wyświetlenie ścieżki oznacza, że plik znajduje się na dysku. Błąd No such file or directory oznacza, że klonowanie trafiło w inne miejsce, zazwyczaj z powodu nieistnienia katalogu umiejętności o oczekiwanej nazwie, co spowodowało utworzenie nowego przez git. Nie należy polegać wyłącznie na komunikacie agenta. Instrukcja instalacji w pliku README kończy się tym samym ostrzeżeniem: „Nie informuj o zakończeniu instalacji, dopóki fizycznie nie zweryfikujesz obecności pliku na dysku”.

W przypadku środowiska bez mechanizmu ładowania umiejętności, należy wkleić zawartość pliku SKILL.md do promptu systemowego lub pliku z regułami. Jest to udokumentowana metoda awaryjna, dzięki której rozwiązanie działa w Claude Code, Codex, Cursor oraz każdym innym narzędziu odczytującym instrukcje w formacie Markdown. Aby dowiedzieć się, co zapewnia poprawne ładowanie pliku SKILL.md, warto zapoznać się z sekcją tworzenie własnej umiejętności agenta, która opisuje frontmatter oraz dopasowywanie opisów decydujące o aktywacji umiejętności.

Czy Stop hook działa poza Claude Code?

Nie, i jest to kwestia wymagająca precyzji. Wszystko powyżej to instrukcje, a instrukcje mogą być ignorowane. Jedynym elementem wymuszania strukturalnego jest Stop hook, który stanowi funkcję Claude Code.

node <path-to-skill>/scripts/install-hooks.mjs            # this project only (settings.local.json)
node <path-to-skill>/scripts/install-hooks.mjs --global   # every project
node <path-to-skill>/scripts/install-hooks.mjs --uninstall

Stop hook uruchamia się w momencie, gdy agent próbuje zakończyć swoją turę. Skanuje on pliki gates i blokuje zakończenie tury, dopóki warunki nie zostaną spełnione, dzięki czemu tura nie może zakończyć się z niezaznaczonym polem. Odczytuje on pliki i nie wykonuje żadnych wywołań modelu, dlatego w README zaznaczono, że kosztuje to zero tokenów. Informacje o ogólnym mechanizmie oraz innych zdarzeniach, do których można się podpiąć, znajdują się w sposób wyzwalania hooków Claude Code w trakcie tury.

Posiada on zawór bezpieczeństwa, co jest ważniejsze, niż mogłoby się wydawać. Jeśli agent nie poczyni żadnych postępów w przechodzeniu przez bramki w ciągu sześciu kolejnych zablokowanych prób zakończenia tury, hook przepuszcza go z ostrzeżeniem, zamiast go blokować. Linia ABANDON: <gate> <reason> jest zawsze honorowana jako uczciwe wyjście. Bez tych dwóch mechanizmów ratunkowych, bramka niemożliwa do przejścia w danym środowisku zużywałaby tokeny, dopóki sesja nie zostałaby przerwana ręcznie.

W przypadku Codex, Cursor lub jakiegokolwiek innego środowiska, install-hooks.mjs nie ma gdzie się zainstalować. Użytkownik nadal otrzymuje plik gates i możliwe do uruchomienia testy, jednak brak jest strukturalnych zabezpieczeń powstrzymujących model przed przedwczesnym zakończeniem tury. W takim scenariuszu plik gates jest dokumentem, który należy przeczytać samodzielnie.

unlazy czy ponytail: co wybrać?

Te dwie umiejętności zyskały popularność w tym samym sezonie i wpływają na objętość kodu w przeciwnych kierunkach, co ułatwia ich pomylenie.

ponytail sprawia, że agent zachowuje się jak starszy programista, którego pierwszym pytaniem jest to, czy dany kod w ogóle musi istnieć. Ogranicza zakres, preferuje bibliotekę standardową i zmniejsza rozmiar diffa. unlazy zakłada, że zakres został już ustalony i zwiększa nakład pracy, dopóki każda część zadania nie zostanie ukończona i zweryfikowana.

Wybór należy uzależnić od rodzaju obserwowanego problemu. Jeśli agent zamienia małą funkcjonalność w cały framework, należy wybrać umiejętność ponytail i jej personę leniwego starszego programisty. Jeśli agent pozostawia trzeci z czterech punktów żądania niedokończony, a następnie zgłasza sukces, należy wybrać unlazy.

Możliwe jest uruchomienie obu, przy czym kolejność ma znaczenie. Najpierw należy ustalić zakres za pomocą pytania ponytail, a następnie przekazać uzgodniony zakres do bramek unlazy. Zrobienie tego w odwrotnej kolejności spowoduje zbudowanie drzewa zależności dla pracy, którą ponytail by usunął, co wymusi poniesienie kosztów czasowych dla każdego z tych elementów. Ta kolejność jest moją rekomendacją, a nie udokumentowaną integracją między tymi dwoma projektami.

Jaki jest koszt głębokości w przypadku agenta hostowanego na VPS?

Głębokość jest mnożnikiem wysiłku, a wysiłek to tokeny. Na serwerze VPS, gdzie agent korzysta z własnego klucza API, ten mnożnik oznacza bezpośrednie koszty finansowe.

[
  {
    "label": "Skill run vs no skill, output tokens",
    "low_multiplier": 1.6,
    "high_multiplier": 3.9
  },
  {
    "label": "tree 6 vs tree 3, total cost",
    "low_multiplier": 1.0,
    "high_multiplier": 1.5
  }
]

Powyższe dane pochodzą z testów autorów z dnia 2026-08-10. Nie przeprowadzaliśmy własnej weryfikacji tych wyników, dlatego należy traktować je jako przybliżony model, a nie prognozę. Tryb Solo zwiększył wydajność od około 1.6 do 3.9 razy względem wartości bazowej, podczas gdy przejście z drzewa 3 do drzewa 6 w ramach jednego kontekstu dodało tylko od 1.0 do 1.5 razy, co jest wynikiem znacznie niższym niż ośmiokrotny wzrost, którego można by oczekiwać po trzech dodatkowych podziałach binarnych.

Większa głębokość nie oznacza proporcjonalnie wyższych kosztów, ponieważ głębokość redystrybuuje wysiłek, zamiast dodawać kolejne konteksty. Dokumentacja ekonomii tokenów jasno wskazuje źródło mnożnika kosztów: „To orkiestracja mnoży koszty i powinna to robić, ponieważ każdy liść wymaga nowego kontekstu”. Tryb Solo mnoży tokeny wyjściowe wewnątrz jednego kontekstu. Tryb orkiestrowany mnoży konteksty, a każdy nowy kontekst przed wykonaniem jakiegokolwiek użytecznego zadania ponownie odczytuje kontrakt oraz plik bramek (gates file).

Istnieje drugi koszt, który łatwo przeoczyć, a o którym wspomina ta sama dokumentacja. Jeden monolityczny, głęboki przebieg w ich teście „zużył około 58 milionów tokenów wejściowych z pamięci podręcznej”, ponieważ pojedynczy, stale rosnący kontekst zawierał wszystkie dane. Tokeny wejściowe z pamięci podręcznej są tańsze, ale przy takiej skali nadal znacząco obciążają rachunek.

Z powyższego wynikają cztery ustawienia:

• Wybierz najmniejszą głębokość, przy której liście stanowią rzeczywiste jednostki pracy, a następnie zatrzymaj się. Niepotrzebna głębokość to niepotrzebny wydatek.
• Pozostań w trybie Solo przy zadaniach trwających poniżej pół godziny, ponieważ koszt konfiguracji subagenta przewyższa zyski z nowego kontekstu.
• Zainstaluj hook Stop, jeśli korzystasz z Claude Code. Jest to jedyny element, który działa bezpłatnie.
• Ustaw twardy limit wydatków na poziomie konta przed rozpoczęciem jakichkolwiek długotrwałych zadań.

Ostatni punkt jest najważniejszy. Umiejętność zaprojektowana tak, aby odmawiać wczesnego zatrzymania, z założenia będzie pracować dalej. Budżetowanie i alerty to zadania oddzielne od promptowania, a kontrola kosztów agenta na VPS opisuje limity, które warto wdrożyć w pierwszej kolejności.

Co zmierzyli autorzy i co to dowodzi

Repozytorium publikuje własne testy, co zdarza się rzadziej, niż powinno. Ich konfiguracja, cytowana z pliku README: „dwa zadania budowania od zera (strona marketingowa i układ słoneczny w three.js), trzy warunki dla każdego (brak umiejętności, tree 3, tree 6), jeden świeży folder i świeża sesja na uruchomienie, ten sam model, ta sama treść promptu. Każdy wynik został poddany przeglądowi kodu przez niezależnych agentów, zweryfikowany w sposób kontradyktoryjny i przetestowany na żywo w przeglądarce”.

[
  {
    "label": "Self-found defects fixed, skill runs",
    "low_count": 4,
    "high_count": 10
  },
  {
    "label": "Wrong numbers in report, skill runs",
    "low_count": 1,
    "high_count": 3
  },
  {
    "label": "Wrong numbers in report, baseline runs",
    "low_count": 0,
    "high_count": 0
  }
]

Przeczytaj środkowy wiersz dwukrotnie. W teście przeprowadzonym przez autorów uruchomienia z użyciem umiejętności wykryły od 4 do 10 defektów, które agent znalazł samodzielnie przed dostarczeniem, a każde uruchomienie umiejętności wygenerowało raport końcowy zawierający od 1 do 3 błędnych liczb, w porównaniu do 0 w uruchomieniach bazowych. Większa ilość pracy zaowocowała lepszymi kompilacjami, ale gorszymi podsumowaniami. To wniosek stojący za zasadą rejestru oraz za instrukcją ponownego mierzenia każdej liczby w momencie tworzenia raportu lub oznaczania jej jako niezweryfikowaną.

Warto zapamiętać jeszcze jeden z ich wyników: „Jedyną poważną awarią na żywo była kompilacja bazowa, a jej raport twierdził, że przypadek został obsłużony”. Pewne siebie podsumowanie znajdujące się nad uszkodzoną kompilacją jest dokładnie tym, przed czym mają chronić bramki (gates).

Teraz ograniczenia. Sześć uruchomień, dwa zadania budowania, jeden model, uruchomione i zaraportowane przez samego autora umiejętności. Nie jest to niezależna replikacja, a my cytujemy to jako twierdzenia autorów na dzień 2026-08-10. Przetestuj to na własnej pracy: wykonaj to samo zadanie dwukrotnie, raz w sposób standardowy, a raz z użyciem pliku gates, a następnie policz bramki, które zamknęły się z dowodami, które możesz samodzielnie zweryfikować. Ta liczba jest jedyną w tym obszarze, która należy do Ciebie.

FAQ

Czym jest Depth Tree w umiejętności unlazy?

Jest to metoda dekompozycji. Zadanie dzieli się w naturalnych punktach styku na N warstw, a jedynie liście na samym dole są traktowane jako praca. Umiejętność definiuje liść jako dziesięć lub więcej minut skupionego wysiłku, zakończonego jednym spójnym produktem oraz plikiem gates. Jeśli liść można ukończyć w dwie minuty, oznacza to, że podział był o jedną warstwę zbyt głęboki. Każda warstwa powyżej liści służy dekompozycji i integracji, a każda gałąź posiada własne pliki gates, które potwierdzają scalenie elementów potomnych oraz zgodność interfejsów. Głębokość wybiera się podczas wywołania, na przykład tree 5, a udokumentowana wartość domyślna to najmniejsza głębokość, przy której liście stanowią rzeczywiste jednostki pracy.

Czy umiejętność unlazy działa poza Claude Code?

Częściowo. Umiejętność jest zwykłym plikiem markdown, więc Codex, Cursor oraz każde narzędzie odczytujące SKILL.md lub prompt systemowy może wykorzystać Depth Tree, plik gates, testy wykonywalne oraz cztery przejścia na liść. Twarde wymuszanie działa inaczej. Mechanizm Stop hook, który blokuje zakończenie tury, jeśli wymagania gates nie zostały spełnione, jest funkcją Claude Code, instalowaną za pomocą node <path-to-skill>/scripts/install-hooks.mjs. W innych środowiskach nic nie zapobiega strukturalnie przedwczesnemu zakończeniu tury przez model, więc to użytkownik musi odczytać plik gates i odesłać go z powrotem.

O ile umiejętność unlazy zwiększa zużycie tokenów?

Autorzy podają mnożnik od 1.6 do 3.9 w stosunku do liczby tokenów wyjściowych w trybie bez użycia umiejętności w pracy solo, plus kilkaset tokenów narzutu na sam plik gates. Schodzenie głębiej w ramach jednego kontekstu jest w porównaniu z tym niemal darmowe, około 1.0 do 1.5 przy przejściu z drzewa 3 na drzewo 6. Tryb orkiestrowany jest kosztowny, ponieważ każdy liść wymaga nowego kontekstu, który przed rozpoczęciem pracy ponownie odczytuje kontrakt oraz jego pliki gates. Mechanizm Stop hook nie generuje dodatkowych kosztów, ponieważ jedynie skanuje pliki. Są to dane autorów na dzień 2026-08-10, a nie pomiary, które powtarzaliśmy.

Czy powinienem użyć unlazy czy ponytail?

Dopasuj umiejętność do napotkanego problemu. ponytail jest przeznaczone dla agenta, który pisze zbyt wiele, ponieważ wciela się w rolę starszego programisty, który pyta, czy dany kod w ogóle musi istnieć i w pierwszej kolejności sięga po bibliotekę standardową. unlazy jest przeznaczone dla agenta, który kończy zbyt mało z powierzonych zadań, ponieważ wymusza dekompozycję i odmawia zamknięcia bramki bez dowodów. Jeśli potrzebujesz obu, najpierw ustal zakres za pomocą ponytail, a następnie przekaż ten zakres do unlazy, aby nie płacić mnożnika wysiłku za pracę, która powinna zostać usunięta.

Dlaczego mój agent nadal kończy pracę przedwcześnie po zainstalowaniu unlazy?

Sprawdź cztery kwestie. Po pierwsze, potwierdź obecność umiejętności na dysku za pomocą ls ~/.claude/skills/unlazy/SKILL.md, ponieważ sklonowanie do nieistniejącego katalogu jest częstym błędem. Po drugie, potwierdź, że plik gates został zapisany przed rozpoczęciem pracy, ponieważ mechanizm hook skanuje pliki gates, a brak GATES.md sprawia, że nie ma czego blokować. Po trzecie, sprawdź miejsce instalacji hooka: zwykłe uruchomienie install-hooks.mjs zapisuje konfigurację tylko dla bieżącego projektu settings.local.json, więc inny projekt wymaga --global. Po czwarte, pamiętaj, że zawór bezpieczeństwa działa zgodnie z projektem: sześć kolejnych zablokowanych prób zakończenia bez postępu w pliku gates pozwala agentowi kontynuować z ostrzeżeniem, a linia ABANDON: <gate> <reason> celowo kończy próbę.