Od planu do działającego kodu

Masz plan. Może to jest formalna specyfikacja, którą napisałeś w ostatniej sesji. Może to są punkty w dokumencie Notion. Może to jest rozmowa z twoim tech leadem, która zakończyła się “brzmi dobrze, idź to zbudować.” Plan to łatwa część. Trudna część to zamienienie go w działający kod, który dotyka dwunastu plików, szanuje istniejące wzorce, przechodzi testy i nie psuje funkcji, które twoi koledzy wysłali w zeszłym tygodniu.

To jest miejsce, gdzie większość programistów albo traci godziny na przełączanie kontekstu, albo daje Claude’owi niejasny prompt i kończy z kodem, który ignoruje konwencje projektu. Ta lekcja opisuje przepływ pracy implementacji, który unika obu pułapek: najpierw zbadaj, zaplanuj konkretne zmiany, zaimplementuj w możliwych do przejrzenia kawałkach i commituj w każdym punkcie kontrolnym.

Co wynosisz z tej lekcji

• Cykl explore-plan-implement-commit, który utrzymuje wieloplikowe zmiany na właściwym torze
• Prompty, które produkują kod pasujący do istniejących wzorców twojego projektu
• Techniki łamania dużych implementacji na możliwe do przejrzenia commity
• Wzorzec checkpoint, który łapie błędy zanim się nawarstwiają

Cykl implementacji

Programiści, którzy najszybciej wysyłają z Claude Code, nie są tymi, którzy piszą “implement the feature” i akceptują wszystko. Podążają za ścisłą pętlą: badają obszar, który zaraz zmienią, planują konkretne edycje, implementują jeden logiczny kawałek, weryfikują, że działa i commitują przed przejściem dalej.

1. Zbadaj odpowiedni kod

   Nawet jeśli zaplanowałeś funkcję w poprzedniej sesji, zacznij od ugruntowania Claude’a w konkretnych plikach, które się zmienią. Kontekst z sesji planistycznej nie przenosi się perfekcyjnie — Claude musi zobaczyć faktyczny kod.

   Read these files and summarize the patterns I need to follow:
   - src/services/user.service.ts
   - src/routes/user.routes.ts
   - src/schemas/user.schema.ts
   - tests/services/user.service.test.ts
   
   I'm about to add an organization service that follows the same
   patterns. Tell me: naming conventions, error handling approach,
   how validation is structured, and how tests are organized.

2. Zaplanuj konkretne zmiany

   Zanim Claude dotknie jakichkolwiek plików, niech opisze dokładnie, co zrobi. To jest twój punkt kontrolny przeglądu.

   Wskazówka

   Prompt do skopiowania dla planowania implementacji:

   I need to implement organization management. Based on the patterns
   you just analyzed, list every file you'll create or modify, and
   for each one, describe the change in one sentence. Do not start
   implementing yet -- just show me the plan.

   Przejrzyj plan. Jeśli Claude chce utworzyć plik w złym katalogu, wprowadzić nowy wzorzec lub pominąć testy, złap to teraz. Korekty na tym etapie nic nie kosztują.

3. Zaimplementuj jeden logiczny kawałek

   Nie proś Claude’a o zaimplementowanie całej funkcji na raz. Podziel to na kawałki, które mają sens jako indywidualne commity.

   Start with the data layer: create the organization schema,
   the database migration, and the service with CRUD operations.
   Follow the exact patterns from user.service.ts. Include tests.
   
   Do not touch routes or middleware yet -- we'll do that next.

4. Zweryfikuj przed commitowaniem

   Po każdym kawałku, niech Claude uruchomi testy i sprawdzi problemy.

   Run the tests for the organization service. Also run the existing
   user service tests to make sure nothing is broken. Show me the
   test output.

5. Commituj punkt kontrolny

   All tests pass. Commit with a message describing what was added.
   Keep the message under 72 characters for the subject line.

6. Powtórz dla następnego kawałka

   Przejdź do routów, potem middleware, potem integracji frontendu. Każdy kawałek dostaje swój własny cykl weryfikuj-i-commituj.

Dopasowanie do istniejących wzorców

Najczęstszy błąd w implementacji wspomaganej AI to wygenerowany kod, który działa, ale nie wygląda jak reszta bazy kodu. Rozwiązaniem jest wyraźne dopasowanie wzorców.

Wskazówka

Prompt do skopiowania dla implementacji dopasowanej do wzorców:

Implement the organization API routes. Before writing any code,
read src/routes/user.routes.ts and src/routes/project.routes.ts.

Your implementation MUST follow these exact patterns:
- Same middleware chain order
- Same error response format
- Same validation approach (Zod schemas with .parse())
- Same naming convention for route handlers
- Same test structure as tests/routes/user.routes.test.ts

If you're unsure about a pattern, read more files to verify
rather than guessing. I'd rather the code be correct than fast.

Kiedy Claude podąża za istniejącymi wzorcami, twoje przeglądy kodu stają się szybsze, ponieważ recenzenci patrzą na znajome struktury. Diff opowiada historię tego, co się zmieniło, nie tego, jak preferowany styl Claude’a różni się od twojego.

Obsługa zmian w wielu plikach

Duże funkcje nieuchronnie dotykają wielu plików. Kluczem jest uporządkowanie zmian tak, aby każdy krok budował na solidnym gruncie.

Kolejność zależności

Implementuj w tej kolejności, aby zminimalizować uszkodzenia:

1. Typy i interfejsy — Najpierw zdefiniuj kształty danych
2. Warstwa bazy danych — Migracje, schemat, zapytania
3. Logika serwisowa/biznesowa — Podstawowe operacje zależne od bazy danych
4. Routy API — Cienka warstwa, która wywołuje serwisy
5. Komponenty frontendowe — Konsumują API
6. Testy na każdej warstwie — Pisane razem z kodem, nie po

We're implementing multi-tenant support. Let's work through it
in dependency order. Start with the types:

1. Create src/types/tenant.ts with the Tenant interface
2. Add tenant_id to the User interface in src/types/user.ts
3. Create the Zod schemas for tenant validation

Show me each file. Don't proceed to the database layer until
I confirm these are correct.

Używanie sub-agentów do równoległej implementacji

Kiedy części funkcji są niezależne, deleguj je do sub-agentów, aby utrzymać pracę w ruchu.

Use sub-agents to implement these in parallel:

1. Create the tenant database migration and Drizzle schema
2. Create the tenant service with CRUD operations
3. Create the tenant API route handler

Each sub-agent should read the existing user.* files first
to match our patterns. Report the results so I can review
before we integrate them.

Sub-agenci są szczególnie użyteczni do generowania testów obok kodu implementacji. Podczas gdy jeden sub-agent pisze serwis, inny może pisać plik testowy oparty na tych samych wzorcach.

Wzorzec checkpoint

Każda sesja implementacji powinna produkować commity, które opowiadają spójną historię. Jeśli coś zepsuje się później, możesz przeszukać commity, aby znaleźć dokładnie, kiedy bug został wprowadzony.

After implementing each layer, create a commit:

1. "Add tenant types and validation schemas"
2. "Add tenant database migration and Drizzle schema"
3. "Add tenant service with CRUD operations and tests"
4. "Add tenant API routes with auth middleware"
5. "Add tenant switcher component to dashboard"

Each commit should pass all tests independently. If a commit
would leave tests failing, the chunk is too big -- break it
down further.

Uwaga

Nie pozwól Claude’owi stworzyć jednego masywnego commita ze wszystkimi zmianami. Jeśli coś pójdzie nie tak, nie możesz przywrócić tylko problematycznej części. Co gorsza, recenzenci kodu przejrzą diff 500 linii i przegapią buga ukrytego w linii 347.

Uruchamianie testów na bieżąco

Claude Code może uruchomić twój zestaw testów po każdej zmianie. To nie jest opcjonalne — to siatka bezpieczeństwa, która pozwala ci szybko się poruszać bez psucia rzeczy.

After every file you create or modify, run:
1. The specific test file for the module you changed
2. The full test suite to check for regressions

If a test fails, fix it before moving to the next file.
Do not accumulate broken tests and fix them later.

Dla projektów z wolnymi zestawami testów, ogranicz uruchomienia testów:

Run only the tests related to the tenant module:
npm test -- --grep "tenant"

We'll run the full suite before committing.

Używanie hooków do automatycznych kontroli jakości

Skonfiguruj hooki, aby output Claude’a był automatycznie walidowany:

.claude/settings.json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx eslint --fix $FILE_PATH && npx tsc --noEmit"
      }
    ]
  }
}

Z tą konfiguracją, każdy plik, który Claude tworzy lub edytuje, jest automatycznie lintowany i sprawdzany pod kątem typów. Problemy są łapane natychmiast, nie na końcu długiej sesji implementacji.

Wznawianie implementacji w wielu sesjach

Złożone funkcje obejmują wiele sesji. Nazywaj swoje sesje i używaj artefaktów do utrzymania ciągłości.

# Nazwij swoją sesję implementacji
/rename tenant-implementation

# Na końcu sesji, zapisz postęp

Przed zakończeniem sesji, niech Claude napisze checkpoint:

Write a brief status update to docs/plans/tenant-progress.md:
- What's been implemented and committed
- What's next
- Any decisions that were made during implementation
- Any blockers or open questions

Kiedy rozpoczynasz nową sesję:

Read docs/plans/tenant-progress.md and docs/specs/tenant-spec.md.
Also check git log --oneline -10 to see recent commits.
Pick up where we left off. What's the next chunk to implement?

Kiedy to nie działa

Claude generuje kod, który nie pasuje do twoich wzorców. Nie pokazałeś mu wystarczająco dużo przykładów. Przed implementacją zawsze niech Claude przeczyta przynajmniej dwa istniejące pliki, które podążają za wzorcem, który chcesz. Jeśli nadal odbiega, bądź wyraźny: “Use the exact same error handling as user.service.ts lines 45-60.”

Testy przechodzą, ale funkcja nie działa end-to-end. Twoje kawałki testów są zbyt wyizolowane. Dodaj test integracyjny po ukończeniu każdej warstwy, który ćwiczy pełny stos dla przynajmniej jednej happy path.

Implementacja odbiega od planu. To się dzieje, gdy Claude odkrywa coś podczas implementacji, czego plan nie uwzględniał. Kiedy to się stanie, zatrzymaj się: “Stop implementing. You just found something the plan didn’t cover. Explain the issue and propose an update to the plan before continuing.”

Kontekst wypełnia się podczas długiej implementacji. Uruchom /compact Focus on the tenant implementation. Keep the current file list, patterns, and progress. Drop exploration context. Lub, jeśli commitowałeś w punktach kontrolnych, rozpocznij świeżą sesję — twoje commity zachowują cały postęp.

Commit psuje testy dla niezwiązanego modułu. Twoja zmiana dotknęła współdzielonego narzędzia lub typu. Przed kontynuowaniem, napraw regresję. Następnie dodaj notatkę do swojego planu implementacji: “Shared module X is fragile. Changes here require running the full test suite.”

Co dalej

Twoja funkcja jest zaimplementowana i commitnięta. Teraz upewnij się, że jest przetestowana poza happy path i przejrzana przed wysłaniem.

Testing Generuj kompleksowe zestawy testów pasujące do istniejących wzorców twojego projektu

Debugging Kiedy coś się psuje podczas implementacji, śledź problem z terminala