Zadania atomowe (Atomowa dekompozycja zadań)

1. Przegląd koncepcji i problem systemowy

W klasycznym rozwoju oprogramowania rozmyte zadania („Zaimplementuj autoryzację”, „Przepisz moduł wyszukiwania”) są główną przyczyną opóźnień w terminach oraz konieczności przerabiania kodu. W erze developmentu z udziałem agentów AI cena złej dekompozycji wzrosła wielokrotnie.

Gdy inżynier podaje agentowi wysokopoziomową, nieprecyzyjną instrukcję, ten dokonuje założonych interpretacji dziesiątek nieokreślonych szczegółów. W rezultacie generowany jest monolityczny diff obejmujący 40 plików, w którym mieszają się warstwa prezentacji (UI), schematy bazy danych oraz reguły biznesowe. Zweryfikowanie takiego diffa jest praktycznie niemożliwe: inżynier doświadcza przeciążenia poznawczego, klika „Accept”, a po tygodniu napotyka nierozwiązywalne konflikty.

Atomic Tasks (Zadania atomowe) to dyscyplina inżynieryjna strukturyzacji pracy według zasady niepodzielności:

• Każde podzadanie koncentruje się na jednej zmianie zachowania lub struktury.
• Posiada precyzyjnie określone parametry wejściowe oraz oczekiwane niezmienniki wyjściowe.
• Może być w pełni zaimplementowane, przetestowane i skomitowane niezależnie od reszty systemu.

Chaotyczny monolit (Porażka agenta):
[Wymaganie: „Zrób mi sklep internetowy”] ---> [LLM generuje bałagan w 30 plikach z placeholderami]

Atomowa dekompozycja (Kontrolowany sukces):
[Wymaganie: „Realizacja zamówienia”]
   |
   +---> Zadanie 1: Utworzenie schematu tabeli Order w Drizzle + migracja (Weryfikacja: db:push)
   |
   +---> Zadanie 2: Napisanie czystej funkcji calculateTotal(items, discount) (Weryfikacja: 5 testów jednostkowych)
   |
   +---> Zadanie 3: Implementacja endpointu POST /api/orders z walidacją Zod (Weryfikacja: curl / test API)
   |
   +---> Zadanie 4: Stworzenie interfejsu formularza realizacji zamówienia (Weryfikacja: komponent w przeglądarce)

2. Taksonomia architektoniczna i model mentalny

Skala granularności zadań (Task Granularity Spectrum):

1. Poziom makro (System Feature / Epic):
   • Cel biznesowy (np. „Obsługa wielojęzyczności serwisu”). Nie nadaje się do bezpośredniego przekazania agentowi jako pojedynczego polecenia.
2. Moduł atomowy (Feature Slice / Component):
   • Pionowy przekrój funkcjonalności (np. „Routing lokalizacji przez middleware”).
3. Działanie atomowe (Atomic Micro-Task):
   • Konkretny krok modyfikacji jednej warstwy: „Utwórz słownik tłumaczeń dla strony 404 w formacie JSON i dodaj ścisłe typowanie kluczy”.
   • Czas wykonania: 2–5 minut.
   • Liczba zmienionych linii: do 50–100 linii.

3. Pipeline techniczny i mechanika wewnętrzna

Szablon inżynieryjnego zadania atomowego (TASK_SPEC.md)

### Zadanie: Utworzenie repozytorium do przechowywania tokenów sesji

**Kontekst plików:**
- Plik docelowy: `src/lib/auth/session-store.ts`
- Plik testowy: `src/lib/auth/__tests__/session-store.test.ts`
- Kontrakt referencyjny: `src/lib/auth/types.ts`

**Wymagania:**
1. Zaimplementuj klasę `RedisSessionStore`, która implementuje interfejs `SessionStore`.
2. Metoda `saveSession(token, data, ttlSeconds)` powinna ustawiać klucz z TTL przy użyciu polecenia Redis `SETEX`.
3. Metoda `getSession(token)` powinna zwracać zdeserializowany obiekt lub `null`, jeśli klucz nie istnieje.

**Kryterium zakończenia (Definition of Done):**
- Polecenie `npx vitest run src/lib/auth/__tests__/session-store.test.ts` zwraca 100% pomyślnych testów.
- Brak błędów typowania: `npx tsc --noEmit` kończy się z 0 błędami.

Pipeline wykonania kroku atomowego:

1. Inżynier formułuje TASK_SPEC z jasnym kontekstem i testem.
2. Agent czyta WYŁĄCZNIE wskazane 2-3 pliki (czyste okno kontekstu, zero halucynacji).
3. Agent pisze implementację.
4. Uruchomienie automatycznego testu -> zielone światło.
5. Inżynier sprawdza kompaktowy diff (20 linii) w 15 sekund.
6. Git commit: `git commit -m "feat(auth): implement redis session store"`

4. Praktyczne scenariusze inżynieryjne w środowisku produkcyjnym

01. Bezpieczna migracja bazy danych liczącej 10 milionów rekordów

Zamiast przeprowadzać jedną złożoną migrację, zespół dzieli zadanie na 4 atomowe taski: 1) Dodanie nowej kolumny jako nullable; 2) Napisanie skryptu tła synchronizującego dane partiami po 1000 rekordów; 3) Przełączenie zapisu na nową kolumnę; 4) Dodanie ograniczenia NOT NULL i usunięcie starego pola. Każdy etap jest weryfikowany i deployowany osobno, co eliminuje ryzyko blokady tabeli.

02. Wyjście ze stanu impasu twórczego podczas debugowania

Inżynier nie rozumie, dlaczego złożony algorytm wyznaczania trasy zwraca błędny wynik. Zamiast bezowocnego analizowania całego pliku o długości 1000 linii, rozbija algorytm na 5 czystych podfunkcji i pisze dla każdej osobny test. Na poziomie 3. podfunkcji wykrywany jest błąd zaokrągleń ułamków, a bug zostaje usunięty w ciągu 3 minut.

03. Równoległe sterowanie subagentami (Parallel Subagents)

Dzięki atomowości architekt może uruchomić 3 różne sesje modelu jednocześnie: jeden agent pisze parser XML, drugi – generator raportów PDF, trzeci – schemat bazy danych. Ponieważ ich kontrakty są atomowe i nie nakładają się na wspólne pliki, całkowicie unikamy konfliktów scalania (Merge Conflicts).

5. Pułapki, typowe błędy i bezpieczeństwo

1. Paraliż fragmentacji (Micro-Task Hell): Nadmierna dekompozycja zadania na 50 drobnych kroków po 30 sekund każdy tworzy biurokratyczne tarcie: czas na sformułowanie promptu i oczekiwanie na odpowiedź zaczyna przewyższać czas pisania kodu. Zachowuj zdrowe proporcje: 1 zadanie atomowe powinno zawierać istotny krok rozwiązywania problemu.
2. Utrata globalnego niezmiennika (Local Optimum Trap): Każde zadanie atomowe może zostać wykonane idealnie na swoim poziomie, ale w kompleksie moduły mogą nie pasować do siebie, jeśli wcześniej nie ustalono wspólnego kontraktu interfejsowego (Contract-First Design).
3. Nagromadzenie nieskomentowanego bałaganu: Jeśli po wykonaniu każdego zadania atomowego nie zostanie wykonany git commit, po 5 iteracjach drzewo robocze zamienia się w chaos setek niezrozumiałych zmian, a korzyści płynące z atomowości zostają całkowicie utracone.