07 — Nowy projekt: Dzień 0

Konkretna checklista, którą Claude wykonuje rozpoczynając nowy projekt. Cel: po Dniu 0 każda kolejna sesja ma grunt pod nogami.

Najpierw wepnij The Craft (jednorazowo)

Zanim ruszysz właściwy Dzień 0, wepnij doktrynę do projektu tak, żeby agent ją realnie czytał. Reguły, których agent nigdy nie otworzy, są martwe — to wpięcie sprawia, że działają.

Umieść The Craft w docs/rules/ — jako git submodule (zostaje aktualizowalne) albo zwykła kopia:

git submodule add https://github.com/JKolada/TheCraftWithClaude docs/rules
# albo: po prostu skopiuj pliki do docs/rules/

Wskaż na to w CLAUDE.md projektu — żeby każda sesja ładowała reguły i wiedziała, jak po nich nawigować. Dopisz blisko góry:

Czytaj docs/rules/ co sesję — to doktryna budowania (The Craft). Szukasz tematu? grep -i <keyword> po docs/rules/AI_README.md → właściwy rozdział; czytaj tylko ten (oszczędność kontekstu).
Wybierz język — angielski jest bazą (root repo), polski leży w pl/. Agent czyta tę kopię.
Potem wypełnij brief (następna sekcja); jego wynik brief-projektu.md ląduje w rootcie projektu, a z niego składasz własny CLAUDE.md projektu.

Ładną stronę instalacji (komendy do skopiowania, wybór paczki/języka) robi The Craft Web — to jest minimalne, kanoniczne wpięcie, które podróżuje razem z plikami.

0. Brief produktowy — dopytaj, zanim cokolwiek powstanie

Przed pierwszą linią kodu i przed CLAUDE.md zadaj użytkownikowi zestaw pytań — i nie zgaduj domyślnych odpowiedzi tam, gdzie zmieniają architekturę, prawo lub markę. Te decyzje są tańsze na papierze niż w kodzie (i18n dorzucony później to przepisywanie, monetyzacja po fakcie to Migracja (bazy danych) — Kontrolowana zmiana układu bazy — dodanie kolumny, tabeli czy przeniesienie danych — krok po kroku. Jak remont według planu: przebudowa danych w ustalonej kolejności, żeby nic się nie „zawaliło”. danych). Pytaj zwięźle, grupami; jeśli czegoś user nie wie — zaproponuj domyślną i zaznacz ją jako założenie. Te same pytania zadaj aplikując doktrynę do istniejącego projektu — wtedy jako audyt („co już jest, czego brak”).

Poziom techniczny użytkownika i styl komunikacji. Zadaj to pierwsze — ustawia rejestr całej rozmowy. Czy programujesz / czytasz kod? Czy znasz pojęcia jak repo, deploy, baza danych, API — Umówiony sposób, w jaki dwa programy gadają ze sobą — jeden prosi, drugi odpowiada w ustalonym formacie. Przez API Twoja aplikacja łączy się z cudzymi usługami (płatności, mapy, AI). Klucz API traktuj jak hasło. — czy mam je tłumaczyć? Wolisz decyzje techniczne podejmowane za Ciebie (z krótkim „dlaczego”), czy chcesz je rozumieć i współdecydować? Jak raportować postęp: zwięźle „działa/nie działa”, czy z detalami? → Przy odpowiedziach „nietechniczny” przełącz rejestr: zero żargonu bez wyjaśnienia, analogie zamiast terminów, pytania zamknięte z rekomendacją zamiast otwartych technicznych, decyzje domyślne + zgoda zamiast narady. To ta sama treść doktryny, inny język podania (→ edycje: techniczna / BIZ-TECH / biznesowa, zob. nagłówek repo).
Twoje języki i Twój warsztat. W jakich językach mówisz/czytasz — żebym rozmawiał z Tobą w Twoim natywnym (najlepiej brief mi w języku, w którym myślisz)? Jakie technologie realnie znasz — żebym dobrał głębię wyjaśnień i oparł się na Twoim stacku, a nie obcym? → Zapisuję to w CLAUDE.md/AI_README.md (iloma językami mówisz + znane technologie), żeby każda sesja porozumiewała się z Tobą w Twoim języku i na Twoim poziomie. To konfiguracja współpracy, ustawiana raz.
Języki docelowe i rynki. Jeden język czy wiele? Które, w jakiej kolejności, który jest źródłem prawdy? Parytet treści jako wymóg? RTL? Waluty/strefy/format dat? → decyduje o i18n od Dnia 0 i strukturze danych (10, 11).
Funkcjonalności — rdzeń vs „później”. Co jest MVP (bez czego produkt nie istnieje), a co jest miłe-do-mienia? Konta i role? Treść statyczna czy user-generated? Integracje zewnętrzne (płatności, mapy, AI, e-mail)? → wyznacza warstwy i Feature flag — Wewnętrzny włącznik, który uruchamia nową funkcję dla części ludzi albo wyłącza ją bez przerabiania kodu. Wpuszczasz nowość stopniowo i wycofujesz w sekundę — najtańsza polisa przy każdej zmianie. (12).
Monetyzacja. Darmowe, płatne, freemium, subskrypcja, jednorazowo, reklamy, afiliacja? Kiedy pojawia się płatność (Dzień 1 czy po trakcji)? Dostawca (Stripe/inny), faktury, VAT/OSS? → dotyka modelu danych i obowiązków prawnych (09, 11).
Styl UX i kierunek wizualny. Grupa docelowa i ton (poważny B2B ↔ zabawowy konsumencki)? Jest marka (paleta, typografia, logo) czy tworzymy od zera? Gęsty dashboard czy przewiewny landing? Tryb jasny/ciemny? Dostępność (WCAG) jako wymóg?
Animacje i „odczucie” interfejsu. Statyczny i szybki, czy bogaty w mikrointerakcje i przejścia? Budżet wydajności i prefers-reduced-motion jako zasada? → animacja nie może bić się z Core Web Vitals — Miary od Google: jak szybko strona się pokazuje, jak stabilnie się układa i jak szybko reaguje. Wpływają na pozycję w Google i na to, czy użytkownik nie ucieknie. Mierzalne, więc da się je poprawiać. (13).
Wydźwięk marketingowy. Jedno zdanie wartości (value prop), kto jest klientem, czego unikamy w tonie? Nazwa/domena/hasło ustalone? To samo „dlaczego”, które potem napędza changelog i copy pisane językiem użytkownika (08 → 01).

Zapisz odpowiedzi, nie tylko je usłysz: twarde decyzje → CLAUDE.md (polityki) i memory/ (cel biznesowy, ograniczenia — krok 10). Założenia przyjęte za usera oznacz wyraźnie, by dało się je później zweryfikować.

Gdzie ląduje brief. Najszybciej wypełnisz go w czytniku Craft (widok „Brief” → generuje gotowy Markdown). Wypełniony brief:

zapisz jako brief-projektu.md w głównym folderze nowego projektu (Craft jest dołączony jako docs/rules/, więc brief leży obok — w rootcie repo projektu, nie w docs/rules/), albo
wklej całość wprost do Claude Code / Claude Desktop otwartego w głównym folderze projektu jako pierwszą wiadomość.

Brief to wejście do reszty Dnia 0: z niego rodzi się CLAUDE.md (krok 2) i wpis w memory/ (krok 10).

Anty-wzorce

🚫 Skok do kodu bez briefu — „zacznę, dopytam po drodze”. Język, monetyzacja i marka wpisane po fakcie to przepisywanie, nie poprawka.
🚫 Zasypanie pytaniami — 30 pytań naraz zniechęca. Pytaj grupami, o to co zmienia plan; resztę zaproponuj jako domyślne.
🚫 Ciche założenia — przyjęcie „pewnie tylko polski” albo „pewnie za darmo” bez zaznaczenia, że to Twoje założenie, nie decyzja użytkownika.
🚫 Żargon do nietechnicznego usera — „zrobię rebase i podbiję semver po migracji” do osoby, która nie programuje. Najpierw ustal poziom, potem dobierz język. Brak adaptacji rejestru wyklucza połowę odbiorców doktryny.

1. Rozpoznanie (zanim cokolwiek napiszesz — Przykazanie II)

Przeczytaj istniejący CLAUDE.md / AI_README.md / README, jeśli są.
git log --oneline -20, git status — co już jest, co w toku, czy są sieroty/śmieci.
Zidentyfikuj stack, sposób uruchomienia, gdzie żyją dane.
Wypisz, czego jeszcze nie wiesz — i dopytaj tylko o to, co zmienia plan.

2. Konstytucja projektu — `CLAUDE.md`

Quick orientation (warstwa → tech → lokalizacja).
Dokładne komendy uruchomienia (interpreter, port, env).
Polityki nadrzędne: „nigdy nie deployuj automatycznie”, privacy/compliance, git workflow.
Sekcja „Current state” z datą i liczbami.

Szkielet na start (uzupełnij, potem wytnij, co nie pasuje — trzymaj krótko, czytane co sesję):

# CLAUDE.md — <Projekt>

## Czym to jest
<jeden akapit: co robi, dla kogo>

## Stack i jak uruchomić
<warstwa → tech → lokalizacja, jako mała tabela>
# uruchom: <dokładna komenda, np. python -m http.server 8080 → http://localhost:8080>

## Polityki (nadpisują domyślne zachowanie)
- Nigdy deploy/push bez jawnego „wdrażaj". Commituj swobodnie; potwierdzaj nieodwracalne.
- Dry-run domyślny; --execute świadomy. Prod święty; dane usera nienaruszalne.
- Mów do mnie w <język natywny usera>; znam <języki / technologie programisty>.
- Czytaj docs/rules/ co sesję (The Craft); temat: grep -i <keyword> docs/rules/AI_README.md.
- <twarde reguły projektu: privacy/compliance, ograniczenia domeny>

## Stan bieżący (<data>)
- <liczby: rekordy, zastosowane migracje, co jest live>

Szczegóły tu nie idą — żyją w AI_README.md per folder i w docs/ (→ 01).

3. Higiena repo

.gitignore: zależności, lokalne bazy, backupy (*.bak), assety generowane, temp, scratch. (Pamiętaj: # komentarz w osobnej linii.)
Konwencja commitów + tagowania deployów.
Task tracking (Issues / docs/plans/) — gdzie żyją zadania.

4. Dokumentacja per katalog

AI_README.md w każdym istotnym katalogu (choćby szkielet).
docs/ na stabilną referencję (architektura, schemat danych) i plany.

5. Skille (automatyzacja powtarzalnego)

/run-<projekt> — uruchom + Smoke test — Szybki test „czy w ogóle działa” zaraz po wdrożeniu — sprawdza najważniejsze ścieżki (np. logowanie). Łapie katastrofy w 30 sekund, zanim zobaczy je użytkownik. Tani sposób na spokojny sen po deployu. (N tras, markery, exit code).
/run-tests — pełny suite (unit + integration + e2e).
/update-ai-readme — sync docsów przed commitem.
/add-migration — jeśli relacyjna baza (numer → SQL — Język zapytań do bazy danych — sposób, w jaki „pytasz” bazę o dane albo je zmieniasz. Uniwersalny standard rozmowy z bazą. Źle napisane zapytanie potrafi zamulić całą aplikację. → apply → AI_README → commit).

6. Testy i weryfikacja

Szkielet unit + integration; smoke test z markerami.
(Jeśli UI) Playwright na osobnym porcie.
Zasada: testy ścieżki krytycznej przed commitem; „weryfikuj, nie deklaruj”.

7. Bazy i skrypty

Migracje forward-only + katalog backups/ + retencja.
Każdy skrypt mutujący: --dry-run domyślnie, --execute świadomie, idempotentny.
Nightly backup od momentu pierwszych prawdziwych userów.

8. Produkcja (przygotuj, nie odpalaj)

Runbook deployu (code-only vs okno maintenance) — spisz, zanim będzie potrzebny.
Branded maintenance page + flaga (np. nginx — Program na froncie serwera, który przyjmuje ruch z internetu i kieruje go do Twojej aplikacji. Obsługuje HTTPS, podaje pliki statyczne, rozkłada ruch — sprawdzona „recepcja” serwera. /tmp/<app>_maintenance).
Plan Rollback — Cofnięcie zmiany do poprzedniego, działającego stanu — „Ctrl+Z” dla wdrożenia. Gdy nowa wersja psuje produkcję, rollback przywraca poprzednią w sekundy zamiast naprawiać w panice.: tag kodu + backup bazy.
Publiczny changelog „Co nowego” (pinned), pisany językiem użytkownika.

9. Compliance / prywatność (jeśli dotyczy danych ludzi)

Polityka prywatności + zgody, anonimizacja, retencja — jako reguła w konstytucji.
Disclaimery (np. „dla pełnoletnich”, „nie świadczymy usług terapeutycznych”).
i18n od początku, jeśli produkt globalny.

10. Pamięć

Zapisz w memory/: kim jest user, cel biznesowy, twarde ograniczenia projektu (to, czego nie ma w kodzie).

Minimalny Dzień 0, gdy nie ma czasu na wszystko: krótki brief (krok 0: język, MVP, monetyzacja, ton) → CLAUDE.md (stack + jak uruchomić + polityki) → .gitignore → jeden skill /run-<projekt> ze smoke testem → szkielet testów → katalog backups/. Reszta dorasta z projektem.