Konfiguracja i inicjalizacja projektów

Jest poniedziałek rano. Twój product manager właśnie opisał nowy mikroserwis: “Potrzebujemy REST API, które obsługuje preferencje użytkowników, przechowuje je w PostgreSQL, z uwierzytelnianiem, rate limitingiem i strukturalnym logowaniem.” Tradycyjna odpowiedź to dzień okablowania boilerplate, zanim napiszesz linię logiki biznesowej. Z Claude Code opisujesz usługę, on buduje szkielet, a Ty spędzasz czas na weryfikacji zamiast na pisaniu.

Sztuczka nie polega na generowaniu — każde narzędzie potrafi wypluć drzewo katalogów. Sztuczka polega na poprowadzeniu pierwszego promptu tak, aby otrzymać szkielet produkcyjny, a następnie na prowadzeniu ścisłej pętli “buduj, zweryfikuj, że działa, koryguj kurs”, żeby wyłapać luki, zanim się skumulują.

Co Wyniesiesz z Tej Lekcji

• Powtarzalną pętlę bootstrapowania: opisz, wygeneruj, zweryfikuj, koryguj kurs
• Zwięzły CLAUDE.md, który przetrwa kolejne sesje, nie będąc ignorowanym
• Prompty copy-paste do API Node/Express, migracji na TypeScript i konfiguracji CI/CD
• Realny przepływ prototypowania z użyciem --dangerously-skip-permissions zamiast wymyślonych “trybów”

Od pomysłu do działającego kodu

Bootstrap, który działa, to nie “wpisz jedno życzenie i odejdź”. To cztery ruchy: opisz konkretnie, pozwól Claude zbudować szkielet, a następnie od razu każ mu udowodnić, że szkielet działa.

1. Stwórz katalog projektu i uruchom Claude Code

   mkdir user-preferences-api && cd user-preferences-api
   git init
   claude

   git init na początku ma znaczenie: Claude Code jest git-aware i commituje w logicznych punktach kontrolnych, więc możesz się cofnąć, jeśli krok scaffoldingu pójdzie nie tak.

2. Opisz usługę z wystarczającą szczegółowością, aby uniknąć generycznego szablonu

   Wskazówka

   Prompt copy-paste do produkcyjnego szkieletu API Node:

   Scaffold a Node.js Express API in TypeScript strict mode for user
   preferences. Use:
   
   - src/ with routes/, middleware/, services/, db/, and lib/ directories
   - Drizzle ORM against PostgreSQL, with a migrations/ folder
   - Zod for request validation middleware
   - JWT auth middleware (access + refresh), reading secrets from env only
   - express-rate-limit at 100 req/min per IP
   - pino for structured JSON logging with request IDs
   - Vitest with a separate test database config
   - A multi-stage Dockerfile running as a non-root user
   - docker-compose.yml for local PostgreSQL 17
   
   Include a /health route and full CRUD for a "preferences" resource with
   error-handling middleware. Async/await everywhere, no callbacks. Put env
   templates in .env.example and never create a real .env.

3. Każ Claude udowodnić, że szkielet działa, zanim na nim zbudujesz

   To jest krok, który odróżnia realny przepływ pracy od broszury. Nie ufaj zrzutowi drzewa — uruchom go.

   Start Postgres with docker compose, run the migrations, then start the
   dev server and confirm /health returns 200. Run the linter and the test
   suite. Paste any errors and fix them until everything is green.

   Claude jest najlepszy z prawdziwym błędem przed oczami. Gdy wersja zależności się kłóci albo migracja zawodzi, to właśnie faktyczny stderr pozwala mu skorygować kurs precyzyjnie, zamiast zgadywać.

4. Skoryguj kurs w jednej realnej luce

   Wygenerowane szkielety prawie zawsze pomijają coś specyficznego dla tego, jak pracujesz. Nazwij to wprost, zamiast opisywać cały projekt od nowa:

   The CRUD handlers call Drizzle directly. Extract a preferences service
   layer between the routes and the DB so business logic is testable in
   isolation, and move the Zod schemas into src/schemas/.

W ciągu kilku minut masz bazę kodu, którą faktycznie uruchomiłeś: warstwę serwisów, zwalidowane routy, migracje, które się zaaplikowały, przechodzący zestaw testów i konfigurację Docker, którą widziałeś jak startuje — a nie drzewo, o którym masz nadzieję, że się kompiluje.

Fundament: CLAUDE.md

Kontekst jest tym, co czyni Claude Code skutecznym między sesjami. CLAUDE.md to trwała pamięć Twojego projektu — przetrwa, gdy rozmowa już nie.

Wygeneruj go automatycznie, potem przytnij

Uruchom /init wewnątrz Claude Code. Czyta Twój package.json, przechodzi przez strukturę katalogów, wykrywa framework testowy i pisze startowy CLAUDE.md. Output jest punktem wyjścia, a nie gotowym plikiem — najlepsze pliki CLAUDE.md są mocno przycięte i dopracowywane w czasie.

# User Preferences API

## Tech Stack
- Node.js 22.x, Express, TypeScript strict
- PostgreSQL 17 via Drizzle ORM
- Redis for rate-limit counters

## Commands
- npm run dev      # start dev server on :3000
- npm test         # vitest
- npm run migrate  # drizzle migrations
- docker compose up

## Conventions
- Service layer between routes and DB; routes stay thin
- Zod validates every request body; never trust client input
- Named exports only; colocate Button.tsx / Button.test.tsx

## Gotchas
- IMPORTANT: never commit .env. Use .env.example.
- Migrations are append-only; use the generator, never hand-edit

Uwaga

Przeładowany CLAUDE.md jest gorszy niż jego brak. Powyżej mniej więcej 50 linii Claude zaczyna ignorować poszczególne zasady, ponieważ te ważne zostają zakopane. Jeśli Claude nadal robi coś, przeciwko czemu masz zasadę, plik jest prawdopodobnie zbyt rozdęty — przycinaj bezlitośnie. Jeśli usunięcie linii nie zmieniłoby zachowania Claude, usuń ją.

Notatka

Umiejscowienie kontroluje zakres. CLAUDE.md w roocie obejmuje cały projekt; CLAUDE.md w podkatalogu dodaje zasady specyficzne dla modułu; ~/.claude/CLAUDE.md przechowuje osobiste preferencje obowiązujące wszędzie. W monorepo trzymaj wspólne standardy w roocie i pozwól każdej aplikacji dodać własne.

Progresywna migracja, nie przepisanie

Dziedziczysz legacy aplikację Express i potrzebujesz jej na TypeScript bez ryzykownego przepisania big-bang. Przepływ pracy to ta sama pętla opisz-wygeneruj-zweryfikuj, stosowana po jednej fazie naraz, tak aby aplikacja pozostawała wdrażalna na każdym kroku.

1. Zdobądź plan fazowy, a nie diff

   Analyze this Express app and propose a phased migration to TypeScript
   strict that keeps the service deployable after each phase. Start with
   tsconfig + build wiring and the leaf modules with no internal imports.

2. Wykonaj fazę pierwszą i potwierdź, że build nadal się wdraża

   Implement phase 1: add the TypeScript config and convert the leaf
   modules. Then run the build and the existing test suite and confirm
   both pass before we touch anything else.

3. Iteruj, weryfikując każdą fazę

   Tests pass. Convert the next layer (the route handlers), add types for
   the external deps they use, and run the suite again. Stop if anything
   breaks.

Dyscyplina tkwi w kroku weryfikacji między fazami. Pominięcie go to sposób, w jaki “stopniowa” migracja po cichu zbiera setkę błędów typów, które odkrywasz wszystkie naraz.

Szybkie prototypowanie

Jesteś na hackathonie. Chcesz zwalidować pomysł w godziny, a prompty o uprawnienia przy każdym zapisie pliku Cię spowalniają. W Claude Code nie ma “trybu YOLO” — realnym mechanizmem jest flaga --dangerously-skip-permissions (lub tryb uprawnień bypassPermissions), która pomija prompty zatwierdzeń na czas sesji.

claude --dangerously-skip-permissions

Następnie podaj mu prompt buildowy o ograniczonym zakresie:

Wskazówka

Prompt copy-paste do jednorazowego prototypu:

Build a minimal real-time collaborative whiteboard: Next.js 16 + Socket.io
+ the Canvas API, deployable to Vercel. In-memory state is fine, no auth,
no database. Core only: draw, see other cursors, clear board. Get it
running on the dev server and tell me the URL.

Uwaga

--dangerously-skip-permissions jest dokładnie tym, co mówi: Claude może edytować pliki i uruchamiać komendy bez pytania. Świetnie sprawdza się w piaskownicowym prototypie, gdzie najgorszym scenariuszem jest wyrzucenie repo, a jest złym pomysłem w jakimkolwiek repo, na którym Ci zależy. Uruchom go w świeżym katalogu, zwaliduj pomysł, a potem odbuduj wersję na stałe w normalnej sesji, gdzie przeglądasz każdą zmianę.

Struktura projektu w różnych narzędziach

Bootstrapowanie projektu to jeden z nielicznych przepływów pracy, które wyglądają znacząco inaczej w każdym narzędziu, więc sięgnij po to, które pasuje do tego, jak pracujesz.

Cursor

Otwórz pusty folder, przełącz Agenta na mocny model (Claude Opus 4.8 do większości szkieletów; Claude Fable 5, gdy priorytetem jest budowanie od zera i budżet ma mniejsze znaczenie) i wklej ten sam prompt scaffoldingowy w trybie Agent. Cursor proponuje drzewo plików jako diff, który akceptujesz lub odrzucasz per plik, a jego checkpointy pozwalają cofnąć zły krok scaffoldingu z paska bocznego zamiast git reset.

Claude Code

Przepływ terminal-first opisany powyżej: git init, claude, wklej prompt scaffoldingowy, a następnie prowadź pętlę weryfikacji (“uruchom serwer deweloperski, uruchom testy, napraw błędy”) w tej samej sesji. /init generuje CLAUDE.md. Najlepsze, gdy chcesz mieć build i weryfikację w jednym, skryptowalnym miejscu.

Codex

Uruchom codex w pustym katalogu (GPT-5.5 domyślnie) i wklej prompt scaffoldingowy. Dla niezaufanego szkieletu zacznij w trybie read-only i zatwierdzaj zapisy w miarę ich pojawiania się: codex --ask-for-approval on-request. Użyj codex --full-auto, gdy zaufasz planowi. Codex potrafi też rozpocząć cały scaffolding z GitHub issue w chmurze, a następnie otworzyć PR, który przeglądasz.

Konfiguracja, która sama się waliduje

Szkielet, który wypluwa pliki konfiguracyjne, nie jest gotowy — chcesz konfiguracji, która głośno zawodzi na złej wartości, i chcesz zobaczyć, jak zawodzi. Poproś o konfigurację świadomą środowiska z walidacją przy starcie, a potem przetestuj tę walidację, podsuwając jej coś zepsutego.

Wskazówka

Prompt copy-paste do zwalidowanej konfiguracji świadomej środowiska:

Add environment-aware config (development/staging/production) loaded by
NODE_ENV, with a single typed config object. Validate it at startup with
Zod: PORT is a valid port, DATABASE_URL is a URL, JWT_SECRET is >= 32
chars. On a missing or invalid value, throw with the offending key named.

Then prove it: start the app with JWT_SECRET unset and show me that it
refuses to boot with a clear error, then set it and show a clean start.

Połowa “then prove it” jest tu sednem. Walidacja konfiguracji, której nigdy nie widziałeś nic odrzucić, to walidacja konfiguracji, której faktycznie nie masz.

Przyspieszanie konfiguracji z MCP i Skills

Dwa dodatki realnie skracają czas konfiguracji i oba działają w Cursor, Claude Code i Codex:

• Serwer Postgres MCP pozwala Claude introspekować Twój żywy schemat zamiast zgadywać nazwy kolumn, gdy pisze migracje i zapytania. Dodaj go w Claude Code za pomocą claude mcp add --transport stdio postgres -- npx -y @modelcontextprotocol/server-postgres "$DATABASE_URL". Ta sama konfiguracja serwera wpada do Cursora i Codeksa.
• Serwer GitHub MCP (@modelcontextprotocol/server-github) pozwala tej samej sesji stworzyć repo, wypchnąć szkielet i otworzyć pierwszy PR bez wychodzenia z terminala.
• Do jednorazowego rozszerzenia, a nie trwałego połączenia, Agent Skill jest lżejszą opcją. Przejrzyj skills.sh i zainstaluj za pomocą uniwersalnego CLI — npx skills add <owner/repo> — które działa w Claude Code, Cursor i Codex. Sięgnij po skill, gdy chcesz pojedynczej, wielokrotnego użytku zdolności (przebieg code review, przepis na deploy); sięgnij po serwer MCP, gdy chcesz żywego, stanowego połączenia z narzędziem.

Kiedy To Się Psuje

Claude wypluwa generyczny szablon zamiast tego, co opisałeś. Twój prompt był zbyt niejasny. Dodaj wersje frameworków, dokładny układ katalogów i swoje konwencje. Szczegółowość, którą wkładasz na początku, to korekta kursu, której unikasz później.

Wygenerowany projekt ma konflikty zależności. Claude czasami pobiera niezgodne wersje. To jest dokładnie powód, dla którego krok weryfikacji jest nienegocjowalny — “uruchom serwer deweloperski i napraw wszelkie błędy” stawia prawdziwy stderr przed Claude, a on dobrze rozwiązuje konflikty, gdy widzi faktyczną awarię.

/init pomija konwencje Twojego zespołu. Czyta strukturę kodu, a nie niepisane zasady. Zawsze uzupełniaj jego output o rzeczy, które żyją tylko w głowach ludzi: nazewnictwo branchy, proces PR, kroki wdrożenia. Następnie waliduj, zadając pytanie, na które tylko dobrze skonfigurowany CLAUDE.md mógłby odpowiedzieć (“Jak uruchomić tylko testy jednostkowe modułu auth?”).

Szkielet odchodzi od Twojego promptu w trakcie długiej sesji. Gdy kontekst się zapełnia, Claude może zapomnieć wczesną instrukcję (tylko named exports, bez default exports). Powtórz tę zasadę w CLAUDE.md, aby przetrwała, zamiast powtarzać ją w czacie za każdym razem.

CLAUDE.md jest ignorowany w późniejszych sesjach. Plik jest zbyt długi lub zbyt niejasny. Przytnij go poniżej ~50 linii i uczyń każdą linię konkretną i wykonalną. “Pisz czysty kod” nie wnosi nic; “Warstwa serwisów między routami a DB; routy pozostają cienkie” zarabia na swoje miejsce.

Co Dalej

Możesz przejść od zera do usługi, którą faktycznie uruchomiłeś. Dalej naucz się, jak Claude Code nawiguje po kodzie, którego nie napisałeś.

Rozwój API Głębokie zagłębienie w budowanie solidnych API z Claude Code

Praca z bazą danych Opanuj projektowanie bazy danych i migracje z pomocą AI

Strategie testowania Skonfiguruj kompleksowe testowanie od pierwszego dnia