AI-Driven Development Workflow

Wstęp

AI-Driven Development to podejście do wytwarzania oprogramowania, w którym duża część pracy programistycznej — od projektowania, przez implementację, po dokumentację — jest delegowana do agentów AI, a rola człowieka koncentruje się na architekturze, definiowaniu wymagań i weryfikacji wyników. W poprzednich artykułach pokazałem, jak działa to w trybie GitHub Copilot w VS Code — tym razem chcę pójść krok dalej.

AI-Driven Development Workflow to dla mnie powtarzalny proces, w którym agenci AI nie są tylko narzędziem do pojedynczych zadań, lecz pełnią rolę wyspecjalizowanych członków zespołu. Każdy z nich odpowiada za konkretny etap cyklu życia projektu: planowanie zadań, ich realizację, aktualizację specyfikacji, dokumentację, commit message-e. Ja pełnię rolę architekta i recenzenta, agenci wykonują pracę zgodnie z wytycznymi.

Ten artykuł jest raportem z budowy takiego workflow przy okazji realnego projektu, w którym moim agentem był Claude Code od Anthropic.

Po co kolejna aplikacja do pomiarów?

Od dłuższego czasu szukałem aplikacji do regularnej rejestracji ciśnienia tętniczego, pulsu i wagi. Na rynku jest tego sporo, ale każda z aplikacji, na które trafiłem, miała przynajmniej jedną z trzech wad:

• natrętne reklamy albo model freemium, w którym kluczowe funkcje są płatne,
• nadmiar funkcji niepotrzebnych mi do mojego celu,
• brak konkretnej funkcji, na której mi zależało (np. odczyt wartości ze zdjęcia ekranu ciśnieniomierza).

Stwierdziłem, że to dobra okazja, żeby napisać własną aplikację — niedużą, dostosowaną do moich potrzeb — i jednocześnie przetestować pełny AI-Driven Development Workflow na realnym, niekomercyjnym projekcie.

SPEC.md zamiast openspec

Początkowo planowałem oprzeć cały proces o openspec — narzędzie, które wymusza rygorystyczne podejście do specyfikacji oraz zarządzania zmianami w projekcie. Bardzo szybko stwierdziłem jednak, że dla małej, prywatnej aplikacji jest to przerost formy nad treścią — sporo plików, sporo konwencji, sporo pracy administracyjnej, a ja chciałem skupić się na samym kodzie.

Decyzja była prosta: w pustym folderze tworzę pojedynczy plik SPEC.md, w którym będę utrzymywał specyfikację projektu. Piszę ją „na kolanie”, bez idealnego formatowania, bez kompletu szczegółów — bardziej jak notatkę z głośnego myślenia. Resztę roboty zlecam Claude Chat (jeszcze nie Claude Code, czyli wersji webowej claude.ai):

Przed uruchomienie /init chciałbym mieć dobrej jakości plik SPEC.md projektu. Mam taki napisany "na kolanie" i chciałbym, żebyś przekształcił go po względem formy i treści na bardzo profesjonalny. Jeśli potrzebujesz dodatkowych informacji, które powinny się znaleźć w SPEC.md, zadawaj pytania.

i wklejam mój wstępny SPEC.md:

Aplikacja web do rejestrowania wyników pomiaru ciśnienia tętniczego krwi, pulsu oraz wagi zalogowanego użytkownika.

Stack technologiczny:

- **SQLite** jako baza danych.
- **Prisma ORM** jako warstwa abstrakcji pomiędzy bazą danych, a _REST API backend_, narzędzie do definiowania schematów tabel oraz zarządzania migracjami w bazie danych.
- **Nuxt** serwer jako _REST API backend_.
- **Nuxt** + **Nuxt UI** (wspomagany przez **Tailwind CSS**) jako frontend użytkownika (SSR: false).
- Moduł **nuxt-auth-utils** wspomagający realizację autentykacji i autoryzacji użytkowników.
- Biblioteka **zod** do walidacji danych na formularzach frontend oraz dannych przekazywanych do endpoint-ów REST API.
- Biblioteki **unovis** do prezentacji danych w formie wykresów i grafów.

Wzorce projektowe:

- **Język interfejsu i komunikatów**: polski
- **Walidacja request body** — Zod schema w endpoincie API (`safeParse`)
- **Komunikaty błędów** — `useAppMessages()` store → `AppMessages.vue` → `useToast()`
- **Endpoint-y chronione** — `requireUserSession(event)`
- **Store pattern** — Pinia setup stores (`defineStore` z composition API)
- **Okna dialogowe (Modal/Slideover)** — sterowane przez `useOverlay` (nie `v-model:open`). Dialogi potwierdzenia przez composable `useConfirmDialog` oparty na `useOverlay`
- **If bez klamer**: jeśli po `if` występuje tylko jedno polecenie, nie używaj nawiasów `{ }` (np. `if (!x) return`)
- **Handler-y API (server/api/)**: minimum kodu — tylko kontrola autentykacji/autoryzacji (`requireUserSession`, `checkUserHasAnyRole`) i walidacja wejścia (Zod). Cała logika biznesowa i dostęp do bazy danych należą do serwisów w `server/services/`

Interfejs użytkownika:

- Prosty, w układzie pionowym dla urządzeń mobilnych.
- Wspólnych layout dla wszystkich ekranów: top nav bar z guzikiem powrotu na stronę domową, nazwa aplikacji CPW oraz hamburger menu (Mój profil, Wyloguj) oraz główna przestrzeń aplikacji.
- Strona domowa to 3 duże guziki: Ciśnienie / puls, Waga, Statystyki.
- Strony dodatkowe:
  - logowania uzytkownika
  - mój profil, na której można zmienić sobie hasło.

Planowanie funkcjonalności:

- Rejestrowanie wagi - po wybraniu Waga z ekranu głównego -> strona z formularzem:
  - Pole na wagę
  - Pole na date wykonania pomiaru, domyślnie _now_ z możliwością ręcznego ustawienia daty i czasu
- Rejestrowanie ciśnienie i pulsu - po wybraniu Ciśnienie / puls z ekranu głównego -> strona z formularzem:
  - Pole na ciśnienie skurczowe
  - Pole na ciśnienie rozkurczowe
  - Pole na puls
  - Pole na date wykonania pomiaru, domyślnie _now_ z możliwością ręcznego ustawienia daty i czasu
  - Możliwość przekazania wartości dla pierwszych trzech pól poprzez flow:
    - aktywacja aparatu fotograficznego z podglądem co widzi obiektyw
    - użytkownik robi zdjęcia ekranu ciśnieniomierza, na którym widać wartości zmierzone
    - zdjęcie przekazane na serwer, który następnie wysyła je do analizy AI, np. z pośrednictwem OpenRouter
    - AI zwraca w formacie JSON 3 wyłuskane ze zdjęcia wartości
- Statystyki - po wybraniu Statystyki ekranu głównego -> strona z formularzem:
  - Formularz ustalania zakresu analizowanych danych: 7 dni, 2 tygodnie, miesiąc, kwartał, rok.
  - Wykresy:
    - Ciśnienie - dwie linie: skurczowe i rozkurczowe
    - Puls
    - Waga

Autentykacja:

- Oprócz strony /login i endpoint /api/login, wszystkie pozostały strony i endpoint-y wymagają aktywnej sesji zalogowanego użytkownika. Jej brak kieruje na stronę /login.
- Aplikacja nie daje możliwości rejestracji nowego użytkownika. Administrator systemu ma do dyspozycji specjalnych skrypt _typescript_, którym może dodać nowego do aplikacji.

Autoryzacja:

- Użytkownik ma dostęp tylko i wyłączenie do pomiarów zarejestrowanych przez siebie.

Chat zadał mi 11 pytań doprecyzowujących (m.in. o politykę haseł, format dat, jednostki, obsługę stref czasowych, sposób przechowywania zdjęć), a następnie przygotował naprawdę porządną specyfikację — uporządkowaną logicznie, z rozdziałami, jednolitym formatowaniem i kompletem informacji, na których mógł oprzeć się dalszy proces.

Claude Code, /init i CLAUDE.md

Mając gotowy plik SPEC.md, do gry wchodzi Claude Code — wersja agenta uruchamiana lokalnie z konsoli, w katalogu projektu. Pierwsze polecenie to wbudowany /init, który analizuje zawartość katalogu (a w moim przypadku — istniejący już SPEC.md) i generuje plik CLAUDE.md z instrukcjami dla samego siebie.

CLAUDE.md jest tym, co odróżnia Claude Code od „zwykłego” asystenta — plik ten automatycznie ląduje w kontekście każdej sesji w tym katalogu. To jest projektowa pamięć agenta: wzorce, konwencje, polecenia npm, struktura folderów, ograniczenia. Każde nowe uruchomienie zaczyna się od tej samej, spójnej wiedzy o projekcie.

SKILL-e Claude Code

Drugim mechanizmem, który zdecydował o całym workflow, są SKILL-e Claude Code — wyspecjalizowane „role” agenta, każda z własnym opisem, parametrami i instrukcjami postępowania. Tworzy się je jako pliki w katalogu .claude/skills/<nazwa-skilla>/SKILL.md i wywołuje z poziomu CLI poprzez polecenia /<nazwa-skilla>.

Samodzielne pisanie dobrych SKILL-i jest trudne — wymaga znajomości konwencji i sporej dyscypliny. Sztuka jest jednak prostsza, niż się wydaje: opisuję agentowi co chcę osiągnąć i to on przygotowuje mi gotowego SKILL-a. Każdy kolejny w tym artykule powstał właśnie w ten sposób.

SKILL #1: planista zadań — update-tasks-list

Pierwsza decyzja dotycząca workflow: potrzebuję wyspecjalizowanego planisty, który na podstawie specyfikacji rozpisze listę zadań do realizacji. Proszę agenta o przygotowanie pierwszego SKILL-a:

Przygotuj SKILL-a o nazwie **update-tasks-list**, który przejrzy specyfikację w `./SPEC.md` i `./CLAUDE.md` i w pliku `./TASKS.md` dopisze zadania, które nie były jeszcze realizowane (wynikają z nowo dodanej specyfikacji).
Lista zadań to tabela MD z kolumnami:

- Numer zadania w formacie NNNN, np. 0001, 0204, w formie linku do pliku `NNNN.md`
- Status - wartości Planowane, Zrealizowane
- Tytuł - ogólny, skrócony opis zadania

SKILL musi logicznie układać zadania, czyli zawsze na początku musi być praca w bazie danych, modelach danych, potem REST API, a na końcu frontend.
Jedno zadanie może być przekrojowe przez warstwy aplikacji i raczej nie rozbijamy się na bardzo małe zadania, tylko zadania realizujące konkretne funkcjonalności aplikacji, np: zarządzanie użytkownikami, które będzie realizowało utworzenie tabeli, modeli danych, DTOs, endpoint-ów.
Logiczny plan realizacji każdego zadania musi znaleźć się osobnym pliku o nazwie `NNNN.md` w folderze `./_TASKS/`.
Jeśli SKILL pierwszy raz uruchomiony, musi utworzyć plik `./TASKS.md` oraz folder `./_TASKS/` z wszystkimi zadaniami, które wymagają realizacji w ramach specyfikacji.
Przy kolejnych uruchomieniach, dodaje nowe zadania, które wynikają z dodanej specyfikacji.

Agent przygotował kompletny plik SKILL-a wraz z opisem, parametrami i procedurą.

Pierwsze uruchomienie planisty

Wywołuję /update-tasks-list i otrzymuję plik TASKS.md z listą zadań ułożonych logicznie od bazy danych, przez API, po frontend:

# Zadania projektu CPW

| Nr                       | Status       | Tytuł                                               |
| ------------------------ | ------------ | --------------------------------------------------- |
| [0001](./_TASKS/0001.md) | Zrealizowane | Inicjalizacja projektu i konfiguracja               |
| [0002](./_TASKS/0002.md) | Zrealizowane | Model danych i migracje bazy danych                 |
| [0003](./_TASKS/0003.md) | Zrealizowane | Skrypt CLI dodawania użytkowników                   |
| [0004](./_TASKS/0004.md) | Zrealizowane | Autentykacja i autoryzacja                          |
| [0005](./_TASKS/0005.md) | Zrealizowane | Wspólny layout, nawigacja i infrastruktura frontend |
| [0006](./_TASKS/0006.md) | Zrealizowane | Pomiary ciśnienia i pulsu                           |
| [0007](./_TASKS/0007.md) | Zrealizowane | Pomiary wagi                                        |
| [0008](./_TASKS/0008.md) | Zrealizowane | Statystyki i wykresy                                |
| [0009](./_TASKS/0009.md) | Zrealizowane | Profil użytkownika — zmiana hasła                   |
| [0010](./_TASKS/0010.md) | Zrealizowane | Analiza zdjęcia ciśnieniomierza przez AI            |

Równocześnie powstał folder _TASKS/ z dziesięcioma plikami NNNN.md, w których agent rozpisał szczegółowe kroki realizacji każdego z zadań — od migracji Prisma, przez DTO, po komponenty Vue.

SKILL #2: wykonawca — do-task

Mogłem teraz puścić agenta luzem i poprosić go o realizację wszystkich zadań naraz. Wolę jednak inne podejście: zadanie po zadaniu, weryfikacja przez git diff, świadomy git commit, dopiero potem kolejne. Po pierwsze — zachowuję kontrolę nad jakością. Po drugie — historia commit-ów ma sens i da się ją po latach czytać.

Zlecam agentowi przygotowanie kolejnego SKILL-a:

Przygotuj SKILL-a o nazwie **do-task**, który zrealizuje zadania o podany numerze. Numer podajemy jako parametr wywołania SKILL-a. Po zakończeniu realizacji zadania zmiana status zadania w pliku `./TASKS.md`.

Uruchamiam pierwsze prace poleceniem /do-task 1 i czekam, aż agent przygotuje strukturę projektu. Po kilku minutach mam zainicjowany projekt Nuxt ze skonfigurowanym TypeScript, ESLint, Prettier, Vitest. Po git diff i git commit przechodzę do /do-task 2 — modele bazy danych, schemat Prisma, pierwsza migracja. I tak dalej.

SKILL #3: korygujący — update-task

Po pierwszych implementacjach szybko okazało się, że niezależnie od jakości wyjściowej, zawsze coś trzeba poprawić — kosmetycznie, koncepcyjnie lub funkcjonalnie. Można poprawki zlecać agentowi w tej samej sesji (dopóki nie wyczyścimy kontekstu poleceniem /clear), ale wtedy ślad po decyzji znika — plik NNNN.md z opisem zadania pozostaje nieaktualny, a zmiany są tylko w kodzie i git log.

Potrzebny był osobny SKILL, który zaktualizuje plik zadania w folderze _TASKS/, a następnie od razu przeprowadzi zmianę w kodzie:

Przygotuj SKILL-a o nazwie **update-task**, który przyjmuje dwa parametry: nr zadania oraz nowe wymagania związane z zadaniem (nowa funkcja, rozbudowa, poprawka). SKILL aktualizuje plik `NNNN.md` w folderze `./_TASKS/` zgodnie z podanymi oczekiwaniami i od razu przystępuje do realizacji w kodzie, jeśli jest taka potrzeba.

Od tego momentu każda poprawka jest udokumentowana w pliku zadania — opis aktualnego stanu wymagania i opis zmiany żyją razem z kodem.

SKILL #4: aktualizacja specyfikacji — update-spec

Po realizacji pierwszych dziesięciu zadań, w trakcie codziennego korzystania z aplikacji, zaczęły pojawiać się pomysły na nowe funkcje i usprawnienia. Każdy taki pomysł powinien najpierw trafić do specyfikacji (czyli plików SPEC.md i ewentualnie CLAUDE.md), a dopiero potem wpływać na listę zadań. Robienie tego ręcznie mijałoby się z celem całego workflow — zlecam agentowi czwartego SKILL-a:

Przygotuj SKILL-a o nazwie **update-spec**, który przyjmuje jeden parametr - opis planowanej zmiany koncepcyjnej, nowej funkcjonalności, nowego procesu, który ma być obsługiwany przez aplikację. SKILL aktualizuje plik `./SPEC.md` i jeśli jest taka potrzeba pliki `./CLAUDE.md`.

Pętla rozwojowa

W tym momencie mam już komplet ról potrzebnych do utrzymania projektu i wpadam w wyraźnie powtarzalną pętlę:

• nowy pomysł / funkcja → aktualizacja specyfikacji: /update-spec
• nowe zadania wynikające ze specyfikacji → /update-tasks-list
• realizacja zadań → /do-task <nr>
• ewentualne poprawki → /update-task <nr> <opis zmiany>
• zatwierdzenie → git commit + git push

W ten sposób dołożyłem do projektu dodatkowych 13 zadań, które przeszły przez tę samą ścieżkę co pierwsza dziesiątka:

| Nr                       | Status       | Tytuł                                                 |
| ------------------------ | ------------ | ----------------------------------------------------- |
| [0011](./_TASKS/0011.md) | Zrealizowane | Ikony aplikacji i metadane web app                    |
| [0012](./_TASKS/0012.md) | Zrealizowane | Resetowanie stanu Pinia store'ów przy wylogowaniu     |
| [0013](./_TASKS/0013.md) | Zrealizowane | Konfigurowalna długość sesji (NUXT_SESSION_VALIDITY)  |
| [0014](./_TASKS/0014.md) | Zrealizowane | Refaktor walidacji wejścia API (DTOs + helper-y)      |
| [0015](./_TASKS/0015.md) | Zrealizowane | Warstwa bezpieczeństwa (nuxt-security)                |
| [0016](./_TASKS/0016.md) | Zrealizowane | Centralna funkcja apiCall dla wywołań API frontend-u  |
| [0017](./_TASKS/0017.md) | Zrealizowane | Globalny wskaźnik ładowania (appStatus + AppLoader)   |
| [0018](./_TASKS/0018.md) | Zrealizowane | Refaktor systemu komunikatów (appStatus + AppToaster) |
| [0019](./_TASKS/0019.md) | Zrealizowane | Testy integracyjne REST API                           |
| [0020](./_TASKS/0020.md) | Zrealizowane | Profil — data urodzenia i wzrost                      |
| [0021](./_TASKS/0021.md) | Zrealizowane | Statystyki — wskaźnik BMI w sekcji Waga               |
| [0022](./_TASKS/0022.md) | Zrealizowane | Konfiguracja SMTP i serwis wysyłki e-mail             |
| [0023](./_TASKS/0023.md) | Zrealizowane | Agent przypomnień e-mail                              |

Ciekawostka: część tych zadań (np. 0014–0018) to czysty refaktor pojawiający się w trakcie pracy z aplikacją — kiedy zauważam powtarzający się wzorzec albo widzę, że coś jest robione na trzy różne sposoby. Wcześniej takie rzeczy odkładałem na kiedyś. W tym workflow są równorzędnymi zadaniami, które przechodzą tę samą drogę co nowe funkcjonalności.

Skill pomocniczy: commit-staged

Pracując w tym tempie szybko okazuje się, że pisanie sensownych commit message-y po polsku też zajmuje wymierny czas, a jeszcze częściej pojawia się pokusa, żeby napisać byle co (update, fix, wip). Czas na kolejnego specjalistę:

Przygotuj SKILL-a o nazwie **commit-staged**, który przygotuje _commit message_ w języku polskim, dla plików, które są w statusie _staged_, wykona _commit_ z przygotowanym opisem. Na końcu ZAWSZE ma pytać, czy wykonać _git push_.

Od momentu powstania tego SKILL-a, jedyne polecenie zatwierdzające zmiany w repozytorium to /commit-staged. Komunikaty są spójne stylistycznie, krótkie, w jednym języku, a finalne pytanie o git push chroni mnie przed nawykowym wysyłaniem niedokończonych zmian na zdalne repo.

SKILL #5: dokumentacja API — update-api-doc

Kolejnym eksperymentem było sprawdzenie, czy agent jest w stanie samodzielnie utrzymywać dokumentację techniczną. Zlecam przygotowanie SKILL-a do dokumentacji REST API:

Przygotuj SKILL-a o nazwie **update-api-doc**, który utworzy (jeśli nie istnieje) lub zaktualizuje (np. po zmianach w **backend**) plik `./API.md`. Skill ma dbać o dobrej jakości dokumentację wszystkich punktów _REST API endpoints_, zawierającą URL, metodę HTTP, przyjmowane dane wejściowe (z podziałem na body, url params, query params), czy sprawdza autentykację/autoryzację użytkownika oraz biznesowy opis operacji, które wykonuje przy wywołaniu.

Uruchomienie /update-api-doc dało mi kompletny plik API.md ze wszystkimi endpoint-ami: URL, metoda HTTP, wymagana autentykacja, schemat wejścia, opis biznesowy. Od tego momentu wystarczy wywołać ten SKILL po wprowadzeniu zmian w warstwie API, żeby dokumentacja była zsynchronizowana z kodem.

SKILL #6: porządkowanie specyfikacji — cleanup-spec

Po kilkudziesięciu iteracjach przez /update-spec zaczęły pojawiać się ostrzeżenia w konsoli Claude Code: pliki SPEC.md i CLAUDE.md rozrosły się i zaczęły zajmować nieproporcjonalnie dużą część okna kontekstowego. Po krótkim audycie tych plików stało się jasne dlaczego:

• powielały się informacje między SPEC.md a CLAUDE.md,
• powielały się informacje z plikami zewnętrznymi (np. API.md),
• układ rozdziałów przestał być logiczny — np. „Usuwanie pomiarów” (funkcja użytkownika) wcisnęło się między „Skrypty administracyjne” a „Zmienne środowiskowe”.

Potrzebny był SKILL porządkujący:

Przygotuj SKILL-a o nazwie **cleanup-spec**, który porządkuje pliki `./SPEC.md` oraz `./CLAUDE.md`. Pliki szybko się rozrastają i agent rzuca ostrzeżeniami, że są zbyt duże, rozdmuchują kontekst. Nie ma sensu powielać tych samych informacji w obu plikach lub informacji, które są dostępne w plikach dodatkowych jak na przykład `./API.md`, który stanowi pełną dokumentację endpoint-ów REST API. Wystarczy przywołać plik zewnętrzny - wstawić link do pliku. Plik `./SPEC.md` powinien koncentrować się na danych zarządzanych w aplikacji oraz na stronie funkcjonalnej i biznesowej aplikacji, zawierać opisy funkcjonalności i realizowanych procesów biznesowych, czyli zawierać specyfikację z naciskiem na biznesową, a mniej techniczną. Zawartość powinna być lepiej uporządkowana, np. w tej chwili rozdział **Usuwanie pomiarów** (funkcja użytkownika), jest nielogicznie wciśnięty pomiędzy rozdziały **Skrypty administracyjne**, a **Zmienne środowiskowe**. Plik `./CLAUDE.md` powinien mieć zawartość zalecaną przez agenta _Claude Code_, ale wg mnie powinien koncentrować się na warstwie bardziej technicznej oraz stanowić pamięć projektu, czyli przechowywać wzorce projektowe, zalecenia architektoniczne. Nie powinien powielać informacji już dostępnych w pliku `./SPEC.md` oraz innych plikach projektu (jak `./API.md`), ale na pewno powinien na niego wskazywać z opisem co zawiera.

Uruchomienie /cleanup-spec zredukowało rozmiar obu plików o około 40%, uporządkowało strukturę rozdziałów i pozbyło się duplikatów. Ważniejsze niż statystyki — zmiana ról jest teraz jasna: SPEC.md mówi co robi aplikacja z perspektywy biznesowej, CLAUDE.md to projektowa pamięć agenta i warstwa techniczna, a pliki takie jak API.md są przywoływane linkami zamiast kopiowane.

SKILL #7: instrukcja użytkownika — update-user-guide

Dokumentacja deweloperska to jedno, ale instrukcja dla użytkownika końcowego to zwykle zupełnie inna jakościowo historia: musi być prosta, czytelna, ze zrzutami ekranów. W praktyce takiej instrukcji prawie nigdy nie ma — pisze się ją na końcu projektu i niespecjalnie chętnie. Aplikacja jest dla mnie, więc instrukcja nie jest konieczna, ale to ciekawy test dla całego workflow.

Przygotuj SKILL-a o nazwie **update-user-guide**, który utworzy (jeśli nie istnieje) lub zaktualizuje (np. po zmianach w **frontend**) plik `./GUIDE.md`. SKILL ma dbać o dobrej jakości instrukcję dla użytkownika końcowego, zawierającą opis wszystkich funkcjonalności wraz ze zrzutami ekranów. SKILL ma tworzyć i używać użytkownika testowego, wykonać _seed_ tabel bazy danych, żeby wypełnić testowymi danymi (strona statystyk musi coś pokazywać), a zrzuty ekranu wykonać za pomocą _Playwright_.

Wynik mile mnie zaskoczył. Agent samodzielnie:

• utworzył testowego użytkownika,
• wykonał seed tabel pomiarów (dziesiątki rekordów rozłożonych w czasie, żeby wykresy miały sens),
• uruchomił aplikację,
• przeszedł przez wszystkie ekrany za pomocą Playwright, robiąc zrzuty,
• napisał spójną instrukcję powiązaną tekstowo z odpowiednimi obrazkami.

Plik GUIDE.md spokojnie nadaje się do wyeksportowania jako PDF albo do podpięcia w samej aplikacji pod linkiem Instrukcja w menu głównym.

Generowanie README.md

Na samym końcu, kiedy aplikacja, API i instrukcja dla użytkownika były już gotowe, poprosiłem agenta o jeszcze jedną rzecz — główną stronę projektu na GitHubie:

Mając wiedzę na temat tego projektu, przygotuj prosty plik **README.md**, który będzie stanowił główną stronę projektu dla GitHub repo.

Tym razem nie tworzyłem SKILL-a — to była operacja jednorazowa. Agent przygotował kompletny README.md zawierający opis funkcji, stack technologiczny, instrukcję instalacji i uruchomienia, sposób zakładania kont użytkowników skryptem CLI oraz sekcję o aktualizacji zależności i bezpieczeństwie łańcucha dostaw (.ncurc.json, .npmrc).

Podsumowanie workflow

W finalnej formie cały mój AI-Driven Development Workflow dla projektu CPW sprowadza się do kilku ról i jednej pętli:

Role (SKILL-e):

• update-tasks-list — planista, czyta specyfikację, układa zadania od bazy danych po frontend.
• do-task <nr> — wykonawca, realizuje pojedyncze zadanie zgodnie z planem w _TASKS/NNNN.md.
• update-task <nr> <opis> — korygujący, aktualizuje opis zadania i wprowadza zmianę w kodzie.
• update-spec <opis> — analityk biznesowy, aktualizuje specyfikację o nowe wymagania.
• cleanup-spec — porządkowy, dba o higienę plików specyfikacji.
• update-api-doc — technical writer od API.
• update-user-guide — technical writer od instrukcji użytkownika (ze zrzutami z Playwright).
• commit-staged — sekretarz, opisuje i zatwierdza zmiany w repozytorium.

Pętla rozwojowa:

Główna:
  pomysł → /update-spec → /update-tasks-list → /do-task → (/update-task)* → /commit-staged

Pomocnicza:
  ↘ /update-api-doc, /update-user-guide (regularnie)
  ↘ /cleanup-spec (okresowo)

Moja rola w tej pętli to architektura, decyzje koncepcyjne, recenzja przez git diff i testy ręczne w przeglądarce. Agent wykonuje wszystko, co da się jednoznacznie opisać — a okazuje się, że da się opisać znacznie więcej, niż na pierwszy rzut oka się wydaje.

Wnioski

Trzy obserwacje, które wynoszę z tego projektu:

• Wyspecjalizowany agent bije agenta uniwersalnego. Te same modele i to samo narzędzie, ale rozdzielenie ról przez SKILL-e dało jakościowo lepsze wyniki niż próby zmuszania jednej sesji do robienia wszystkiego naraz. Każdy SKILL ma jasne kryteria sukcesu, jasne pliki, na których pracuje, i jasne ograniczenia.
• Specyfikacja musi być żywa. Workflow, w którym SPEC.md jest pisany raz na początku i nigdy nie odświeżany, rozjeżdża się z kodem w ciągu tygodni. /update-spec + /cleanup-spec to nie luksus, tylko warunek konieczny, żeby reszta procesu w ogóle miała sens po kilkudziesięciu iteracjach.
• Małe zadania, częste commit-y. Konwencja 1 zadanie = 1 funkcjonalność = 1 commit (z opcjonalnymi commit-ami od /update-task) daje czytelną historię i pozwala szybko cofać się do dowolnego stanu projektu. Bez tego nie da się recenzować pracy agenta na tej skali.

Aplikacja CPW jest niekomercyjna i pisana wyłącznie dla mnie, więc jako projekt produktowy jest mało ekscytująca. Jako ćwiczenie z workflow była bardzo wartościowa — w kilku wieczorach zbudowałem działającą aplikację z 23 zadaniami, pełną dokumentacją techniczną, dokumentacją REST API, instrukcją użytkownika ze zrzutami ekranów i wzorcami bezpieczeństwa łańcucha dostaw. Wszystko to z git log-iem, w którym każdy commit ma sens.

Materiały do pobrania / podglądu

Wszystkie SKILL-e opisane w tym artykule oraz pliki dokumentacji wygenerowane w projekcie CPW udostępniam do swobodnego użycia:

• Komplet SKILL-i Claude Code — publiczne repozytorium z wszystkimi 8 SKILL-ami jako zestawem plików SKILL.md w odpowiedniej strukturze katalogów.
• Przykładowy README.md — wygenerowany na końcu projektu.
• Przykładowy API.md — pełna dokumentacja REST API.
• Przykładowy GUIDE.md — instrukcja użytkownika końcowego ze zrzutami z Playwright.

Wystarczy skopiować SKILL-e do katalogu .claude/skills/ we własnym projekcie i można od razu zacząć pracę w tym samym workflow.