Nowy projekt z terminala w Claude Code

Żeby postawić projekt w Claude Code, zrób commit pustego repozytorium, zatwierdź plan w trybie planowania, pozwól Claude uruchomić generator frameworka i dostosować wynik, a potem każ mu udowodnić, że szkielet działa – jednym skryptem verify, który uruchamia też CI. Szybka część tego skryptu pilnuje każdej odpowiedzi w hooku Stop, a /init zapisuje konwencje w CLAUDE.md.

Ta strona jest dla programistów, którzy zaczynają usługę od pustego katalogu, i dla tech leadów, którzy chcą, żeby każde nowe repozytorium w zespole startowało z tą samą bramką jakości. Sytuacja: product manager opisuje usługę jednym zdaniem – „REST API do preferencji użytkownika, PostgreSQL, uwierzytelnianie, rate limiting, logi strukturalne” – a zwykle oznacza to dzień klejenia infrastruktury, zanim powstanie jakakolwiek logika biznesowa. Claude Code pisze to okablowanie szybko. Trudność polega na tym, że drzewo katalogów niczego nie dowodzi, więc ten przepływ kończy się dowodami, które da się sprawdzić, a nie drzewem, o którym masz nadzieję, że się skompiluje. Potrzebujesz zainstalowanego i zalogowanego Claude Code (instalacja) oraz Gita i Dockera, żeby przejść przykład krok po kroku.

Co daje zweryfikowany bootstrap

• Plan zatwierdzony, zanim powstał pierwszy plik: stack, drzewo plików, zależności i lista kryteriów akceptacji.
• Szkielet wygenerowany narzędziem samego frameworka, jeśli takie istnieje, i dostosowany przez Claude do twoich konwencji.
• Jedno polecenie, scripts/verify.sh, które uruchamia linter, sprawdzanie typów i testy, startuje usługę i odpytuje /health. Uruchamiasz je ty przed commitem, a CI przy każdym pushu; jego szybka połowa, scripts/verify-fast.sh, działa w hooku Stop, zanim Claude może ogłosić koniec pracy.
• CLAUDE.md poniżej 200 linii, czyli limitu zalecanego przez producenta, oraz zapisany przepis uruchomienia dla wbudowanych skilli /run i /verify.
• Prompty copy-paste dla Expressa z Drizzle, Next.js, FastAPI i Phoenixa.

Którą drogą Claude ma zbudować szkielet?

Zdecyduj o tym przed pierwszym promptem. Od tej decyzji zależy, ile wyniku musisz sprawdzić.

Droga	Kiedy jej użyć	Co weryfikujesz
Claude uruchamia oficjalny generator (create-next-app, mix phx.new), potem dostosowuje wynik	Framework ma utrzymywany generator	Różnicę między wyjściem generatora a zmianami Claude oraz skrypt verify
Claude pisze projekt od zera	Żaden generator nie pasuje (API w Expressie, mały worker)	Każdy plik napisał agent, więc cały ciężar niosą skrypt verify i kryteria akceptacji
Claude kopiuje szablonowe repozytorium zespołu	Zespół ma już swoją „złotą ścieżkę”	Tylko różnicę specyficzną dla projektu; bramce szablonu już ufacie

Domyślna jest droga przez generator, bo boilerplate jest deterministyczny i utrzymują go autorzy frameworka. Wkład Claude kurczy się do tego, co specyficzne dla twojego projektu.

Zbuduj nową usługę od pustego katalogu

Przykład buduje API preferencji użytkownika z opisanej sytuacji. Te same kroki działają dla każdego stacku z następnej sekcji.

1. Utwórz repozytorium i zrób commit, zanim Claude czegokolwiek dotknie

   mkdir prefs-api && cd prefs-api
   git init
   git commit --allow-empty -m "chore: empty root"
   claude --permission-mode plan

   Pusty commit znaczy więcej, niż się wydaje. Checkpointy Claude Code nie śledzą plików zmienionych przez polecenia Bash, a generator czy npm install działają właśnie przez Bash. Esc Esc i /rewind nie cofną więc nieudanego szkieletu; git go cofnie.

   --permission-mode plan uruchamia sesję w trybie planowania: Claude bada i proponuje, ale nie zapisuje plików.

2. Poproś o plan z listą kryteriów akceptacji

   Ogólnikowy prompt w stylu „stwórz aplikację webową” zwraca generyczny szablon. Nazwij stack, układ katalogów, konwencje i to, co znaczy „gotowe”.

   Prompt copy-paste: plan produkcyjnego szkieletu API w Node

   Plan (do not write files yet) a Node.js Express API in TypeScript strict
   mode for a user-preferences service:
   
   - src/ with routes/, middleware/, services/, db/, lib/
   - Drizzle ORM against PostgreSQL with a migrations/ folder
   - Zod request validation middleware; JWT auth middleware (access + refresh)
     reading secrets from env only
   - express-rate-limit at 100 req/min per IP; pino JSON logs with request IDs
   - Vitest with a separate test database; docker-compose.yml for local Postgres
   - Multi-stage Dockerfile running as a non-root user
   - GitHub Actions CI that runs ./scripts/verify.sh
   - .env.example only, never a real .env
   
   First resource: GET /health and CRUD for "preferences", with error-handling
   middleware. Before listing dependencies, check each current version with
   `npm view <pkg> version` instead of guessing.
   
   Your plan must include: the file tree, the dependency list with versions,
   the commands you will run, and an acceptance checklist of 6-10 observable
   checks (for example "POST /preferences without a token returns 401").

   Czytaj plan, nie kod, którego jeszcze nie ma. Sprawdź, czy kryteria akceptacji opisują zachowanie, na którym ci zależy, i poprawiaj je w rozmowie, aż tak będzie. To tę listę zatwierdzasz później zamiast czytania każdej wygenerowanej linii.

3. Zatwierdź plan i pozwól Claude zbudować szkielet

   Zaakceptuj plan i wybierz tryb uprawnień na czas budowy. Od Claude Code v2.1.283 (kanał latest) tryb auto jest trybem startowym interaktywnych sesji w terminalu: klasyfikator ocenia każdą akcję i tylko ryzykowne trafiają do ciebie. Na kanale stable (v2.1.274 w dniu 2026-09-26) tryb auto jest trybem startowym tylko w planach Pro, Max i Team; sesje Enterprise, API i u dostawców chmurowych startują w trybie Manual, więc pytań o zgodę będzie więcej. Gdy pliki są na miejscu, zrób commit:

   git add -A && git commit -m "chore: scaffold prefs-api"

4. Każ Claude zbudować bramkę i udowodnić, że szkielet działa

   Prompt copy-paste: jeden skrypt verify, uruchomiony i sprawdzony

   Write scripts/verify.sh (bash, set -euo pipefail) that:
   1. runs the linter and the TypeScript type check
   2. starts Postgres with docker compose, applies the migrations, runs Vitest
   3. boots the dev server, curls /health until it returns 200 (30 s timeout),
      then stops the server and exits non-zero on any failure
   Put step 1 plus the unit tests (no Docker, no server) in
   scripts/verify-fast.sh, and have verify.sh call it first.
   
   Run verify.sh and fix everything until it passes. Then prove the gate can fail:
   temporarily break one assertion in a preferences test, run verify.sh, show
   me that it exits non-zero, and revert the change. Finish with a table that
   maps each acceptance-checklist item from the plan to the test or command
   that proves it, and list any item that has no proof yet.

   To tę tabelę przeglądasz zamiast kodu. Kryterium bez testu obok to luka, niezależnie od tego, jak wygląda kod. Claude radzi sobie też najlepiej, gdy ma przed sobą prawdziwy błąd: nieudana migracja albo konflikt wersji w stderr daje mu coś konkretnego do naprawienia.

5. Popraw jedną realną lukę

   Szkielety zwykle pomijają coś specyficznego dla twojego sposobu pracy. Nazwij to wprost, zamiast opisywać cały projekt od nowa.

   The CRUD handlers call Drizzle directly. Put a preferences service layer
   between routes and db so business logic is testable without HTTP, move the
   Zod schemas to src/schemas/, and run ./scripts/verify.sh again.

6. Zapisz konwencje i przepis uruchomienia

   /init

   /init analizuje projekt i zapisuje startowy CLAUDE.md z poleceniami budowania, instrukcjami testów i wykrytymi konwencjami; jeśli CLAUDE.md już istnieje, proponuje poprawki zamiast go nadpisywać. Dopisz reguły, których nie wywnioskuje z kodu – „warstwa serwisów między trasami a bazą”, „nigdy nie edytuj migracji ręcznie” – i trzymaj plik poniżej 200 linii, czyli celu z dokumentacji pamięci Anthropic. Anatomię dobrego pliku opisuje inicjalizacja projektu: CLAUDE.md i kontekst projektu.

   Potem uruchom /run-skill-generator. Ten wbudowany skill uruchamia aplikację od czystego środowiska i zapisuje przepis jako skill projektu w .claude/skills/run-<name>/ (zacommituj go razem ze szkieletem), dzięki czemu wbudowane skille /run i /verify następnym razem poprawnie startują usługę, zamiast zgadywać, jak podnieść Postgresa.

Po kroku 6 masz repozytorium, którego deklaracje da się sprawdzić: plan, który zatwierdziłeś, bramkę, którą widziałeś zarówno czerwoną, jak i zieloną, oraz mapowanie każdego kryterium akceptacji na jego dowód.

Jak utrzymać bramkę bez spowalniania każdej odpowiedzi?

Instrukcje w CLAUDE.md są tylko wskazówkami; hooki uruchamiają się za każdym razem. Hook Stop odpala się, gdy Claude kończy odpowiedź, a kod wyjścia 2 nie pozwala mu skończyć i przekazuje mu stderr. Hook odpala się po każdej odpowiedzi, także po odpowiedzi w trybie planowania i na zwykłe pytanie, więc podepnij tylko verify-fast.sh (linter, sprawdzanie typów, testy jednostkowe). Claude nie zgłosi wtedy „gotowe”, dopóki ta bramka jest czerwona, a odpowiedź nie czeka na Dockera. Dodaj to do .claude/settings.json, gdy skrypty już istnieją:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "cd \"$CLAUDE_PROJECT_DIR\" && { [ -z \"$(git status --porcelain)\" ] && exit 0; ./scripts/verify-fast.sh 1>&2 || exit 2; }"
          }
        ]
      }
    ]
  }
}

Stop nie przyjmuje matchera. Warunek z git status --porcelain pomija bramkę przy czystym drzewie roboczym, więc pytanie zadane po commicie nic nie kosztuje; dopóki zmiany nie są zacommitowane, każda odpowiedź uruchamia szybką bramkę i dlatego musi ona pozostać szybka. Liczy też nowe, nieśledzone pliki; git diff --quiet HEAD by ich nie zauważył i tura bootstrapu, która tylko dodaje pliki, skończyłaby się bez bramki. Claude Code ogranicza kontynuacje wymuszone przez hook Stop do ośmiu z rzędu, a potem kończy turę, więc bramka, która nie może przejść, nie zapętli sesji. Limit zmienisz zmienną CLAUDE_CODE_STOP_HOOK_BLOCK_CAP, a pole stop_hook_active w danych wejściowych hooka mówi skryptowi, że trwa już wymuszona kontynuacja. Przewodnik po hookach opisuje formatery w PostToolUse i blokady w PreToolUse.

Pełny verify.sh (szybka połowa plus Docker, migracje i start z /health) uruchamiasz przed każdym commitem i w CI. Ponieważ wywołuje verify-fast.sh, bramka w hooku Stop jest ścisłym podzbiorem bramki, którą musi przejść każdy merge, i obie nie mogą się rozjechać. Agent, który może edytować bramkę, może ją też osłabić, dlatego zmiany w scripts/verify*.sh i .claude/settings.json przechodzą przez przegląd człowieka; jak to zrobić, pokazuje ochrona wyroczni. Kto zatwierdza: programista akceptuje listę kryteriów i czyta tabelę dowodów, a nie każdą linię. Tech lead jest właścicielem promptu dla stacku i kontraktu verify, więc każde nowe repozytorium startuje z tą samą bramką.

Prompty startowe dla innych stacków

Każdy prompt ma ten sam kształt co prompt dla Expressa: najpierw generator, potem układ, konwencje, pierwszy zasób i ten sam kontrakt verify.

Next.js

Prompt copy-paste: szkielet Next.js z App Routerem

Run `npx create-next-app@latest web --help` first, then create the app
non-interactively with TypeScript, Tailwind CSS, ESLint, the App Router and a
src/ directory. Then add:

- Prisma with PostgreSQL, User and Session models; docker-compose.yml for Postgres
- a proxy.ts (Next.js 16 renamed middleware to proxy) that protects /app/*
- .env.example only, never a real .env
- scripts/verify.sh: lint, type check, tests, `next build`, boot and curl /

Server components by default, client components only for interactivity.
Named exports except page.tsx and layout.tsx. Run verify.sh until it passes.

FastAPI

Prompt copy-paste: szkielet usługi FastAPI

Create a FastAPI service with Python 3.13 and uv (pyproject.toml + uv.lock):

- src/ layout with routers/, models/, schemas/, services/
- SQLAlchemy 2.0 async sessions and Alembic migrations; Pydantic v2 schemas
- pytest with async fixtures and httpx for API tests
- ruff for lint and format, mypy for type checks
- multi-stage Dockerfile; docker-compose.yml for PostgreSQL
- scripts/verify.sh: ruff, mypy, pytest, boot uvicorn and curl /health

First resource: /health and CRUD for "projects" (list, detail, create, patch).
Run verify.sh until it passes and show me the output.

Phoenix

Prompt copy-paste: szkielet Phoenix LiveView

Generate the app with `mix phx.new acme` (Phoenix 1.8, PostgreSQL, LiveView
on by default), then run `mix phx.gen.auth Accounts User users --live`. Add:

- an Organization schema with a many-to-many to User in the Accounts context
- a LiveView dashboard that updates in real time via Phoenix.PubSub
- ExUnit tests for the context modules
- docker-compose.yml for PostgreSQL
- scripts/verify.sh: mix format --check-formatted, mix compile
  --warnings-as-errors, mix test, boot the server and curl /

Keep LiveView modules thin and put data access in contexts. Run verify.sh
until it passes.

Jak sprawić, by aplikacja nie wystartowała przy błędnej konfiguracji?

Szkielet, który tworzy pliki konfiguracyjne, nie jest gotowy, dopóki nie zobaczysz, jak konfiguracja coś odrzuca. Walidacja, która nigdy niczego nie odrzuciła, to walidacja, której nie masz.

Prompt copy-paste: walidowana konfiguracja zależna od środowiska

Add environment-aware config (development/staging/production) chosen by
NODE_ENV, exposed as one typed config object. Validate at startup with Zod:
PORT is a valid port, DATABASE_URL is a URL, JWT_SECRET is at least 32 chars.
On a missing or invalid value, exit with an error that names the key.

Then prove it: start the app with JWT_SECRET unset, show me it refuses to
boot with a clear error, set it, show a clean start, and add both cases to
the test suite so verify.sh covers them.

Jakie uprawnienia wybrać do bootstrapu albo prototypu na wyrzucenie?

Bootstrap uruchamia mnóstwo poleceń: instalacje pakietów, generatory, Dockera, migracje. Wybierz tryb świadomie:

• Tryb planowania (--permission-mode plan) w kroku 2, żeby nic nie zostało zapisane przed twoją akceptacją.
• Tryb auto na czas budowy od v2.1.283, a we wcześniejszych wersjach w planach Pro, Max i Team. Ustaw "defaultMode": "auto" w sekcji permissions pliku ~/.claude/settings.json (ustawienia użytkownika); Claude Code ignoruje auto i bypassPermissions jako defaultMode w ustawieniach projektu.
• --dangerously-skip-permissions wyłącznie w jednorazowym kontenerze z ograniczonym ruchem wychodzącym. Pomoc samego CLI zaleca tę flagę „only for sandboxes with no internet access”. Bootstrap potrzebuje rejestru pakietów, więc przepuść ruch tylko do niego, na przykład w dev containerze. Nigdy nie używaj jej w repozytorium ani na maszynie, na której ci zależy.

Prompt copy-paste: prototyp na wyrzucenie w piaskownicy

Build a minimal real-time collaborative whiteboard: Next.js + Socket.io + the
Canvas API. In-memory state, no auth, no database. Core only: draw, see other
cursors, clear the board. Start the dev server, open two clients with a
Playwright script to prove strokes sync between them, and tell me the URL.

Sprawdź pomysł w piaskownicy, a wersję, którą zostawiasz, zbuduj od nowa pełnym przepływem opisanym wyżej. Przewodnik po uprawnieniach i piaskownicach porównuje tryby w różnych narzędziach.

Podłącz bazę danych i udostępnij zespołowi przepisy

Dwa rozszerzenia eliminują zgadywanie podczas bootstrapu i rozwiązują różne problemy. Serwer MCP to żywe połączenie z systemem. Skill to przepis wielokrotnego użytku.

Postgres MCP Pro pozwala Claude czytać żywy lokalny schemat i plany zapytań, zamiast zgadywać nazwy kolumn. To pakiet Pythona, więc uruchamia się go przez uvx, a --access-mode=restricted ogranicza go do transakcji tylko do odczytu. Wskaż mu lokalną bazę w Dockerze, nigdy produkcję. Rozwój pakietu wyhamował – najnowsze wydanie na PyPI to 0.3.0 z 2025-05-16 (stan na 2026-09-26) – więc sprawdź repozytorium, zanim wbudujesz go w szablon zespołu:

claude mcp add postgres -e DATABASE_URI="$DATABASE_URL" -- uvx postgres-mcp --access-mode=restricted

W przypadku GitHuba gh repo create wywołane przez narzędzie Bash załatwia utworzenie repozytorium i otwarcie pierwszego pull requesta bez ładowania do kontekstu definicji narzędzi jakiegokolwiek serwera MCP. Serwer MCP GitHuba dodaj wtedy, gdy agent ma czytać logi Actions albo wątki przeglądu. Inne opcje opisują serwery MCP dla baz danych.

Skill projektu zamienia zespołową rutynę „dodaj zasób” w jedno polecenie. Zapisz go jako .claude/skills/new-resource/SKILL.md:

---
name: new-resource
description: Scaffold a CRUD resource with route, service, schema and tests
---
Create the resource $ARGUMENTS following CLAUDE.md:

1. src/routes/$ARGUMENTS.ts, thin, calling the service only
2. src/services/$ARGUMENTS.service.ts with the business logic
3. src/schemas/$ARGUMENTS.schema.ts with Zod request and response schemas
4. src/services/$ARGUMENTS.service.test.ts covering 401, 404, 422 and the happy path
5. Run ./scripts/verify.sh and report the result

Uruchom go poleceniem /new-resource notifications. Skille publikowane przez innych opisuje instalowanie skilli i zarządzanie nimi.

Dołączasz do istniejącej bazy kodu?

Gdy repozytorium już istnieje, pomiń szkielet i zacznij od /init. Tryb interaktywny włączysz, ustawiając CLAUDE_CODE_NEW_INIT=1 przed uruchomieniem /init (sprawdzone w Claude Code 2.1.283): Claude pyta wtedy, które artefakty skonfigurować (pliki CLAUDE.md, skille, hooki), bada kod subagentem, zadaje pytania uzupełniające i pokazuje propozycję do przejrzenia, zanim cokolwiek zapisze. Jeśli repozytorium ma AGENTS.md, a nie ma CLAUDE.md, Claude Code od v2.1.277 na kanale latest czyta AGENTS.md jako instrukcje projektu (v2.1.281 w Bedrock, Google Cloud, Foundry i bramkach LLM; przełącznik w sekcji Project instructions w /config).

Potem zmapuj kod według przewodnika analiza bazy kodu. Jeśli prawdziwym zadaniem jest przeniesienie starej aplikacji na nowy toolchain, zastosuj podejście etapowe z przewodnika migracje baz danych i kodu.

Gdy bootstrap w Claude Code idzie źle

Wynik to generyczny szablon. Prompt był zbyt ogólny. Dodaj układ katalogów, konwencje i kryteria akceptacji albo przejdź na drogę przez generator, żeby boilerplate należał do frameworka.

Zależności są w konflikcie albo wersja nie istnieje. Wiedza modelu o wersjach nie nadąża za rejestrem. Każ Claude odczytywać wersje przez npm view <pkg> version (albo pip index versions, mix hex.info), commitować lockfile i pozwól, żeby konflikt wyszedł w verify.sh. Wklejaj prawdziwe stderr, zamiast je opisywać.

/rewind nie cofnął szkieletu. Checkpointy nie śledzą plików zapisanych przez polecenia Bash, więc wynik generatora i instalacji przetrwa cofnięcie. Uruchom git status, żeby zobaczyć zmiany, a potem git stash -u albo git reset --hard do commita z pustym korzeniem lub ze szkieletem.

Bramka jest zielona, ale niczego nie dowodzi. Testy bez asercji albo trasa /health, która zwraca 200 bez dotykania bazy, przechodzą zawsze. Dlatego krok 4 celowo psuje asercję. Poproś, żeby /health wykonywał SELECT 1, i powtarzaj test „zepsuj i sprawdź” przy każdej zmianie bramki.

Hook Stop nie pozwala Claude skończyć. Bramka pada z powodu, którego Claude nie naprawi, na przykład wyłączonego Dockera. Claude Code kończy turę po ośmiu kolejnych kontynuacjach (limit zmienia CLAUDE_CODE_STOP_HOOK_BLOCK_CAP); napraw środowisko albo usuń hook na czas debugowania skryptu. Jeśli przyczyną jest Docker, sprawdź, czy hook wywołuje verify-fast.sh, a nie pełny verify.sh.

W długiej sesji Claude zapomina wczesne instrukcje. Instrukcja podana tylko w czacie, na przykład „wyłącznie eksporty nazwane”, może wypaść z kontekstu, gdy ten się zapełnia. Przenieś ją do CLAUDE.md albo do reguły z zakresem ścieżek w .claude/rules/; zobacz przewodnik po systemie pamięci.

uvx: command not found przy starcie serwera Postgres MCP. Zainstaluj uv, uruchom sesję ponownie i potwierdź działanie serwera poleceniem claude mcp list.

Dokąd dalej, gdy szkielet przechodzi bramkę

Planowanie funkcji Zamień kolejne wymaganie w plan implementacji w trybie planowania

Wykonywalne kryteria akceptacji Zamień listę kryteriów w padające testy, zanim agent napisze kod

Tworzenie API Buduj endpointy na szkielecie, a Claude Code niech prowadzi testy

Baza kodu gotowa na agentów Środowisko pracy agenta (harness), dzięki któremu kolejne sesje agenta w tym repozytorium są produktywne

Pracujesz w innym narzędziu? Ten sam przepływ opisują nowy projekt w Cursorze i nowy projekt w Codeksie.