Context engineering: przestań za każdym razem tłumaczyć Claude swój projekt

Context to coś więcej niż prompt

Prompt jest tylko bieżącym poleceniem.

Context to wszystko, co model ma aktualnie dostępne przy podejmowaniu decyzji:

bieżące polecenie
+ wcześniejsza rozmowa
+ instrukcje projektu
+ przeczytane pliki
+ wyniki komend
+ wyniki tool calli
+ dokumentacja

To prowadzi do ważnej zmiany myślenia.

Nie pytamy już wyłącznie:

Jak napisać lepszy prompt?

Pytamy:

Jak sprawić, żeby Claude we właściwym momencie miał właściwe informacje?

To jest context engineering.

CLAUDE.md: README dla współpracownika, nie śmietnik na prompty

Najprostszy upgrade to CLAUDE.md.

Przykład:

# Architecture

- Business logic belongs in services.
- HTTP handlers only validate input and map responses.
- Database access goes through repositories.

# Verification

Run:

make test
make lint
make verify

Schema changes additionally require:

make test-integration

# Rules

- Never modify generated files manually.
- Every schema change requires a migration.
- Do not make production changes without explicit approval.

Nie chodzi o to, żeby wkleić tam wszystko, co wiesz o projekcie.

CLAUDE.md powinien zawierać przede wszystkim informacje:

• często potrzebne,
• stabilne,
• ważne dla wielu zadań,
• których pominięcie powoduje realne problemy.

Jeżeli masz 300 linii opisu konkretnego subsystemu, prawdopodobnie nie powinien być ładowany do każdego zadania.

Repozytorium też jest częścią context engineeringu

Dobre repo dla developera często jest również dobre dla agenta.

Porównaj:

"Żeby odpalić testy, wejdź do packages/api,
załaduj .env.dev, odpal kontener z bazą,
następnie wykonaj..."

z:

make test

Im bardziej deterministyczne są podstawowe entrypointy, tym mniej agent musi zgadywać.

Warto mieć jawne komendy typu:

make dev
make test
make lint
make verify

albo ich odpowiedniki w package.json, taskfile, justfile czy innym narzędziu używanym w projekcie.

To nie jest przygotowywanie repo "pod AI".

To po prostu dobre developer experience, z którego agent też korzysta.

Claude nie powinien mieć wszystkiego w context window

Naturalną reakcją po poznaniu CLAUDE.md jest dopisywanie kolejnych rzeczy.

Po kilku tygodniach może powstać:

CLAUDE.md
-> architektura
-> conventions
-> dokumentacja API
-> historia deploymentów
-> 15 runbooków
-> opis każdego modułu
-> wszystkie edge case'y

To zły kierunek.

Context window jest zasobem.

Duża ilość mało istotnych informacji utrudnia znalezienie tego, co ważne dla aktualnego zadania.

Lepiej myśleć warstwami:

CLAUDE.md
= wiedza potrzebna często

repo
= źródło prawdy o kodzie

docs/
= szczegółowa wiedza do odnalezienia

bieżące polecenie
= cel aktualnego zadania

tool results
= dynamiczne informacje zdobyte podczas pracy

Search i retrieval są częścią układanki

Jeśli Claude potrzebuje dowiedzieć się, jak działa konkretny moduł, często nie potrzebujesz żadnego specjalnego systemu RAG.

Może użyć:

• grep,
• glob,
• symbol search,
• git history,
• wyszukiwania po repo.

Dla kodu dokładne wyszukiwanie często jest lepsze niż semantic search.

Pytanie:

Gdzie używany jest PaymentService?

jest naturalnym kandydatem do grep/symbol search.

Nie ma powodu od razu budować vector DB.

Kiedy zaczyna mieć sens RAG?

Problem pojawia się, gdy wiedza żyje poza kodem albo jest jej bardzo dużo:

• ADR-y,
• wiki,
• runbooki,
• wcześniejsze incidenty,
• dokumentacja platformy,
• tickety,
• decyzje projektowe.

Wtedy potrzebujesz mechanizmu:

duży zbiór wiedzy
|
v
wyszukiwanie / retrieval
|
v
najbardziej relevant fragmenty
|
v
context Claude

To ogólna idea RAG: retrieval-augmented generation.

Nie trzeba zaczynać od embeddings.

W praktyce retrieval może łączyć:

• full-text search,
• filtrowanie po metadata,
• semantic/vector search,
• reranking.

Ważniejszy od konkretnej technologii jest wzorzec:

Nie wkładaj wszystkiego do contextu. Daj agentowi możliwość pobrania informacji wtedy, kiedy są potrzebne.

W następnym artykule pójdziemy krok dalej i pozwolimy Claude samodzielnie korzystać także z systemów spoza repo.

Co to zmienia w SDLC?

Implementacja feature

Claude zaczyna od:

1. przeczytania CLAUDE.md,
2. znalezienia podobnego kodu,
3. poznania odpowiednich testów,
4. wykonania zmiany,
5. uruchomienia zdefiniowanego verification.

Nie musisz za każdym razem wyliczać tych kroków.

Review

Reviewer może poznać:

• conventions,
• security constraints,
• Definition of Done,

bez ponownego tłumaczenia ich w promptcie.

Debugging

Claude może sam odnaleźć:

• miejsce implementacji,
• testy,
• git history,
• dokumentację subsystemu.

Context staje się elementem repo i środowiska, a nie jednorazową wiadomością developera.

Wdróż to dziś

1. Otwórz kilka ostatnich rozmów z Claude

Znajdź instrukcje, które powtarzały się więcej niż raz.

Na przykład:

• jak uruchamiamy testy,
• jak wygląda architektura,
• czego nie należy zmieniać,
• jak wygląda Definition of Done.

2. Utwórz lub uprość CLAUDE.md

Zacznij od maksymalnie kilkunastu naprawdę ważnych zasad.

Nie twórz encyklopedii.

3. Ujednolić podstawowe entrypointy

Claude powinien móc łatwo wykonać:

test
lint
verify

bez rekonstruowania procedury z README.

4. Oddziel wiedzę "zawsze" od wiedzy "czasem"

CLAUDE.md:

• zasady ogólne.

Dokumentacja:

• szczegóły konkretnych subsystemów.

Repo search:

• wiedza wynikająca bezpośrednio z kodu.

5. Powtórz wcześniejszy task w świeżej sesji

Nie rób onboardingu.

Sprawdź, czy Claude potrafi prawidłowo odnaleźć sposób pracy z samym repo + CLAUDE.md.

Level complete

Poziom jest zaliczony, jeśli możesz otworzyć świeżą sesję Claude Code i zlecić typowy task bez ponownego tłumaczenia:

• architektury,
• podstawowych conventions,
• sposobu testowania,
• Definition of Done.

Na kolejnym poziomie przestaniemy również ręcznie dostarczać Claude informacje z GitHuba, CI, dokumentacji i innych systemów używanych w SDLC.

Materiały

• Give Claude context: CLAUDE.md and better prompts
• Steering Claude Code: CLAUDE.md, skills, hooks, subagents and more
• Claude Code power user tips