shadcn/improve: audytuj najlepszym modelem, wykonuj tanim

shadcn/improve to Agent Skill na licencji MIT, który audytuje bazę kodu twoim najzdolniejszym modelem i zapisuje w plans/ samodzielne plany wdrożenia do wykonania przez tańszy model. Sam skill nigdy nie edytuje kodu źródłowego: każdy plan zawiera własne polecenia weryfikujące, granice zakresu i warunki STOP, więc wynik sprawdzasz, uruchamiając bramki, a nie czytając każdą linię.

Przejmujesz serwis albo twoje własne repozytorium od roku dryfuje i wiesz, że gdzieś są błędy, wolne zapytania i brakujące testy. Jeśli skierujesz na nie najmocniejszy model z poleceniem „popraw, co się da”, spalisz drogie tokeny na zmiany nazw i przestawianie importów, a na koniec dostaniesz rozległy diff do przejrzenia. Ta strona jest dla programistów i tech leadów, którzy chcą, żeby drogie myślenie odbyło się raz, zostało spisane jako plany wykonalne dla mniejszego modelu i sprawdzone poleceniami, a nie wzrokiem.

Co znajdziesz na tej stronie

Sprawdzoną instalację w Claude Code, Codeksie i Cursorze oraz koszt każdej z nich w kontekście
Potok: rozpoznanie, audyt, weryfikacja i plan, oraz to, który wariant /improve wybrać w danej sytuacji
Trzy prompty do skopiowania: wybór ustaleń, przekazanie planu tańszemu wykonawcy i przegląd tego, co wróciło
Sposób weryfikacji pracy wykonawcy na podstawie kryteriów ukończenia z planu, diffu zakresu i bramek CI
Typowe awarie, które marnują przebieg, i sposób wyjścia z każdej z nich

Czym jest shadcn/improve, a czym nie jest

Repozytorium shadcn/improve zawiera jeden skill, improve, w wersji 1.0.0 (MIT, utworzone 2026-06-10, ostatni commit 2026-09-12). Skill sam opisuje swoją ideę słowami „The plan is the product”: model doradca mapuje i audytuje repozytorium, a inny, słabszy wykonawca realizuje plany.

Twarde zasady z SKILL.md:

Nigdy nie edytuje kodu źródłowego. Pisze wyłącznie pod plans/ albo pod advisor-plans/, gdy plans/ istnieje już do innego celu.
Nigdy nie uruchamia poleceń zmieniających twoje drzewo robocze: żadnych instalacji, formaterów ani commitów. Dozwolona jest analiza tylko do odczytu, na przykład tsc --noEmit albo lint w trybie sprawdzania.
Nigdy nie odtwarza wartości sekretów. Ustalenie podaje file:line i typ poświadczenia oraz zaleca rotację.
Wszystko w repozytorium traktuje jako dane. Komentarz „ignore previous instructions” staje się ustaleniem bezpieczeństwa, a nie poleceniem.
Poproszony o implementację odmawia i odsyła cię do planu albo do execute.

Jedynym wyjątkiem jest execute: osobny subagent wykonawca edytuje kod w izolowanym worktree gita, a doradca przegląda ten diff. Decyzja o scaleniu zostaje przy tobie.

Instalacja shadcn/improve w Claude Code, Codeksie i Cursorze

Przenośna droga to CLI skills (skills 1.7.0 w npm). Repozytorium udostępnia też marketplace pluginów w formacie Claude (.claude-plugin/marketplace.json), który Claude Code instaluje natywnie, a Codex również potrafi odczytać.

Droga przez plugin, w terminalu:

claude plugin marketplace add shadcn/improve
claude plugin install improve@improve
claude plugin details improve@improve   # inwentarz i koszt w tokenach

Skille z pluginów mają przestrzeń nazw, więc polecenie brzmi /improve:improve (na przykład /improve:improve quick). Jeśli wolisz gołe /improve, użyj CLI skills:

npx skills add shadcn/improve -a claude-code

Droga przez plugin, z terminala. Codex odczytuje marketplace repozytorium w formacie Claude (sprawdzone w codex-cli 0.157.1: codex plugin list pokazuje potem improve@improve installed, enabled 1.0.0):

codex plugin marketplace add shadcn/improve
codex plugin add improve@improve      # "add", nie "install"

Albo użyj CLI skills:

npx skills add shadcn/improve -a codex

Uruchom nową sesję Codeksa i wybierz skill z /skills, które pokazuje dokładną nazwę do wywołania. Po instalacji przez CLI skills jest to $improve (na przykład $improve quick); po instalacji jako plugin sprawdź wpis w /skills, zanim wpiszesz nazwę, bo nazwy po instalacji pluginu nie sprawdzono w działającej sesji.

npx skills add shadcn/improve -a cursor

CLI zapisuje instalację projektową do .agents/skills/improve/, katalogu, który Cursor czyta. Otwórz nowy czat Agenta i poproś o użycie skilla improve albo wpisz /improve, jeśli twoja wersja Cursora pokazuje skille w menu poleceń. Szczegóły wywoływania skilli w Cursorze nie zostały ponownie sprawdzone 2026-09-26, bo cursor.com był nieosiągalny, więc zanim zaczniesz na tym polegać, upewnij się, że skill się pojawia.

Dodaj -g, żeby zainstalować skill dla swojego użytkownika zamiast projektu, i -y, żeby pominąć pytania w skryptach. Uruchom najpierw npx skills add shadcn/improve -l, jeśli chcesz zobaczyć zawartość repozytorium bez instalowania czegokolwiek. Zanim zainstalujesz jakikolwiek zewnętrzny skill, przeczytaj jego SKILL.md; bezpieczeństwo łańcucha dostaw skilli wyjaśnia dlaczego.

Jak przebiega uruchomienie /improve

Rozpoznanie. Doradca czyta README, CLAUDE.md lub AGENTS.md, konfigurację CI i manifesty oraz zapisuje dokładne polecenia build, test, lint i typecheck. Te polecenia stają się bramkami weryfikacji w każdym planie. Czyta też dokumenty intencji, jeśli istnieją (ADR-y w docs/adr/, PRD-y, CONTEXT.md, DESIGN.md, PRODUCT.md), żeby kompromis, o którym już zdecydowałeś, nie wrócił jako błąd.
Audyt. Równoległe subagenty tylko do odczytu obejmują dziewięć kategorii: poprawność, bezpieczeństwo, wydajność, pokrycie testami, dług techniczny i architekturę, zależności i migracje, DX i narzędzia, dokumentację oraz kierunek rozwoju. Każde ustalenie wymaga dowodu file:line, wpływu, nakładu (S/M/L), ryzyka poprawki i poziomu pewności.
Weryfikacja. Subagenty zgłaszają za dużo, więc doradca sam otwiera każde cytowane miejsce. Odrzuca zachowania celowe, poprawia błędne przypisania, scala duplikaty i zapisuje odrzucenia, żeby następny przebieg ich nie powtórzył.
Priorytety i wybór. Dostajesz tabelę uporządkowaną według dźwigni (wpływ podzielony przez nakład, ważony pewnością), a propozycje kierunku rozwoju osobno. Odpowiadasz, które ustalenia mają dostać plan. Skill czeka na ten wybór; uruchomiony bez interakcji planuje trzy do pięciu najlepszych i zapisuje to domyślne założenie.
Plan. Każde wybrane ustalenie staje się plikiem plans/NNN-slug.md, a plans/README.md zawiera kolejność, zależności i kolumnę statusu. Każdy plan zapisuje commit, na którym powstał.

Który wariant /improve uruchomić

Argument wybiera zakres i głębokość. Słowa kluczowe głębokości łączą się z pozostałymi, na przykład quick security albo deep --issues.

Chcesz…	Uruchom	Co robi
Tanio dostać pierwszą mapę dużego repozytorium	`/improve quick`	Tylko gorące punkty; poprawność, bezpieczeństwo i testy; około sześciu ustaleń o wysokiej pewności
Przeprowadzić zwykły audyt	`/improve`	Wszystkie dziewięć kategorii, do czterech równoległych subagentów
Zaudytować wszystko, łącznie ze słabymi tropami	`/improve deep`	Każdy pakiet, do ośmiu równoległych subagentów
Skupić się na jednej kategorii	`/improve security` (lub inna nazwa kategorii, np. `perf` albo `tests`)	Rozpoznanie, potem tylko ta kategoria
Zrobić autoprzegląd przed otwarciem PR-a	`/improve branch`	Pliki zmienione od merge-base plus ich bezpośredni wywołujący; każde ustalenie oznaczone `introduced` albo `pre-existing`
Zdecydować, co budować dalej	`/improve next`	Cztery do sześciu propozycji funkcji popartych dowodami, które stają się planami projektu lub spike’a
Zaspecyfikować jedną wybraną rzecz	`/improve plan <opis>`	Pomija audyt i pisze jeden plan
Docisnąć plan, zanim ktoś go uruchomi	`/improve review-plan <plik>`	Krytykuje plan względem szablonu; jeśli plan powstał w tej samej sesji, subagent ze świeżym kontekstem dodatkowo czyta go na zimno
Wykonać plan i przejrzeć wynik	`/improve execute <plan>`	Wysyła wykonawcę do worktree, ponownie uruchamia bramki i wydaje werdykt
Posprzątać po tygodniu pracy	`/improve reconcile`	Sprawdza plany DONE, przerabia BLOCKED, odświeża nieaktualne, wycofuje naprawione
Opublikować plany tam, gdzie śledzisz pracę	dodaj `--issues`	Tworzy przez `gh` jedno issue na GitHubie na każdy plan

W Claude Code z instalacją przez plugin poprzedzaj je /improve:improve; w Codeksie używaj nazwy pokazanej w /skills ($improve po instalacji przez CLI skills).

Dlaczego plany przetrwają słabszy model

Plan jest pisany dla „najsłabszego wiarygodnego wykonawcy”: modelu, który nie widział audytu i może być znacznie mniejszy. Szablon wymusza trzy właściwości:

Samodzielność. Ścieżki plików, fragmenty obecnego kodu z numerami linii, konwencje do naśladowania z plikiem wzorcowym oraz odpowiednie linie z CONTEXT.md lub ADR-ów, wszystko wstawione w treść.
Bramki weryfikacji. Każdy krok kończy się poleceniem i oczekiwanym wynikiem, a kryteria ukończenia da się sprawdzić maszynowo. Wykonawca nigdy nie musi oceniać, czy mu się udało.
Twarde granice. Listy plików w zakresie i poza nim oraz warunki STOP („jeśli X, zatrzymaj się i zgłoś”) zamiast improwizacji.

Każdy plan zaczyna się od sprawdzenia dryfu, git diff --stat <planned-at SHA>..HEAD -- <in-scope paths>, żeby plan napisany we wtorek nie został zastosowany na ślepo do kodu zmienionego w środę. To ta sama dyscyplina, dzięki której przebieg /goal kończy się czysto i którą spec-driven development stosuje do funkcji: spisana specyfikacja ze sprawdzalnymi kryteriami akceptacji.

Pętla audyt, plan, wykonanie i weryfikacja

Poniższa pętla osadza skill w cyklu plan, budowa, weryfikacja, przegląd i wdrożenie. Podział modeli wynika z zasady opisanej na stronie porównania modeli: doradca zostaje na domyślnym modelu narzędzia (Claude Opus 5.5 w Claude Code, domyślny od v2.1.280 w kanale latest; GPT-6 Astra w Codeksie), a wykonawca działa na tańszym (Claude Sonnet 5 lub Claude Haiku 4.5; GPT-6 Sol lub GPT-6 Luna). Przenieś zadanie z powrotem na mocniejszy model dopiero wtedy, gdy jego bramki uparcie nie przechodzą.

Plan. Uruchom /improve (albo /improve quick w dużym monorepo). Wybierz ustalenia pierwszym promptem poniżej. Tech lead przegląda plans/README.md i wybrane plany; jednostronicowy plan to znacznie mniejsza powierzchnia przeglądu niż diff, który z niego powstanie.
Budowa. Uruchom każdy plan na tańszym modelu w osobnym worktree. Polecenia różnią się w zależności od narzędzia:
Pozwól skillowi wysłać wykonawcę i przejrzeć wynik w jednym kroku. Wykonawca domyślnie działa na sonnet; inny model podaj po numerze planu.
/improve execute 001 /improve execute 003 haiku
Wysyłka używa subagenta general-purpose z izolacją w worktree. Doradca wstawia pełny tekst planu, bo niezacommitowany katalog plans/ nie istnieje w nowym worktree.
Krok wysyłki w skillu jest napisany pod subagenty Claude Code. Na hoście, który nie potrafi uruchomić subagenta w izolowanym worktree, skill to mówi i przekazuje ci plan. Uruchom wykonawcę sam z katalogu głównego repozytorium:
Okno terminala
git worktree add ../app-plan-001 -b plan-001 (cd ../app-plan-001 && npm ci) # albo polecenie instalacji twojego repozytorium codex exec -C ../app-plan-001 -m gpt-6-sol --approve-for-me \ "$(cat ../executor-preamble.txt plans/001-*.md)"
Nowy worktree dzieli historię gita, ale nie node_modules ani artefakty builda, więc najpierw zainstaluj zależności we własnej powłoce, poza sandboksem, gdzie sieć jest dostępna. Zapisz drugi prompt poniżej jako ../executor-preamble.txt, poza repozytorium, żeby nigdy nie trafił do commita. --approve-for-me kieruje prośby o zgodę do automatycznego przeglądu w sandboksie workspace-write (Codex CLI 0.157.1).
Utwórz worktree i zainstaluj jego zależności w terminalu, otwórz ten katalog w nowym oknie Cursora, wybierz tańszy model w selektorze modeli Agenta i wklej drugi prompt poniżej, a po nim pełny tekst planu. Wklejenie tekstu jest ważne: nowy worktree nie zawiera niezacommitowanych plików planów.
Okno terminala
git worktree add ../app-plan-001 -b plan-001 (cd ../app-plan-001 && npm ci) # albo polecenie instalacji twojego repozytorium
Weryfikacja. Uruchom w worktree ponownie każde kryterium ukończenia z planu, a potem zwykłe bramki (typecheck, lint, testy). W Claude Code execute robi to sam i zwraca APPROVE, REVISE (najwyżej dwie rundy) albo BLOCK. W pozostałych narzędziach wklej trzeci prompt poniżej do sesji na najmocniejszym modelu.
Przegląd. Sprawdź zakres przez git -C ../app-plan-001 diff --stat main...HEAD względem listy plików w zakresie z planu; każdy plik spoza niej oblewa przegląd. Zastąp main domyślną gałęzią swojego repozytorium. Samo git diff --stat po commicie wykonawcy nie pokazuje nic, więc przegląd przeszedłby bez patrzenia na zmianę. Czytaj asercje nowych testów, a nie tylko liczbę zaliczonych, bo wykonawca potrafi spełnić kryterium testem, który niczego nie sprawdza.
Wdrożenie. Otwórz PR z gałęzi worktree. CI uruchamia te same bramki, a osoba, która scala, bierze za to odpowiedzialność. Dołącz plan i wynik bramek jako pakiet dowodów PR-a.
Uzgodnienie. Na początku następnej sesji uruchom /improve reconcile, żeby backlog pokazywał, co weszło, co się zdezaktualizowało i co zostało naprawione przy okazji.

Plan 1, 3 and 5. Order them so any characterization tests land before the
refactor they protect, and say which plan depends on which. For each plan,
use this repo's own typecheck, lint and test commands as the done criteria,
list the files that are out of scope, and add a STOP condition for the case
where the current code no longer matches your excerpt. Skip anything whose
confidence is below HIGH and tell me what you dropped.

You are the executor for the implementation plan below. Run the plan's drift
check first. Then follow the plan step by step, run every verification command,
and confirm the expected result before moving to the next step. Touch only the
files listed as in scope. If any STOP condition occurs, stop and report instead
of working around it. Do not edit plans/README.md. Commit your work on this
branch. Finish with: STATUS (COMPLETE or STOPPED), each step with its
verification result, FILES CHANGED, and NOTES on any deviation. Report only what
a command in this session actually showed.

Review the branch plan-001 in ../app-plan-001 against plans/001-*.md as a tech
lead would, without editing any file. 1) Re-run every done criterion in the
plan and show the output. 2) Compare `git diff --stat main...plan-001` (use the
repo's default branch in place of main) with the plan's in-scope list and
flag every file outside it. 3) Read each new or changed
test and say what behaviour it would catch if it failed. 4) Check the diff
against "Why this matters" in the plan. End with APPROVE, REVISE (with specific
fixes), or BLOCK (with what the plan got wrong).

Kiedy shadcn/improve pasuje, a kiedy nie

Sięgnij po niego, gdy przejmujesz nieznaną bazę kodu i chcesz sprawdzonej, uporządkowanej mapy, zanim czegokolwiek dotkniesz; gdy chcesz, żeby budżet na najmocniejszy model szedł na ocenę i decyzje, a edycje robiły tańsze modele; przed PR-em, przez /improve branch; oraz gdy potrzebujesz opcji popartych dowodami z kodu, co budować dalej, przez /improve next.

Pomiń go przy jednym znanym błędzie (poproś agenta wprost albo użyj /improve plan <opis>), w repozytoriach bez działającego buildu i testów, dopóki tego nie naprawisz (skill zwykle i tak czyni „ustanowienie bazowej weryfikacji” ustaleniem numer jeden), oraz gdy zadaniem jest przegląd diffu, a nie audyt repozytorium; to obejmują skille do code review.

Awarie shadcn/improve i jak z nich wyjść

Wykonawca nie widzi planu. Nowy worktree zawiera tylko zacommitowane pliki, więc brakuje w nim niezacommitowanego katalogu plans/. Wyjście: wstaw tekst planu do promptu wykonawcy (tak robi execute i polecenie Codeksa powyżej) albo najpierw zacommituj plans/.

Plany trafiły do advisor-plans/. Twoje repozytorium miało już niezwiązany katalog plans/. Wyjście: nic się nie zepsuło; wskaż wykonawcy advisor-plans/ albo zmień nazwę swojego katalogu przed następnym przebiegiem.

Pierwsza bramka wykonawcy pada z powodu brakujących modułów. Nowy worktree nie ma node_modules ani wyników builda, a wykonawca w sandboksie może nie mieć sieci, żeby je zainstalować. Wyjście: zainstaluj zależności w worktree z własnej powłoki (npm ci albo polecenie instalacji twojego repozytorium), uruchom jeden build, jeśli twoje narzędzia czytają z dist/, i dopiero wtedy uruchom wykonawcę ponownie.

Plan jest nieaktualny. Ktoś zmienił pliki z zakresu po napisaniu planu i sprawdzenie dryfu pokazuje różnice. Wyjście: potraktuj to jako STOP, uruchom /improve reconcile, żeby odświeżyć fragmenty kodu i commit Planned at, a potem wykonaj plan ponownie.

Wykonawca ciągle się zatrzymuje albo oblewa tę samą bramkę. Plan jest niedospecyfikowany albo zadanie przerasta tańszy model. Wyjście: uruchom /improve review-plan plans/NNN-*.md, żeby go docisnąć; jeśli po dwóch rundach poprawek nadal nie przechodzi, uruchom ten plan na mocniejszym modelu albo go podziel.

Tabela ustaleń to szum. Zawiera zachowania celowe albo kompromisy rozstrzygnięte dawno temu. Wyjście: zapisz decyzję jako ADR w docs/adr/ albo w CONTEXT.md; rozpoznanie je czyta, a weryfikacja zapisuje odrzucone ustalenia, żeby nie wracały.

Audyt monorepo jest za drogi. Wyjście: zacznij od /improve quick albo pojedynczej kategorii (/improve security), a deep zostaw na sytuację, gdy potrzebujesz każdego pakietu; nawet wtedy skill przydziela subagenty do pakietów, a nie do korzenia. Raport końcowy mówi, czego nie zaudytowano, więc przeczytaj tę sekcję, zanim założysz pełne pokrycie.

Następne kroki

Instalowanie i zarządzanie skillami Jak CLI skills instaluje, aktualizuje i usuwa skille w Claude Code, Codeksie i Cursorze.

Grill Me i łańcuch skilli Pococka Krok uzgodnienia przed planem: agent przepytuje cię, aż specyfikacja jest ustalona.

Polecenie /goal Przekaż samodzielny plan autonomicznemu przebiegowi ze sprawdzalną metą.

Porównanie modeli AI dla agentów kodujących Który model wybrać na doradcę, a który na wykonawcę, z aktualnymi domyślnymi.