Kompletny przewodnik po pisaniu promptów systemowych dla agentów — Lekcje z inżynierii wstecznej Claude Code

Zdekompilowałem prompt systemowy Claude Code, przestudiowałem kod źródłowy DeepAgents i zbudowałem własnego agenta AI od zera. Większość poradników o promptowaniu to zwykłe lanie wody.

W świecie AI mamy teraz do czynienia ze zbiorowym złudzeniem.

Każdy tutorial mówi ci, żebyś pisał system prompty tak, jakbyś rzucał zaklęcia — wystarczy znaleźć odpowiednią inkantację, a model będzie posłuszny. "Jesteś WYBITNIE UTALENTOWANYM senior inżynierem z 20-letnim doświadczeniem..." Brzmi znajomo?

Spędziłem ostatnie kilka miesięcy budując VibeCom, doradcę AI dla startupów, który przeprowadza głęboki research rynku i generuje analizy na poziomie funduszy VC. Po drodze zreversowałem system prompt z Claude Code, przekopałem się przez kod źródłowy middleware'u DeepAgents i przepaliłem więcej kredytów API, niż chciałbym przyznać. Największa lekcja? Większość rzeczy, o których ludzie myślą, że mają znaczenie w system promptach, nie ma go wcale. A o tych, które faktycznie mają znaczenie, prawie nikt nie mówi.

Ten post to kompletny playbook — nie 5-minutowy przegląd, ale wszystko, co chciałbym, żeby ktoś mi powiedział, zanim zacząłem. Zrób sobie kawę.

1. Filozofia designu: Zaufaj modelowi

"An agent is a model. Not a framework. Not a prompt chain." — shareAI-lab/learn-claude-code

Ta idea zmieniła dla mnie wszystko. LLM już wie, jak rozumować, planować i działać. Twój system prompt nie uczy go myśleć — on tworzy środowisko, w którym model ma pracować.

Pomyśl o tym jak o zatrudnianiu senior developera. Nie dajesz mu 20-punktowej checklisty do każdego zadania. Mówisz mu: tym jesteśmy, tu są nasze granice, tak wygląda dobrze wykonana robota. A potem schodzisz mu z drogi.

Twój system prompt ma dokładnie cztery zadania:

Powiedz mu, kim jest — rola i tożsamość
Powiedz mu, gdzie są ściany — ograniczenia bezpieczeństwa
Powiedz mu, jak wygląda dobra robota — standardy jakości
Daj mu narzędzia — możliwości i wiedza

To wszystko. Cała reszta to szum.

Mindset Środowiska Pracy (The Harness Mindset)

Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions

Twój system prompt to instrukcja obsługi tego środowiska (harness). Nie projektujesz sztywnego rurociągu (pipeline) — projektujesz środowisko, w którym model może autonomicznie wykonywać swoją najlepszą pracę.

Nie pisz system promptu jak schematu blokowego. Model sam zdecyduje o kolejności wykonywania zadań.

2. Struktura promptu i kolejność sekcji

Rekomendowany układ (Zreversowany z Claude Code v2.0.14)

┌─────────────────────────────────────────────┐
│ 1. Identity                                  │  ← Czytane jako pierwsze, kotwiczy zachowanie
│ 2. Security & Safety                         │  ← Znaczniki IMPORTANT, nie do negocjacji
│ 3. Tone & Style                              │  ← Kontroluje format wyjściowy
│ 4. Core Workflow                             │  ← Jak wykonywać pracę
│ 5. Tool Usage Policy                         │  ← Priorytety wyboru narzędzi
│ 6. Domain Knowledge                          │  ← Na żądanie, nie ładowane z góry
│ 7. Environment Info                          │  ← Kontekst runtime, wstrzykiwany dynamicznie
│ 8. Reminders                                 │  ← Przypomnienie kluczowych zasad
├─────────────────────────────────────────────┤
│ [Tool Definitions — system-injected]         │  ← Nieedytowalne, zazwyczaj bardzo długie
├─────────────────────────────────────────────┤
│ [User Message]                               │
└─────────────────────────────────────────────┘

Dlaczego ta kolejność ma znaczenie

LLM-y mają krzywą uwagi w kształcie litery U — zwracają największą uwagę na początek i koniec twojego promptu, a "odpływają" w środku. To zjawisko znane jako "Lost in the Middle" i jest dobrze udokumentowane.

Tożsamość + Bezpieczeństwo na samej górze: Model najpierw ustala rolę i granice (efekt pierwszeństwa).
Core Workflow w górnej części środka: Twoja najważniejsza sekcja — jak agent wykonuje swoją pracę.
Definicje narzędzi są wstrzykiwane przez system po twoim prompcie: Definicje narzędzi w Claude Code pożerają ~11,438 tokenów. Oznacza to, że twoja niestandardowa treść ląduje bliżej początku, niż mogłoby się wydawać — co pomaga w przestrzeganiu instrukcji.
Przypomnienia na samym dole: Wykorzystaj efekt świeżości (recency bias), aby wzmocnić kluczowe zasady.

3. Pisanie poszczególnych sekcji

3.1 Tożsamość (Identity) — Kim jest ten agent?

Cel: Zakotwiczenie roli modelu w 1-3 zdaniach.

You are Claude Code, Anthropic's official CLI for Claude.
You are an interactive agent that helps users with software engineering tasks.

Wskazówki:

Bądź zwięzły — max 1-3 zdania.
Nazwij rolę wprost (pomaga to modelowi odróżnić konteksty).
Określ główną odpowiedzialność ("pomaga w X"), a nie ogólnikowe "jesteś pomocnym asystentem".
Wspomnij o SDK/platformie, jeśli ma to zastosowanie ("zbudowany na Anthropic's Claude Agent SDK").

Antywzorce:

"Jesteś pomocnym, nieszkodliwym i uczciwym asystentem AI" — zbyt ogólne, brak zakotwiczenia roli.
Cały akapit historii postaci i lore — marnuje tokeny, model nie potrzebuje rozwoju postaci.

3.2 Bezpieczeństwo i Ograniczenia (Security & Safety) — Twarde granice

Cel: Ustanowienie nienaruszalnych ograniczeń behawioralnych.

IMPORTANT: Assist with defensive security tasks only.
Refuse to create, modify, or improve code that may be used maliciously.
IMPORTANT: You must NEVER generate or guess URLs for the user.

Wskazówki:

Używaj prefiksu IMPORTANT: — trening hierarchii instrukcji Claude'a nadaje temu dodatkową wagę.
Używaj absolutnego języka: NEVER, MUST NOT, Refuse to.
Określ zarówno to, co jest dozwolone, JAK I to, co jest zabronione (dwukierunkowe ograniczenia są jaśniejsze).
Umieść na samej górze, nie zakopuj w środku.
Powtórz kluczowe zasady bezpieczeństwa na końcu — Claude Code robi dokładnie to.

Dlaczego powtarzać? Efekt pierwszeństwa (początek) + Efekt świeżości (koniec) = podwójne wzmocnienie. Deklaracja bezpieczeństwa Claude Code pojawia się zarówno na początku, jak i na końcu promptu. Nie dlatego, że inżynierowie byli zapominalscy — dlatego, że rozumieją krzywą uwagi w kształcie litery U.

3.3 Ton i Styl (Tone & Style) — Kontrolowanie outputu

Cel: Kontrola formatu wyjściowego i głosu.

## Tone and style

- Your responses should be short and concise.
- Only use emojis if the user explicitly requests it.
- Use Github-flavored markdown for formatting.
- NEVER create files unless absolutely necessary.

Wskazówki:

Wymieniaj konkretne zachowania, a nie ogólnikowe "bądź profesjonalny".
Każda zasada powinna być testowalna (prawda/fałsz) ("krótko i zwięźle" vs. "postaraj się być zwięzły").
Uwzględnij wymagania dotyczące formatu wyjściowego (markdown? JSON? plain text?).
Uwzględnij, czego NIE robić — wiele problemów ze stylem dotyczy zakazywania konkretnych zachowań.

Perełka z Claude Code — Profesjonalny Obiektywizm:

Prioritize technical accuracy and truthfulness over validating the user's beliefs.
Focus on facts and problem-solving, providing direct, objective technical info
without any unnecessary superlatives, praise, or emotional validation.

Ten akapit jest kluczowy: blokuje tendencję modelu do potakiwania (sycophancy). Jeśli twój agent musi wydawać obiektywne osądy (code review, ewaluacja pomysłów, decyzje architektoniczne), absolutnie potrzebujesz podobnej klauzuli.

3.4 Core Workflow — Najważniejsza sekcja

Cel: Nauczenie modelu jak pracować — metodologia, a nie sztywne procedury.

To jest najtrudniejsza sekcja do dobrego napisania, ale daje największe efekty, gdy zrobisz to dobrze.

Główna zasada: dawaj zasady (principles), nie procedury.

Powiedz LLM-owi, jak wygląda dobry output i dlaczego jest dobry — pozwól mu samemu wymyślić, jak do niego dojść. Unikaj narzucania dokładnej liczby pól, sekwencji kroków czy formatów, chyba że output jest konsumowany przez maszyny na dalszym etapie.

Podejście Claude Code:

## Doing tasks

The user will primarily request software engineering tasks.
For these tasks the following steps are recommended:

- Use the TodoWrite tool to plan the task if required

Zwróć uwagę na słowo "recommended" (zalecane) — a nie "musisz wykonać dokładnie te kroki". Ten jeden wybór słowa daje modelowi przestrzeń do adaptacji.

Dobra definicja workflow:

1. Understand first — read existing code before modifying it
2. Plan first — break complex tasks into steps before executing
3. Minimal changes — only change what's necessary, don't "refactor while you're in there"
4. Verify — confirm your changes work (run tests, lint, etc.)

Każda zasada ma ukryte "dlaczego" — model potrafi zrozumieć intencję i zgeneralizować ją na nowe scenariusze.

Antywzorce:

Sztywna 20-krokowa procedura — model będzie wykonywał ją mechanicznie i zawiesi się przy nieoczekiwanym inpucie.
"Najpierw zrób A, potem B, potem C" — to jest łańcuch promptów (prompt chain), a nie prompt agenta.
Nadmierne instruowanie w rzeczach, w których LLM jest już dobry — marnowanie tokenów.

Nauczyłem się tego na własnych błędach przy VibeCom. Wczesne wersje miały 10-krokowy workflow badawczy. Model posłusznie wykonywał wszystkie 10 kroków, nawet gdy krok 3 już odpowiedział na pytanie użytkownika. Kiedy przeszedłem na zasady ("rób research, aż zbierzesz wystarczające dowody, a potem zsyntetyzuj"), jakość wzrosła, a koszty tokenów spadły.

Wyjątek: Kiedy output jest konsumowany przez maszyny (komunikacja między agentami, formaty odpowiedzi API), powinieneś zdefiniować ścisłe formaty. Zasady są dla zachowań; schematy są dla interfejsów.

3.5 Zasady korzystania z narzędzi (Tool Usage Policy) — Rozwiązywanie niejednoznaczności

Cel: Kiedy wiele narzędzi może zrobić to samo, powiedz modelowi, które preferować.

## Tool usage policy

- Use specialized tools instead of bash commands:
  - Read for reading files instead of cat/head/tail
  - Edit for editing instead of sed/awk
  - Grep for searching instead of grep/rg
- You can call multiple tools in a single response. If independent, call in parallel.
- Use the Task tool for file search to reduce context usage.

Wskazówki:

Używaj "instead of" (zamiast), aby wyrazić priorytet (A zamiast B).
Wyjaśnij dlaczego preferować dane narzędzia ("zapewnia lepsze UX", "zmniejsza zużycie kontekstu").
Zdefiniuj strategię zrównoleglania (niezależne → równolegle, zależne → sekwencyjnie).
Wypisz ograniczenia bezpieczeństwa dla użycia narzędzi (walidacja ścieżek, sprawdzanie uprawnień).

Kluczowa relacja między narzędziami a promptami:

Definicje narzędzi są zazwyczaj wstrzykiwane przez system i nie możesz ich bezpośrednio edytować. Definicje narzędzi w Claude Code to ~11,438 tokenów. Oznacza to:

Nie powtarzaj informacji, które już są w definicjach narzędzi.
Używaj system promptu do strategicznych wskazówek: kiedy użyć danego narzędzia, dlaczego preferować jedno nad drugim, ustalanie priorytetów.
Jakość definicji narzędzi bezpośrednio wpływa na skuteczność agenta — jeśli budujesz własnego agenta, zainwestuj czas w napisanie świetnych opisów narzędzi.

3.6 Wiedza domenowa (Domain Knowledge) — Ładuj na żądanie, nie z góry

Cel: Dostarczenie specjalistycznej wiedzy, której może brakować w danych treningowych modelu.

Kluczowa zasada: stopniowe ujawnianie (progressive disclosure), a nie zrzuty wiedzy.

❌ Wklejenie wszystkich 200 endpointów API do system promptu → eksplozja tokenów
✅ Daj modelowi narzędzie do wyszukiwania informacji → "Ładuj wiedzę, kiedy jej potrzebujesz"

Tę strategię dzieli system Skills w Claude Code i middleware Progressive Disclosure w DeepAgents. Oba ładują wiedzę na żądanie poprzez wywołania narzędzi, zamiast ładować wszystko z góry.

Podejścia do implementacji:

Umieść wskaźniki w system prompcie: "Użyj narzędzia get_api_docs, aby pobrać dokumentację w razie potrzeby".
Użyj CLAUDE.md / AGENTS.md dla kontekstu projektu — ładowane w runtime, nie hardkodowane.
Użyj Skills / SKILL.md do odkrywania możliwości — model widzi menu dostępnych umiejętności i pobiera pełne specyfikacje na żądanie.

3.7 Informacje o środowisku (Environment Info) — Kontekst Runtime

Cel: Danie modelowi świadomości środowiska, w którym jest uruchomiony.

<env>
Working directory: /Users/fengliu/Desktop/tfm/vibecom
Is directory a git repo: true
Platform: darwin
Today's date: 2026-03-21
</env>
You are powered by the model named Claude Opus 4.6.

Wskazówki:

Generuj dynamicznie, nigdy nie hardkoduj.
Uwzględnij: katalog roboczy, platformę, datę, nazwę modelu, status git.
Używaj ustrukturyzowanego formatu (tagi XML lub bloki kodu) dla łatwego parsowania.
Data ma znaczenie — model musi wiedzieć, kiedy jest "teraz", aby ocenić świeżość informacji.

3.8 Przypomnienia (Reminders) — Ostatnie wzmocnienie

Cel: Ponowne określenie najbardziej krytycznych zasad na końcu promptu.

Claude Code powtarza swoje ograniczenia bezpieczeństwa i wymóg TodoWrite na samym dole:

IMPORTANT: Assist with defensive security tasks only. [repeated]
IMPORTANT: Always use the TodoWrite tool to plan and track tasks. [repeated]

Wskazówki:

Powtórz tylko 2-3 najbardziej krytyczne zasady — nie duplikuj wszystkiego.
Wykorzystaj efekt świeżości — model silniej zapamiętuje ostatnie treści.
Najlepsi kandydaci: ograniczenia bezpieczeństwa, najczęściej łamane zasady, przypomnienia o core workflow.

4. Budżet tokenów i zarządzanie kontekstem

Referencja alokacji budżetu

Sekcja	Rekomendowane Tokeny	Uwagi
Tożsamość + Bezpieczeństwo	200-500	Zwięzłe, ale nie do negocjacji
Ton i Styl	300-800	Zasady muszą być konkretne, ale nie lej wody
Core Workflow	500-2,000	Najważniejsza sekcja, warta inwestycji
Zasady korzystania z narzędzi	300-1,000	Zależy od liczby narzędzi
Wiedza domenowa	0-1,000	Preferowane ładowanie na żądanie
Informacje o środowisku	100-300	Generowane dynamicznie
Przypomnienia	100-300	Powtarzaj tylko to, co niezbędne
Twoja suma	1,500-6,000
Definicje narzędzi (system)	5,000-15,000	Poza twoją kontrolą

Krzywa degradacji kontekstu

Testy społeczności (Reddit u/CodeMonke_) zmapowały rzeczywistą degradację przestrzegania instrukcji:

< 80K tokenów: Przestrzeganie promptu pozostaje stabilne.
80K - 120K tokenów: Podążanie za instrukcjami zaczyna degradować.
> 120K tokenów: Znacząca degradacja — model "zapomina" wczesne instrukcje.
> 180K tokenów: Poważna degradacja.

Twoje 200K okna kontekstowego ≠ 200K efektywnego kontekstu. Planuj z głową.

Strategie mitygacji:

Utrzymuj swój system prompt w ryzach (< 6,000 tokenów dla twojej części).
Używaj podsumowań do kompresji historii konwersacji (DeepAgents triggeruje się przy ~80K znaków).
Umieszczaj krytyczne zasady na obu końcach promptu (uwaga w kształcie litery U).
Wstrzykuj tagi <system-reminder> w trakcie konwersacji (więcej o tym w sekcji 8).

5. Zasady pisania

5.1 Dawaj zasady, nie procedury

❌ "Step 1: Read the file. Step 2: Find the bug. Step 3: Fix it. Step 4: Run tests."
✅ "Always understand existing code before modifying it. Verify your changes work."

Zasady można uogólnić. Procedury można tylko mechanicznie odtwarzać. Kiedy model napotyka sytuację, której nie przewidziałeś, zasady kierują go ku właściwej decyzji. Procedury nie.

Wyjątek: Kiedy output jest konsumowany przez maszyny (komunikacja między agentami, formaty API), definiuj ścisłe schematy.

5.2 Używaj absolutnego języka dla twardych ograniczeń

Siła	Język	Zastosowanie
Absolutny zakaz	`NEVER`, `MUST NOT`	Bezpieczeństwo, nieodwracalne operacje
Silny wymóg	`ALWAYS`, `MUST`	Zasady core workflow
Rekomendacja	`recommended`, `prefer`	Best practices z wyjątkami
Sugestia	`consider`, `you may`	Opcjonalne optymalizacje

Przykłady z Claude Code:

NEVER update the git config — absolutny zakaz
ALWAYS prefer editing an existing file — silne, ale istnieją wyjątki
The following steps are recommended — sugerowany workflow

5.3 Używaj przykładów zamiast wyjaśnień

## Code References

When referencing specific functions or pieces of code include
the pattern `file_path:line_number`.

<example>
user: Where are errors from the client handled?
assistant: Clients are marked as failed in the `connectToServer`
function in src/services/process.ts:712.
</example>

Jeden przykład uczy więcej niż 100 słów wyjaśnienia:

Modele uczą się wzorców z przykładów bardziej niezawodnie niż z abstrakcyjnych opisów.
Otaczaj tagami <example>, aby oddzielić je od zasad.
Podawaj zarówno pozytywne ("rób to"), jak i negatywne ("nie rób tego") przykłady.
Używaj prawdziwych, konkretnych przykładów — a nie placeholderów typu "foo/bar".

5.4 Ograniczenia dwukierunkowe

✅ "Use dedicated tools: Read for reading files, Edit for editing files."
✅ "Do NOT use bash for file operations (cat, head, tail, sed, awk)."

Mówienie tylko "rób to" → model nie wie, kiedy tego NIE robić. Mówienie tylko "nie rób tego" → model nie zna alternatywy. Dwukierunkowo → jasno i jednoznacznie.

5.5 Wyjaśniaj "dlaczego", nie tylko "co"

❌ "Don't use git commit --amend."
✅ "Avoid git commit --amend. ONLY use --amend when either
   (1) user explicitly requested amend OR
   (2) adding edits from pre-commit hook.
   Reason: amending may overwrite others' commits."

Wyjaśnienie dlaczego pozwala modelowi podejmować właściwe decyzje w przypadkach brzegowych (edge cases). Protokół bezpieczeństwa git w Claude Code to mistrzostwo — każda zasada implikuje swoje uzasadnienie.

5.6 Struktura ponad prozą

Nagłówki Markdown (##, ###) — modele rozpoznają hierarchię.
Listy punktowane zamiast akapitów — każda zasada testowalna niezależnie.
Tagi XML dla specjalnych treści: <example>, <env>, <system-reminder>.
Tabele do porównań i mapowań.
Nigdy nie wrzucaj nieustrukturyzowanego tekstu — ustrukturyzowane prompty konsekwentnie osiągają lepsze wyniki w testach przestrzegania instrukcji niż proza w języku naturalnym.

6. Antywzorce, które marnują twoje tokeny

Łańcuchy promptów w przebraniu agentów

"First call tool A to get data.
Then call tool B with the result.
Then format the output as JSON.
Then save to file."

To nie jest prompt agenta — to skrypt pipeline'u. Model wykona go mechanicznie i straci swoją zdolność do autonomicznego planowania.

Rozwiązanie: Powiedz modelowi, jaki jest cel i ograniczenia. Pozwól mu zdecydować o krokach.

Inżynieria pochlebstw

"You are an EXTREMELY TALENTED and INCREDIBLY EXPERIENCED
senior software engineer with 20 years of experience..."

Komplementy i superlatywy nie poprawiają jakości outputu. Model nie ma ego, które trzeba by pompować. Zachowaj te 15 tokenów na prawdziwą zasadę.

Zrzuty wiedzy (Knowledge Dumps)

"Here is the complete API documentation for our 200 endpoints..."

To pożera twoje okno kontekstowe i przyspiesza degradację kontekstu. Zastąp to ładowaniem na żądanie:

"Use the get_api_docs tool to retrieve API documentation when needed."

Powtarzanie opisów narzędzi

Jeśli definicja narzędzia już mówi "Narzędzie Read czyta plik z systemu plików", nie mów tego ponownie w system prompcie. Dodawaj tylko strategiczne wskazówki, których definicja narzędzia nie obejmuje — kiedy go użyć, dlaczego go preferować, ustalanie priorytetów.

Brak obsługi błędów

Bez wyraźnych wskazówek modele będą ponawiać nieudane wywołania narzędzi w nieskończonej pętli. Zawsze dodawaj:

"If a tool call is denied, do not re-attempt the exact same call.
Think about why it was denied and adjust your approach."

Ignorowanie degradacji okna kontekstowego

200K okna kontekstowego ≠ 200K efektywnego kontekstu. Testy w świecie rzeczywistym pokazują, że degradacja zaczyna się przy 80K. Potrzebujesz strategii podsumowywania.

7. Punkty wstrzykiwania i priorytety

Trzy metody kustomizacji w Claude Code

Metoda	Zastępuje	Umiejscowienie	Najlepsze do
Output Styles	Sekcje "Tone and style" + "Doing tasks"	Tuż przed definicjami narzędzi	Zmiany stylu interakcji
--append-system-prompt	Nic (addytywne)	Po output style, przed definicjami narzędzi	Dodawania konkretnych zachowań
--system-prompt	Cały system prompt	Zostawia definicje narzędzi + jedną linię tożsamości	Pełnej kustomizacji (opcja atomowa)

Jeśli używasz wielu: Output Style → Append Prompt → Tool Definitions

Hierarchia instrukcji

Claude jest specjalnie trenowany z hierarchią instrukcji:

1. User's explicit instructions (CLAUDE.md, direct requests)  ← Najwyższy priorytet
2. Custom system prompt additions                               ← Wysoki
3. Default system prompt                                        ← Średni
4. Tool definitions                                             ← Poziom referencyjny

Oznacza to, że:

Zasady z CLAUDE.md nadpisują domyślne zachowanie system promptu.
Bezpośrednie prośby użytkownika nadpisują wszystko.
Twój customowy prompt nadpisuje domyślny prompt.

Mechanizmy dynamicznego wstrzykiwania

<system-reminder> — wstrzykiwane do dowolnej wiadomości w trakcie konwersacji, aby przypomnieć modelowi o krytycznych zasadach.
CLAUDE.md / AGENTS.md — ładowane w runtime z plików, dołączane do system promptu.
Skills / SKILL.md — ładowane na żądanie przez wywołania narzędzi, zerowy ślad w system prompcie.

8. Wstrzykiwanie w trakcie konwersacji — Tajna broń

System prompt pojawia się tylko raz, na samym początku tablicy wiadomości. Ale LLM-y przyjmują pełną tablicę wiadomości (naprzemienne wiadomości user / assistant / tool) jako input, i możesz wstrzykiwać prompty również do wiadomości użytkownika i wyników narzędzi. Claude Code intensywnie korzysta z tej techniki na produkcji.

Dlaczego to jest konieczne

Walka z degradacją kontekstu. W miarę jak konwersacje stają się dłuższe, przestrzeganie instrukcji z system promptu przez model spada (zauważalne przy 80K+ tokenów). Wstrzykiwanie przypomnień w trakcie konwersacji = odświeżanie zasad poprzez efekt świeżości (recency bias).

Model mentalny:

System prompt = konstytucja (ustanowiona raz, długoterminowy autorytet)
Przypomnienia w wiadomościach użytkownika = notatki/okólniki (wysyłane okresowo, utrzymujące egzekwowanie prawa)

Trzy punkty wstrzykiwania w tablicy wiadomości

Messages Array:
┌─────────────────────────────────────┐
│ System Prompt                       │ ← Pojawia się raz, efekt pierwszeństwa
│   (identity, safety, workflow...)   │
├─────────────────────────────────────┤
│ User Message 1                      │
│ Assistant Message 1                 │
│ User Message 2 + <system-reminder>  │ ← Wstrzyknięcie w trakcie konwersacji
│ Assistant Message 2                 │
│ Tool Result + <system-reminder>     │ ← Można wstrzykiwać też do wyników narzędzi
│ ...                                 │
│ User Message N + <system-reminder>  │ ← Najnowsza wiadomość, najsilniejszy efekt świeżości
└─────────────────────────────────────┘

Lokalizacja	Zaleta	Wady
System prompt	Efekt pierwszeństwa, czytane jako pierwsze	Pojawia się raz, "zapominane" w długich konwersacjach
Wstrzyknięcie do User message	Efekt świeżości, okresowe odświeżanie	Każde wstrzyknięcie kosztuje tokeny
Wstrzyknięcie do Tool result	Najbardziej naturalny punkt wstrzyknięcia	Działa tylko wtedy, gdy wywoływane są narzędzia

Jak Claude Code faktycznie tego używa

Warunek wstępny — zadeklaruj tagi w system prompcie:

Tool results and user messages may include <system-reminder> tags.
<system-reminder> tags contain useful information and reminders.
They are automatically added by the system, and bear no direct
relation to the specific tool results or user messages in which they appear.

Ten krok jest krytyczny: mówi modelowi, że te tagi są wstrzykiwane przez system, a nie są wypowiedzią użytkownika.

Zastosowanie 1: Przypomnienia behawioralne (okresowe odświeżanie zasad)

<system-reminder>
The task tools haven't been used recently. If you're working on tasks
that would benefit from tracking progress, consider using TaskCreate...
</system-reminder>

Claude Code używa tego, aby przypomnieć modelowi o planowaniu za pomocą TodoWrite — ponieważ modele mają tendencję do "zapominania" o planowaniu i od razu zaczynają kodować.

Zastosowanie 2: Przełączanie trybów (Plan Mode)

<system-reminder>
Plan mode is active. The user indicated that they do not want you to
execute yet -- you MUST NOT make any edits, run any non-readonly tools,
or otherwise make any changes to the system.
</system-reminder>

Tryb planowania nie jest zaimplementowany w system prompcie. To tag wstrzykiwany do następnej wiadomości użytkownika. Pozwala to na dynamiczne przełączanie trybów bez modyfikowania system promptu. Genialne.

Zastosowanie 3: Powiadomienia o zmianach w plikach

<system-reminder>
Note: /path/to/file.ts was modified, either by the user or by a linter.
This change was intentional, so make sure to take it into account.
</system-reminder>

Kiedy zewnętrzny proces (linter, formatter, ręczna edycja) modyfikuje plik, system powiadamia model poprzez przypomnienie — zapobiegając decyzjom opartym na nieaktualnej zawartości plików.

Zastosowanie 4: Dynamiczny kontekst (daty, zasady projektu)

<system-reminder>
Today's date is 2026-03-21.
Current branch: dev
claudeMd: [CLAUDE.md content injected here]
</system-reminder>

Kontekst runtime (data, status git, zasady projektu) jest wstrzykiwany przez wiadomości użytkownika, a nie hardkodowany w system prompcie.

Wskazówki dotyczące pisania przypomnień

Otaczaj tagami XML (<system-reminder>) — model potrafi odróżnić wstrzyknięcie systemowe od wypowiedzi użytkownika.
Zadeklaruj tagi wcześniej w system prompcie — inaczej model może próbować odpowiadać na przypomnienie.
Nie wstrzykuj do każdej wiadomości — każde wstrzyknięcie kosztuje tokeny, wstrzykuj tylko wtedy, gdy to konieczne.
Bądź zwięzły — przypomnienie to nie drugi system prompt, tylko 1-2 krytyczne zasady.
Nie przecz system promptowi — przypomnienia uzupełniają i wzmacniają, nie nadpisują.
Używaj do dynamicznego przełączania — tryb planowania, tryb readonly, feature flagi.

Kiedy używać System Promptu vs. Przypomnienia w User Message

Scenariusz	System Prompt	Przypomnienie w User Message
Definicja roli	✅	❌
Ograniczenia bezpieczeństwa	✅ Pierwsza deklaracja	✅ Okresowe powtarzanie
Metodologia workflow	✅	❌
Przełączanie trybów (plan mode)	❌	✅
Powiadomienia o zmianach w plikach	❌	✅
Data / informacje o środowisku	✅ Wartość początkowa	✅ Zaktualizowana wartość
Korekta behawioralna	❌	✅
Przypomnienia o użyciu narzędzi	✅ Definicja zasady	✅ Bodźce do wykonania

9. Prompt Cache — Zaoszczędź 90% na powtarzających się tokenach

Prompt caching od Anthropic pozwala na cache'owanie statycznego prefiksu twojej tablicy wiadomości. Kiedy kolejne zapytania dzielą ten sam prefiks, trafiają w cache — oszczędzając pieniądze i redukując opóźnienia (latency).

Dla agentów ma to ogromne znaczenie: wysyłasz ponownie system prompt + definicje narzędzi przy każdym pojedynczym wywołaniu LLM w ramach konwersacji.

Kluczowe liczby

Metryka	Wartość
Koszt trafienia w cache (hit)	10% normalnej ceny (90% oszczędności)
Koszt zapisu do cache	125% normalnej ceny (25% premii za pierwszy zapis)
Cache TTL	5 minut (wygasa w przypadku braku zapytań)
Minimalna długość do cache'owania	1,024 tokeny (Claude 3.5+)
Granularność cache	Dopasowanie prefiksu — od początku do zaznaczonego breakpointu
Maksymalna liczba breakpointów	4

Jak to zmienia projektowanie promptów

Główna zasada: treści statyczne na początku, dynamiczne na końcu.

✅ Układ przyjazny dla cache:
  System prompt (statyczny)      ← Cache breakpoint 1
  Definicje narzędzi (statyczne) ← Cache breakpoint 2
  CLAUDE.md / zasady projektu    ← Cache breakpoint 3 (zmienia się rzadko)
  Historia konwersacji           ← Breakpoint 4 dla rolling window

❌ Układ niszczący cache:
  System prompt
  DYNAMICZNY TIMESTAMP           ← Zmienia się co request, wszystko po nim = cache miss
  Definicje narzędzi
  Historia konwersacji

Pułapka, przed którą nikt cię nie ostrzega: Jeśli umieścisz dynamiczny timestamp w środku swojego system promptu, wszystko po nim staje się chybieniem cache'u (cache miss). Przy. Każdym. Zapytaniu. Jeden timestamp w złym miejscu i płacisz pełną cenę za tysiące tokenów.

Użycie API

const response = await anthropic.messages.create({
  model: "claude-sonnet-4-6",
  system: [
    {
      type: "text",
      text: "You are a startup advisor...",
      cache_control: { type: "ephemeral" }  // ← oznacza cache breakpoint
    }
  ],
  messages: [...]
});

Strategia wielu breakpointów

Breakpoint 1: System prompt           ← Prawie nigdy się nie zmienia
Breakpoint 2: Definicje narzędzi      ← Prawie nigdy się nie zmieniają
Breakpoint 3: Zasady projektu / CLAUDE.md ← Zmieniają się rzadko
Breakpoint 4: Pierwsze N wiadomości z historii ← Cache typu rolling window

Nawet gdy historia konwersacji się zmienia, pierwsze 3 breakpointy nadal trafiają w cache. Konwersacja na 10 tur oszczędza około 40-60% na kosztach tokenów wejściowych.

Rekomendacje projektowe

Żadnych wartości dynamicznych o wysokiej częstotliwości zmian w system prompcie — data jest w porządku (zmienia się codziennie), precyzyjne timestampy już nie.
Umieszczaj dynamiczny kontekst (status git itp.) we wstrzyknięciach do wiadomości użytkownika — nie w system prompcie, inaczej zniszczysz cache.
Utrzymuj definicje narzędzi stabilnymi — nie dodawaj/usuwaj narzędzi dynamicznie w runtime.
Używaj rolling window dla historii konwersacji — cache'uj pierwsze N wiadomości, tylko najnowsza wiadomość będzie chybieniem cache'u.

10. Checklista

Po napisaniu swojego system promptu, przejrzyj go z tą checklistą:

Struktura

Tożsamość jest na samej górze?
Ograniczenia bezpieczeństwa oznaczone jako IMPORTANT i powtórzone na końcu?
Jasny podział na sekcje za pomocą nagłówków?
Przykłady otoczone tagami <example>?

Budżet tokenów

Twoja część < 6,000 tokenów?
Nie powtarzasz informacji, które już są w definicjach narzędzi?
Wiedza domenowa ładowana na żądanie, a nie pre-ładowana?
Brak rozwlekłego lore lub historii postaci?

Jakość zasad

Każda zasada jest testowalna (prawda/fałsz)?
Twarde ograniczenia używają absolutnego języka (NEVER/MUST)?
Miękkie sugestie używają języka rekomendacji (recommended/prefer)?
Krytyczne zasady wyjaśniają dlaczego, a nie tylko co?
Ograniczenia dwukierunkowe (rób to + nie rób tamtego)?

Zachowanie Agenta

Podane zasady (principles), a nie sztywne procedury krok po kroku?
Obsłużony scenariusz "odmowa wywołania narzędzia"?
Obsłużona strategia "napotkano przeszkodę" (nie ponawiaj siłowo)?
Strategia zarządzania kontekstem wdrożona (próg podsumowywania)?

Czego NIE robić

Żadnych pochlebstw ani przymiotników w stopniu najwyższym?
Żadnych zbędnych deklaracji "jesteś pomocnym AI"?
Nie napisane jako łańcuch promptów (prompt chain)?
Brak over-engineeringu (funkcje, o które nikt nie prosił)?

Gdybym zaczynał dzisiaj

Oto dokładnie, co bym zrobił:

Zacznij od tożsamości + bezpieczeństwa w pierwszych 3 linijkach. Dwa zdania o tym, kim jest agent. Twarde ograniczenia z NEVER/MUST. Powtórz zasady bezpieczeństwa na końcu.
Napisz swój core workflow jako zasady, nie kroki. Max 4-5 punktów. Używaj "recommended" i "prefer" dla miękkich zasad, "NEVER" i "MUST" dla twardych.
Zabudżetuj 1,500-6,000 tokenów na swoją część. Definicje narzędzi dodadzą kolejne 5,000-15,000. Jeśli przekraczasz 6K, prawdopodobnie zrzucasz wiedzę, która powinna być ładowana na żądanie.
Ustrukturyzuj wszystko. Nagłówki Markdown, listy punktowane, tagi XML dla przykładów. Ustrukturyzowany prompt za każdym razem wygrywa z prozą w języku naturalnym.
Wbuduj przypomnienia w trakcie konwersacji od pierwszego dnia. Zadeklaruj <system-reminder> w swoim system prompcie. Wstrzykuj przypomnienia dla krytycznych zasad, przełączania trybów i aktualizacji kontekstu.
Projektuj pod cache. Treści statyczne na początku, dynamiczne na końcu. Nigdy nie umieszczaj zmieniających się wartości w ciele system promptu.

Ironia tego wszystkiego? Najlepsze system prompty są krótkie. Niestandardowe instrukcje Claude Code (z wyłączeniem definicji narzędzi) są zaskakująco zwięzłe. Każda linijka zapracowała na swoje miejsce.

Kiedyś myślałem, że prompt engineering polega na znajdowaniu sprytnych sztuczek. Teraz uważam, że to kwestia dyscypliny — mówienia mniej, mówienia precyzyjnie i ufania, że model wymyśli resztę. Model jest mądrzejszy niż twój prompt. Projektuj środowisko, nie zachowanie.

Źródła

Źródło	Kluczowy wniosek
Claude Code v2.0.14 System Prompt	Pełna referencja struktury produkcyjnego promptu agenta
Reddit: Understanding Claude Code's 3 System Prompt Methods	Deep dive w Output Styles / --append / --system-prompt, rzeczywiste dane o degradacji kontekstu
shareAI-lab/learn-claude-code	Filozofia "Model to agent", metodologia inżynierii środowiska pracy (harness)
Anthropic Prompt Engineering Docs	Oficjalne best practices dla promptów
DeepAgents Framework	Middleware do podsumowywania, stopniowe ujawnianie umiejętności (skills progressive disclosure)