Inżynieria promptów dla Claude Code

Inżynieria promptów dla Claude Code polega na pisaniu każdej prośby jako krótkiego briefu: co zmienić, gdzie, dlaczego oraz jaki warunek ukończenia Claude sprawdza sam. Najważniejszy jest warunek ukończenia, bo zamienia prośbę w pracę, którą Claude udowadnia testem lub poleceniem. Tryb planowania, przygotowanie kontekstu i poziom effort decydują, jak do tego dojdzie.

Ta strona jest dla programistów, którzy codziennie pracują z Claude Code, i dla tech leadów, którzy chcą, żeby cały zespół pisał briefy w ten sam sposób. Wpisujesz „napraw błąd ponownego łączenia”, Claude edytuje trzy pliki, melduje sukces, a ty zostajesz z 200-liniowym diffem, żeby sprawdzić, czy to prawda. Rozwiązaniem nie jest dłuższy prompt. Jest nim prompt, który mówi, jak wygląda „gotowe”, dzięki czemu dowody przychodzą razem z diffem.

Co daje dobry brief dla Claude Code

• Czteroczęściowy brief (co, gdzie, dlaczego, kiedy gotowe), który działa przy poprawkach błędów, nowych funkcjach i refaktoryzacji.
• Warunki ukończenia, które zmuszają Claude do uruchomienia testu, który najpierw nie przechodzi, sprawdzenia typów albo polecenia, zanim zgłosi sukces.
• Trzy wzorce przygotowania kontekstu, dzięki którym Claude nie zgaduje, jak wygląda kod, którego nie przeczytał.
• Regułę, kiedy włączyć tryb planowania, kiedy podnieść poziom effort, a kiedy żadne z nich nie pomoże.
• Prompty do skopiowania: poprawka błędu, nowa funkcja, zestaw testów i przegląd własnego diffu Claude.
• Skill projektu /brief, który daje całemu zespołowi ten sam szablon.

Jak zbudować prompt dla Claude Code?

Porównaj dwie prośby o ten sam błąd. Pierwsza brzmi: „Napraw błąd WebSocketu”. Druga:

What: The WebSocket client stops reconnecting after the third failed attempt.
Where: src/realtime/socket.ts (reconnect logic) and src/realtime/__tests__/socket.test.ts.
Why: The backoff timer resets on partial connections, so mobile users on weak networks
never recover and have to reload the app.
Done when: a new test that simulates three failed reconnects fails on the current code,
passes after your fix, and `npm test -- socket` plus `npm run typecheck` both pass.
Show me the failing run and the passing run.

Drugi prompt odpowiada na cztery pytania, na które musi odpowiadać każdy brief dla Claude Code:

1. Co się zmienia — opisane jako zachowanie, a nie edycja („przestaje się łączyć”, a nie „zmień linię 80”).
2. Gdzie Claude ma zacząć. Nazwane pliki oszczędzają eksplorację i utrzymują zmianę w obszarze, którego się spodziewasz.
3. Dlaczego zmiana jest potrzebna. Powód pozwala Claude wybrać między poprawkami: „użytkownicy mobilni na słabych sieciach” wyklucza poprawkę, która działa tylko przy stabilnym połączeniu.
4. Kiedy gotowe — sprawdzenie, które dowodzi wykonania pracy. Claude Code uruchamia polecenia, więc sprawdzenie zapisane jako polecenie Claude wykona, zanim zamelduje wynik.

Czwarta część odróżnia promptowanie agenta od promptowania modelu czatowego. Bez niej Claude sam decyduje, kiedy skończył, a „skończył” często znaczy „kod się kompiluje”. Z nią dostajesz twierdzenie razem z wynikiem, który je potwierdza.

Prompt do skopiowania: czteroczęściowy brief dla dowolnej zmiany

What: [the behaviour that must change, in one or two sentences]
Where: [the files or directories to start from]
Why: [the user-facing problem or constraint behind the change]
Done when:
- a new test reproduces the problem and fails before your change
- the same test passes after your change
- `npm test` and `npm run typecheck` pass with no new warnings
Before you finish, list every command you ran and paste the last lines of each output.
Do not change files outside the Where list without asking me first.

Zastąp npm test i npm run typecheck poleceniami swojego projektu. Jeśli raz wpiszesz je do CLAUDE.md, brief może mówić „the checks in CLAUDE.md pass” i pozostać krótki. Co powinno trafić do tego pliku, opisuje strona o systemie pamięci.

Pisz warunki ukończenia, które Claude potrafi udowodnić

Warunek ukończenia ma sens, gdy Claude może go uruchomić, a ty możesz odczytać wynik w kilka sekund. Większość pracy pokrywają cztery formy:

Warunek	Przykład	Czego dowodzi
Najpierw czerwony, potem zielony	„Write the test first, run it, show it failing, then fix.”	Test rzeczywiście dotyka błędu, a nie tylko ścieżki szczęśliwej.
Nazwane polecenie	„npm run typecheck and npm run lint exit 0.”	Brak regresji typów i lintera w całym projekcie.
Obserwowalne zachowanie	„curl -i localhost:3000/api/users/abc%20def returns 400, not 500.”	Poprawka działa od początku do końca, nie tylko w teście jednostkowym.
Granica	„No file under src/generated/ changes. Show git diff --stat.”	Zmiana została tam, gdzie się jej spodziewasz.

Proś o dowody wprost („paste the last lines of each output”). Wtedy Claude raportuje, co uruchomił, a nie tylko to, w co wierzy. Warunek w rodzaju „upewnij się, że działa” albo „utrzymaj czysty kod” niczego nie dowodzi, bo Claude nie może go uruchomić, a ty nie możesz go sprawdzić.

Gdy kryteria akceptacji pochodzą z historyjki produktowej, a nie ze zgłoszenia błędu, zapisz je jako testy, zanim agent zacznie. Ten krok, niezależnie od narzędzia, opisuje strona o wykonywalnych kryteriach akceptacji.

Przygotuj kontekst, zanim zadasz pytanie

Claude Code czyta pliki na żądanie, ale czyta to, co sam uzna za istotne. Gdy odpowiedź zależy od konkretnego kodu, powiedz mu, co ma przeczytać najpierw.

Przeczytaj, potem odpowiedz

Read src/auth/middleware.ts, src/auth/jwt.ts, src/auth/session.ts and their tests.
Then tell me what would break if the access-token expiry changed from 1 hour to 15 minutes.
List each affected call site with its file and line. Do not edit anything yet.

Odpowiedź opiera się wtedy na kodzie na dysku, a nie na wyobrażeniach Claude o tym, jak zwykle wygląda kod uwierzytelniania. „Do not edit anything yet” sprawia, że to pozostaje pytaniem.

Pokaż przykład do naśladowania

Look at how src/api/routes/orders.ts handles errors: the try/catch shape, the
RFC 7807 error body, and the logger calls. Apply the same pattern to every handler
in src/api/routes/products.ts. Done when the products route tests pass and a
`grep -n "console.log" src/api/routes/products.ts` returns nothing.

Wskazanie istniejącego pliku jest dokładniejsze niż opisywanie konwencji słowami i utrzymuje nowy kod w zgodzie z kodem, który recenzent już zna.

Zacznij od ograniczeń

Constraints:
- Do not add dependencies to package.json.
- All database access goes through the Prisma client in src/lib/db.ts.
- Validate input with Zod, following src/api/routes/orders.ts.
- Do not touch src/generated/ (it is regenerated on build).

Task: add GET /api/v2/analytics that returns daily active users for a date range.
Done when: route tests cover an empty range, a range over 90 days (400), and a normal
range; `npm test` and `npm run typecheck` pass.

Ograniczenia na początku Claude czyta, zanim zacznie planować. Ograniczenia, które dotyczą każdego zadania, należą do CLAUDE.md, a nie do każdego promptu.

Prompt do skopiowania: nowa funkcja zgodna z konwencjami projektu

Before writing any code, read CLAUDE.md, src/api/routes/orders.ts and its test file.
Then add a PATCH /api/orders/:id/cancel endpoint that cancels an order only when its
status is "pending". Follow the orders route for validation, error format and logging.

Done when:
- tests cover: pending -> cancelled (200), shipped -> 409, unknown id -> 404, bad id -> 400
- each new test was run once before the handler existed and failed
- `npm test` and `npm run typecheck` pass
Report the commands you ran with their final output lines, plus `git status --short`
and `git diff --stat`.

Kiedy używać trybu planowania?

Tryb planowania to tryb uprawnień, w którym Claude czyta kod i proponuje plan, a edycje pozostają zablokowane, dopóki go nie zatwierdzisz. Włączysz go na trzy sposoby:

• Wpisz /plan, opcjonalnie z opisem zadania (/plan migrate sessions to JWT).
• Naciskaj Shift+Tab, aż wskaźnik trybu pokaże tryb planowania.
• Uruchom w nim sesję: claude --permission-mode plan.

Używaj trybu planowania, gdy liczy się kolejność zmian albo gdy odrzuciłbyś pracę przy złym podejściu: zmiany w więcej niż kilku plikach, migracje danych, wszystko, co dotyka uwierzytelniania lub płatności. Pomiń go przy poprawce w jednym pliku z jasnym testem, bo plan tylko powtórzyłby prompt.

Plan to miejsce, w którym twój przegląd daje najwięcej. Przeczytanie 20-liniowego planu trwa krócej niż przeczytanie diffu, który z niego powstanie, a złe podejście na tym etapie poprawiasz bez kosztów. Sprawdź, czy plan wymienia kroki weryfikacji; jeśli nie, poproś o nie przed zatwierdzeniem.

Prompt do skopiowania: plan ryzykownej zmiany przed jakąkolwiek edycją

/plan Move authentication from express-session (Redis store) to short-lived JWTs
with refresh tokens. Read src/auth/ and every route that reads req.session first.

The plan must include:
1. The order of changes, so that each step deploys on its own without logging users out.
2. How mobile app versions 2.3 and older, which only send session cookies, keep working.
3. How concurrent refresh requests from one client are handled.
4. For each step: the test or command that proves it, and how to roll it back.
List open questions for me at the end instead of guessing.

Szerszy proces planowania, w tym to, kiedy planować w osobnej sesji, opisuje strona o planowaniu funkcji w Claude Code.

Ile rozumowania powinien zamawiać prompt?

Poziom rozumowania (effort) określa, ile Claude rozumuje, zanim zacznie działać. Claude Code przyjmuje poziomy low, medium, high, xhigh i max (sprawdzone w claude --help, v2.1.283). Ustawisz go dla sesji poleceniem /effort, przy starcie przez claude --effort high albo w skryptach przez zmienną środowiskową CLAUDE_CODE_EFFORT_LEVEL. Domyślny model, Claude Opus 5.5, startuje z poziomem effort medium na kanale wydań latest; wartości domyślne dla innych modeli i kanałów znajdziesz w przeglądzie modeli.

Dla pojedynczej trudnej tury dodaj do promptu słowo ultrathink. W v2.1.283 dodaje ono jednorazową instrukcję dokładniejszego rozumowania i nie zmienia poziomu effort ustawionego dla sesji. „Think hard” i „think more” to zwykły tekst promptu bez specjalnego działania.

Podnoś poziom effort, gdy problem wymaga wieloetapowego rozumowania: współbieżność, analiza bezpieczeństwa, decyzja architektoniczna. Przy rutynowych edycjach zostań przy wartości domyślnej. Lepszy kontekst pomaga częściej niż wyższy poziom rozumowania. Jeśli odpowiedź Claude jest płytka, bo nie przeczytał właściwego kodu, wyższy poziom effort da tylko dłuższą błędną odpowiedź. Poziomy effort, ultracode i limity zespołowe opisuje w całości strona o dogłębnym rozumowaniu w Claude Code.

Prompt do skopiowania: jedna trudna tura analizy

ultrathink. We see duplicate charges when two payment confirmations for the same order
arrive within 50 ms. OrderService, PaymentService and InventoryService communicate
over Redis pub/sub. Read src/services/payment/ and src/events/ first.

Walk through the interleaving that produces a double charge, citing file and line
for each step. Then propose a fix, and a test that reproduces the race
deterministically. Do not edit code until I choose a fix.

Prompty do poprawek, testów i samodzielnego przeglądu

Każdy z poniższych promptów ma własny warunek ukończenia, więc wynik przychodzi z dowodami.

Prompt do skopiowania: poprawka błędu na podstawie reprodukcji

GET /api/users/abc%20def returns 500 with an unhandled Prisma error. It should return
400 with our standard validation error body.

1. Add a failing test in tests/api/users.test.ts that reproduces this. Run it and show the failure.
2. Fix input validation in src/api/routes/users.ts only.
3. Run the new test and the whole users suite, and show both passing.
If the root cause is outside users.ts, stop and explain before editing anything else.

Prompt do skopiowania: testy, które potrafią nie przejść

Read src/services/payment.service.ts and follow the structure and mocking style of
src/services/__tests__/order.service.test.ts.

Write tests for: a successful charge, a declined card, a provider timeout, a retry
that succeeds, and an amount of 0. For each test, name the bug it would catch.
Then prove the tests are not tautological: break one line in payment.service.ts,
run the suite, show which tests fail, and restore the line.

Ostatni krok tego promptu to tani test mutacyjny. Test, który nadal przechodzi po zepsuciu kodu, który sprawdza, niczego nie dowodzi, więc poproś Claude o pokazanie czerwonego przebiegu.

Prompt do skopiowania: przegląd diffu Claude, zanim zrobisz to ty

Review the uncommitted changes as a skeptical senior reviewer: run `git status`
and `git diff HEAD`, and read every untracked file in full.
For each finding give: file and line, the problem, severity (critical/high/medium/low),
and a concrete fix. Check error handling, input validation, and any behaviour change
not covered by a test. Skip formatting; our formatter handles it.
End with the list of behaviours this diff changes and the test that covers each one.
Mark any behaviour with no covering test as UNTESTED.

Jak sprawić, żeby cały zespół pisał briefy tak samo?

Szablon na wiki ktoś raz skopiuje, a potem każdy zmienia go po swojemu. Skill projektu jest częścią repozytorium, więc każdy, kto je sklonuje, dostaje to samo polecenie /brief. Zacommituj ten plik jako .claude/skills/brief/SKILL.md:

---
name: brief
description: Turn a one-line request into a four-part brief with a provable done-when clause.
argument-hint: <what should change>
disable-model-invocation: true
---

Treat this request as the "What" of a brief: $ARGUMENTS

Before editing anything:
1. Name the files you will start from (Where) and the user-facing reason (Why).
   If either is unclear from the code, ask me instead of guessing.
2. Write a done-when list: a test that fails before the change and passes after it,
   plus the test, type-check and lint commands listed in CLAUDE.md.
3. Show me the brief and wait for "go".

When you finish: list every command you ran with the last lines of its output,
show `git status --short` and `git diff --stat` (so new, untracked files count too),
and mark any changed behaviour that no test covers as UNTESTED.

Programista wpisuje wtedy /brief the WebSocket client stops reconnecting after three failures, a Claude uzupełnia Where, Why i Done when, zanim dotknie kodu. disable-model-invocation: true sprawia, że skill uruchamiasz tylko ręcznie, więc Claude nie zacznie sam rozpisywać briefu przy każdym drobnym pytaniu. Frontmatter skilli i ich argumenty opisuje w całości strona o własnych poleceniach.

Dla tech leada ten skill jest też standardem przeglądu. Pull request, w którego opisie nie ma przebiegu „najpierw czerwony, potem zielony” ani listy UNTESTED, nie przeszedł przez brief, a recenzent może go odesłać bez czytania diffu.

Jak zweryfikować wynik Claude bez czytania każdej linii?

Dobre promptowanie przenosi twój wysiłek recenzenta z diffu na dowody. Stosuj tę kolejność:

1. Zatwierdź intencję. Przy ryzykownej pracy przeczytaj i popraw plan w trybie planowania. To twój główny punkt przeglądu.
2. Wymagaj dowodów w raporcie. Warunek ukończenia sprawia, że Claude zwraca polecenia i ich wynik. Sprawdź, czy nieudany przebieg był przed udanym.
3. Uruchom bramkę sam albo w CI. Uruchom ponownie testy, sprawdzanie typów i linter albo zostaw to CI. Transkrypt Claude to twierdzenie; twoja bramka to dowód.
4. Zdobądź drugą opinię o diffie. Użyj promptu do samodzielnego przeglądu powyżej albo /code-review, żeby dostać ustrukturyzowany przegląd. Jak uruchamiać przeglądy przy każdym pull requeście, opisuje strona o automatyzacji przeglądów.
5. Czytaj listę UNTESTED, nie cały diff. Poświęć czas na zachowania, których nie pokrywa żaden test, i na pliki spoza listy Where.

Nadal to ty zatwierdzasz, ale plan, dowody i luki w testach, a nie każdą linię. Ten sposób pracy i to, kiedy można go bezpiecznie przyjąć, wyjaśnia strona Dowody zamiast diffów.

Co psuje się przy promptowaniu Claude Code i jak z tego wyjść?

Claude melduje sukces, ale testy nigdy nie zostały uruchomione. Prompt nie miał warunku ukończenia albo mówił „upewnij się, że działa”. Wyjście: odpisz „Run npm test now and paste the output” i dodaj linię o dowodach do swojego szablonu briefu.

Claude ignoruje ograniczenie w długiej sesji. Wczesne instrukcje konkurują ze wszystkim, co zostało przeczytane później. Wyjście: powtórz ograniczenie na początku następnego promptu. Ograniczenie, które dotyczy każdego zadania, przenieś do CLAUDE.md. Gdy sesja mocno odpłynęła, użyj /clear i zacznij od nowa z briefem.

Claude „naprawia” test zamiast kodu. Warunek „testy przechodzą” pozwala Claude osłabić asercję. Wyjście: dodaj „do not change existing assertions; if a test looks wrong, stop and tell me why”. Złą edycję cofniesz przez /rewind (albo dwukrotne Esc), wracając do ostatniego punktu kontrolnego.

Claude wymyśla kod, którego nie ma. Odpowiedział na podstawie założeń. Wyjście: popraw go faktem („the token is stored in Redis, see src/auth/session.ts line 45”) i poproś o przeczytanie pliku przed dalszą pracą. Następnym razem użyj wzorca „przeczytaj, potem odpowiedz”.

Tryb planowania i tak wprowadził zmiany. Sesja nie była w trybie planowania albo zatwierdziłeś plan. Wyjście: sprawdź wskaźnik trybu przed wysłaniem promptu albo zacznij od claude --permission-mode plan. Prośba „najpierw zaplanuj” w zwykłym trybie to prośba, a nie blokada.

Wyższy poziom effort nie poprawił odpowiedzi. Brakowało kontekstu albo sprawdzalnego celu, a nie rozumowania. Wyjście: wróć do domyślnego poziomu effort, dodaj pliki do przeczytania i warunek ukończenia, spróbuj ponownie.

Co dalej z promptowaniem w Claude Code

• System pamięci: wpisz polecenia testów i stałe ograniczenia do CLAUDE.md, żeby każdy brief mógł być krótki.
• Dogłębne rozumowanie w Claude Code: poziomy effort, ultracode i zespołowe limity poziomu effort.
• Planowanie funkcji: tryb planowania przy wieloetapowych funkcjach.
• Operacje wsadowe: jeden dobrze napisany brief zastosowany do wielu plików.
• Procesy debugowania: prompty do szukania przyczyn źródłowych.
• Skuteczne techniki promptowania: niezależne od narzędzia zasady, na których opiera się ta strona.
• Inżynieria promptów dla Codexa: ten sam brief dostosowany do Codexa.
• Szablony promptów w Cursorze: ta sama idea w postaci szablonów wielokrotnego użytku w Cursorze.
• Grill Me i Grill With Docs: pozwól agentowi przepytać cię, zanim napiszesz brief.