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ć Manual → Accept Edits → Plan. Opcjonalne tryby Bypass i Auto dochodzą tylko po włączeniu; zespoły agentów nie zmieniają tego cyklu. 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. Obecne modele (Fable 5, Opus 5 i Sonnet 5) używają adaptacyjnego rozumowania: Claude dynamicznie przydziela, ile myśli, skalując to według ustawionego przez ciebie poziomu effort. Stara wielostopniowa drabinka słów kluczowych zniknęła. Claude Code rozpoznaje teraz tylko ultrathink jako wskazówkę głębszego rozumowania na jedną turę; dodaje instrukcję w kontekście i nie zmienia poziomu effort w API. „Think”, „think hard” i „think more” pozostają zwykłym tekstem promptu.

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

• Ustaw effort przez /effort lub w /model — wybierz low, medium, high, xhigh albo max. high jest domyślny na Fable 5, Sonnet 5 i Opus 5; Opus 4.7 domyślnie używa xhigh.
• 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 — dodatnie wartości ograniczają wyłącznie tryb stałego budżetu po ustawieniu CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1 na Opus/Sonnet 4.6. Zero wyłącza myślenie w pierwszostronnym Anthropic API z wyjątkiem Fable 5.
• ultrathink jest wskazówką na jedną turę. Użyj go dla pojedynczej trudnej tury bez zmiany effort sesji; nie gwarantuje ani nie rezerwuje stałej liczby tokenów myślenia.

Przy dłuższej trudnej pracy podnieś poziom effort. Dla jednej trudnej tury zachowaj ustawienie sesji i dodaj ultrathink:

Set effort to high in /model first (or add ultrathink for this turn), 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 działają dobrze przy niskim effort. Podnoś effort tylko przy współdziałających komponentach lub subtelnych wymaganiach poprawności. ultrathink dodaje instrukcję głębszego rozumowania na jedną turę, ale nie zmienia effort w API ani nie rezerwuje stałego 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
• Grill Me i Grill With Docs — Odwróć promptowanie: agent przepytuje ciebie, po jednym pytaniu naraz, zanim zaplanujesz