Inżynieria promptów dla Claude Code

„Napraw błąd” daje zupełnie inne rezultaty niż „Ponowne łączenie WebSocket w src/realtime/socket.ts zawodzi po trzeciej próbie, ponieważ timer backoff resetuje się przy częściowych połączeniach. Napraw logikę ponownych prób, aby używała wykładniczego backoff z jitterem, i dodaj test, który symuluje trzy nieudane próby ponownego połączenia.”

Różnica nie polega na gadatliwości. Chodzi o podanie Claude odpowiednich ograniczeń, kontekstu i kryteriów weryfikacji, aby uzyskać dokładnie to, czego potrzebujesz, za pierwszym razem.

Co z tego wyniesiesz

• Strukturalne ramy promptu, które działają dla każdego zadania
• Tryb planowania i poziomy wysiłku dla złożonych zmian w wielu plikach
• Techniki przygotowania kontekstu, które redukują halucynacje
• Prompty dla dziesięciu najczęstszych zadań programistycznych

Ramy promptu

Każdy skuteczny prompt dla Claude Code odpowiada na cztery pytania:

1. Co konkretnie musi się zmienić?
2. Gdzie w kodzie?
3. Dlaczego (ograniczenie lub wymaganie napędzające zmianę)?
4. Jak Claude powinien zweryfikować rezultat?

Co: Dodaj ograniczenie liczby żądań do endpointu /api/users
Gdzie: src/api/routes/users.ts i src/middleware/rate-limit.ts
Dlaczego: Dostajemy 10k żądań/minutę z jednego IP i baza danych jest przeciążona
Jak: Istniejący zestaw testów powinien przejść, a dodatkowo dodaj nowy test weryfikujący odpowiedzi 429 po 100 żądaniach/minutę

Wskazówka

Szablon promptu do skopiowania dla dowolnej zmiany kodu:

[WHAT]: [describe the specific change]
[WHERE]: [list specific files or directories]
[WHY]: [explain the constraint or problem]
[VERIFY]: [how to confirm the change works]

Additional context:
- [any relevant architecture decisions]
- [related files Claude should read first]
- [patterns to follow from existing code]

Tryb planowania

Naciskaj Shift+Tab, aby przełączać tryby uprawnień, dopóki nie dotrzesz do trybu planowania (cykl to tryb normalny, potem Auto-Accept, potem Plan; tryb Delegate dochodzi, gdy aktywny jest zespół agentów). W trybie planowania Claude analizuje kod i tworzy plan przed wprowadzeniem jakichkolwiek zmian. Jest to niezbędne dla:

• Zmian obejmujących więcej niż trzy pliki
• Refaktoryzacji, gdzie kolejność zmian ma znaczenie
• Zadań, gdzie nie jesteś pewien podejścia

[Shift+Tab to enable plan mode]

Refactor the authentication system from session-based to JWT. The current implementation
uses express-session with Redis storage across 12 route files. I need:

1. A migration plan that does not break existing sessions during deployment
2. Backward compatibility for the mobile app (version 2.3 and below uses session cookies)
3. Token refresh logic that handles concurrent requests

Read the current auth implementation in src/auth/ first, then create the plan.
Do not start implementing until I approve the plan.

Notatka

Tryb planowania różni się od proszenia Claude, aby „najpierw zaplanował”. Tryb planowania to przełącznik behawioralny, który uniemożliwia Claude wprowadzanie zmian do momentu zatwierdzenia. Samo proszenie Claude o zaplanowanie najpierw to sugestia, której może, ale nie musi, przestrzegać.

Rozszerzone myślenie i poziomy wysiłku

Rozszerzone myślenie jest teraz włączone domyślnie. W obecnych modelach (Fable 5, Opus 4.8, Sonnet 4.6) Claude stosuje adaptacyjne rozumowanie: dynamicznie przydziela, ile myśli przed odpowiedzią, skalując to według ustawionego przez ciebie poziomu wysiłku. Stara drabinka słów kluczowych („think”, potem „think hard”, potem „think harder”, potem „ultrathink”) nie kupuje już progresywnie większych budżetów myślenia — te frazy są teraz odczytywane jako zwykłe instrukcje w prompcie i nie przydzielają tokenów myślenia.

Trwałą dźwignią jest poziom wysiłku, a nie magiczne słowo:

• Ustaw wysiłek w /model — wybierz low, medium, high, xhigh lub max (high jest domyślne). To zalecany sposób strojenia kompromisu między szybkością a głębią dla całej sesji.
• CLAUDE_CODE_EFFORT_LEVEL — ustaw tę samą kontrolę przez zmienną środowiskową dla skryptów i uruchomień headless.
• Option+T (macOS) / Alt+T — włącz lub wyłącz myślenie dla bieżącej sesji.
• MAX_THINKING_TOKENS — ogranicz budżet myślenia dla modeli nieadaptacyjnych (jest ignorowany w Opus 4.8, chyba że ustawisz go na 0, co i tak wyłącza myślenie w dowolnym modelu).
• ultrathink nie jest już dźwignią. Frazy takie jak „think”, „think hard”, „ultrathink” i „think more” są teraz odczytywane jako zwykłe instrukcje w prompcie i nie przydzielają żadnych tokenów myślenia — czterostopniowa drabinka budżetów zniknęła. Zamiast nich używaj poziomu wysiłku lub przełącznika myślenia.

Gdy chcesz uzyskać maksymalne rozumowanie nad jednym trudnym problemem, podnieś poziom wysiłku, zamiast sięgać po słowo kluczowe:

Set effort to high in /model first, then:

Analyze the race condition in our payment processing pipeline. Three services
(OrderService, PaymentService, InventoryService) communicate via Redis pub/sub, and we are
seeing duplicate charges when two payment confirmations arrive within 50ms of each other.
Walk through the timing sequence and propose a solution using distributed locks.

Podnoś wysiłek, gdy problem wymaga wieloetapowego rozumowania, gdy widzisz płytką analizę, lub gdy zadanie obejmuje systemy współbieżne, analizę bezpieczeństwa lub decyzje architektoniczne. Zejdź z powrotem do low przy rutynowych edycjach, abyś nie płacił za rozumowanie, którego nie potrzebujesz.

Wskazówka

Prompt do skopiowania dla głębokiej analizy architektonicznej:

Set effort to high in /model, then think through the best approach for migrating
our monolith's user service into a standalone microservice. Current state:
- 47 files reference the User model directly
- 12 API endpoints depend on the users table
- Auth middleware reads from the users table on every request
- Test suite has 200+ tests that use user fixtures

Constraints:
- Zero downtime migration
- Must support rollback within 5 minutes
- Mobile app (v2.x) cannot be updated simultaneously

Przygotowanie kontekstu

Zanim poprosisz Claude o wprowadzenie zmian, przygotuj jego kontekst odpowiednimi informacjami:

Wzorzec czytaj-potem-działaj

Read src/auth/middleware.ts, src/auth/jwt.ts, and src/auth/session.ts.
Then read the test files for each.
Now tell me: what would break if I changed the token expiry from 1 hour to 15 minutes?

To jest bardziej skuteczne niż zadawanie pytania bezpośrednio, ponieważ Claude ma rzeczywisty kod w kontekście, a nie swoje założenia o tym, jak kod mógłby wyglądać.

Wzorzec pokaż-na-przykładzie

Look at how error handling works in src/api/routes/orders.ts.
Now apply the same error handling pattern to src/api/routes/products.ts.
Every endpoint should have the same try/catch structure, the same error response
format, and the same logging calls.

Wzorzec ograniczenia-najpierw

CONSTRAINTS:
- Do not modify any file in src/core/ (these are generated)
- Keep backward compatibility with the v1 API
- All new code must have 80%+ test coverage
- Use the existing Logger, not console.log

TASK: Add a new /api/v2/analytics endpoint that aggregates user activity data
from the events table.

Wskazówka

Prompt do skopiowania dla rozwoju sterowanego ograniczeniami:

Before you start, confirm you understand these constraints:
1. Do not add new dependencies to package.json
2. Follow the existing patterns in src/api/ for route structure
3. Use Zod for input validation (see existing routes for examples)
4. All database queries must go through the Prisma client in src/lib/db.ts
5. Error responses must follow our RFC 7807 format

Now: [your actual task here]

Prompty dla typowych zadań

Naprawa błędu

The /api/users/:id endpoint returns 500 when the user ID contains special characters.
Steps to reproduce: GET /api/users/abc%20def
Expected: 400 with validation error
Actual: 500 with unhandled Prisma error

Fix the input validation in src/api/routes/users.ts and add a test case for special characters in IDs.

Przegląd kodu

Review the changes in the current git diff (git diff HEAD). For each finding:
1. Explain the issue
2. Rate severity: CRITICAL / HIGH / MEDIUM / LOW
3. Suggest a specific fix with code

Focus on: error handling, type safety, and performance.
Skip: style issues (our formatter handles those).

Generowanie testów

Read src/services/payment.service.ts and generate a comprehensive test file.
Follow the patterns in src/services/__tests__/order.service.test.ts for:
- Test structure (describe/it blocks)
- Mocking approach (jest.mock for external services)
- Assertion style (expect().toEqual for objects, toBe for primitives)

Cover: happy path, validation errors, external service failures, and edge cases
(empty arrays, null values, maximum limits).

Gdy to nie działa

Claude ignoruje ograniczenia: Umieść ograniczenia na początku promptu, nie na końcu. Gdy kontekst staje się długi, koniec promptu otrzymuje mniej uwagi. Rozważ również dodanie krytycznych ograniczeń do pliku CLAUDE.md.

Tryb planowania nadal wprowadza zmiany: Upewnij się, że przełączyłeś tryb planowania za pomocą Shift+Tab (nie tylko poprosiłeś Claude o planowanie). Sprawdź wskaźnik statusu w REPL, aby potwierdzić, że tryb planowania jest aktywny.

Rozszerzone myślenie nie poprawia wyników: Nie każdy problem korzysta z głębokiego rozumowania. Proste edycje plików, zmiany formatowania i nieskomplikowane naprawy błędów działają dobrze przy niskim wysiłku. Podnoś poziom wysiłku (w /model) tylko dla problemów z wieloma współdziałającymi komponentami lub subtelnymi wymaganiami poprawności — i pamiętaj, że wpisanie „ultrathink” samo w sobie nie zwiększa już budżetu.

Claude źle rozumie kod: Przygotuj kontekst, kazując Claude najpierw przeczytać odpowiednie pliki. Jeśli źle rozumie, popraw to słowami „Nie, spójrz na linię 45 src/auth.ts — token jest przechowywany w Redis, nie w sesji.”

Co dalej

• Operacje wsadowe — Zastosuj swoje umiejętności promptowania do zmian na dużą skalę
• Przepływy debugowania — Prompty zaprojektowane specjalnie do znajdowania przyczyn źródłowych
• Optymalizacja CLAUDE.md — Zakoduj swoje wzorce promptowania w trwałej pamięci