Lekcja 25 · Faza 3 · Planowanie wieloetapowe

wizard: skrypty prowadzące człowieka, nie AI

Kolejny zwrot. Wszystko dotąd zakładało, że to Claude wykonuje pracę. /wizard odwraca role: Claude pisze skrypt bash, który potem, samodzielnie, prowadzi człowieka krok po kroku przez żmudną, ręczną procedurę — konfigurację usługi trzeciej, jednorazową migrację, przejście projektu ze stanu A do B.

Po co w ogóle skrypt, skoro jest Claude?

Sam skill nazywa problem wprost: procedura bywa żmudna do zrobienia ręcznie i żmudna do tłumaczenia AI za każdym razem od nowa. Wizard rozwiązuje to raz — otwiera każdy URL, mówi dokładnie co kliknąć i skopiować, zapisuje wartości tam, gdzie mają trafić (.env, sekrety GitHub Actions), potwierdza na każdym etapie i pokazuje, ile jeszcze zostało.

Biblioteka w template.sh — nie dotykaj ręcznie

UX jest już rozwiązany: pasek postępu z szacowanym czasem, bramki potwierdzenia, otwieranie URL działające cross-platformowo (włącznie z WSL), ukryte wpisywanie sekretów, idempotentne zapisy do .env, zapisy sekretów/zmiennych przez gh, i końcowe podsumowanie. Wszystko to leży nad znacznikiem STAGES w template.sh — ta część jest identyczna w każdym wizardzie i nigdy nie edytujesz jej ręcznie. Twoja jedyna praca to opisać procedurę i napisać jej etapy poniżej znacznika.

Przykład wprost z template.sh: konfiguracja Stripe

Wbudowany przykład w repo pokazuje wzorzec, który powtarzasz w każdym własnym etapie:

stage "Stripe — API keys" 5
say "We'll grab your Stripe test keys and store them for local dev + CI."
open_url "https://dashboard.stripe.com/test/apikeys"
step "On the API keys page, copy the Publishable key (starts pk_test_)."
ask STRIPE_PUBLISHABLE_KEY "Paste the publishable key:"
step "Click 'Reveal test key' on the Secret key row, then copy it."
ask_secret STRIPE_SECRET_KEY "Paste the secret key:"
write_env STRIPE_PUBLISHABLE_KEY "$STRIPE_PUBLISHABLE_KEY"
write_env STRIPE_SECRET_KEY "$STRIPE_SECRET_KEY"
set_secret STRIPE_SECRET_KEY "$STRIPE_SECRET_KEY"   # CI needs this one

Zauważ kolejność: open_url zawsze przed ask — człowiek najpierw widzi, gdzie znaleźć wartość, dopiero potem jest o nią proszony. Klucz publiczny idzie przez ask (widoczny), sekret przez ask_secret (ukryty). Do CI trafia tylko STRIPE_SECRET_KEY przez set_secret — klucz publiczny nie musi tam być, bo nie jest tajny.

Cztery kroki procesu

1. Zakres procedury — przeczytaj repo, zanim zapytasz na zimno: .env/.env.example, README, konfigurację frameworka, .github/workflows/* (każde odwołanie secrets.*/vars.* to wartość, którą wizard musi wyprodukować). Gotowe, gdy dla każdej przechwytywanej wartości wiadomo: skąd ją wziąć, gdzie ją zapisać, i czy jest tajna.
2. Ścieżka każdego etapu — dokładna trasa człowieka: który URL, co tam zrobić, gdzie pokazuje się wartość. Tam, gdzie nie znasz dokładnego UI albo komendy — powiedz to i zapytaj, nigdy nie zmyślaj kroków, które mogą nie istnieć.
3. Napisanie wizardu — kopiujesz template.sh, zamieniasz przykładowy etap na własne, jeden stage na krok, ustawiasz TOTAL_STAGES/TOTAL_MINUTES uczciwie.
4. Weryfikacja i przekazanie — bash -n, shellcheck jeśli dostępny, chmod +x. Nigdy nie uruchamiasz go end-to-end samodzielnie — otwiera przeglądarki i czeka na człowieka. Zamiast tego prześledź go statycznie: każda wartość z kroku 1 jest przechwycona i trafia tam, gdzie miała, a każdy set_secret pasuje dokładnie do nazwy z secrets.* w CI.

Efemeryczny domyślnie — ale inaczej niż prototype

Sprawdź się