Inżynieria kontekstu to architektura: wnioski z 650 plików
Mój CLAUDE.md zaczynał od 50 linii. Sześć miesięcy później rozrósł się w rozproszoną architekturę 650 plików rozmieszczonych w siedmiu warstwach. Ta ewolucja pokazała, że inżynieria kontekstu to architektura oprogramowania dla substratu, w którym pamięć degraduje się z każdym tokenem, a nie inżynieria promptów z większą liczbą plików.
Kontekst określa, co agent AI może pomyśleć, co pamięta i co zapomina. Każda inna decyzja projektowa jest jego pochodną. Poniżej przedstawiam sześć miesięcy produkcyjnej inżynierii kontekstu dla Claude Code: architekturę, awarie i system, który je przetrwał.
Inżynieria kontekstu dla agentów AI to praktyka projektowania systemów, które dostarczają agentowi właściwe instrukcje we właściwym momencie, a jednocześnie gwarantują, że instrukcje nieistotne w ogóle się nie ładują. Wykracza ona daleko poza napisanie dobrego pliku z promptem: wymaga warstwowej architektury, w której reguły, umiejętności, hooki, konfiguracje i pliki stanu ładują się przy określonych zdarzeniach cyklu życia. To, co zostaje wykluczone, ma takie samo znaczenie jak to, co zostaje włączone, ponieważ każdy nieistotny token wypiera kontekst, którego agent faktycznie potrzebuje do poprawnego działania.
TL;DR
Artykuł Böckeler o inżynierii kontekstu (martinfowler.com, 2026)1 oraz framework jasnego myślenia Miesslera2 posuwają dyskusję naprzód, ale oba nie doceniają wymagań użycia produkcyjnego. Inżynieria kontekstu wymaga zaprojektowania systemu, w którym właściwe instrukcje docierają do agenta we właściwym momencie, a niewłaściwe instrukcje nigdy się nie ładują. Mój system wykorzystuje dziewięć reguł, 40 umiejętności, 19 agentów, 84 hooki i 14 plików konfiguracyjnych rozmieszczonych w siedmiowarstwowej hierarchii. Architektura tkwi w tym, które pliki ładują się kiedy. To, co zostaje wykluczone, ma takie samo znaczenie jak to, co zostaje włączone.
Kontekst to nie plik
Cotygodniowy post „jak napisać CLAUDE.md” nie trafia w sedno. Napisanie dobrego CLAUDE.md jest konieczne, ale niewystarczające, tak samo jak napisanie dobrego kodu jest konieczne, ale niewystarczające do zbudowania dobrego systemu. Architektura to struktura określająca, jak komponenty ze sobą współdziałają. W systemach agentowych kontekst jest tą strukturą.
To, co zaczęło się od 50 linii, urosło w monolit: mój pierwszy CLAUDE.md liczył 200 linii obejmujących standardy kodowania, strukturę projektu, preferencje, korekty, filozofię, dane uwierzytelniające i stan aktywnych projektów. Działał przez miesiąc. Potem jednocześnie wydarzyły się trzy rzeczy:
- Plik przekroczył 300 linii i zaczął przeczyć sam sobie (reguła A mówiła „uprość”, reguła B mówiła „dodaj dokładną obsługę błędów”)
- Kontekst z projektu A wyciekał do projektu B (reguły specyficzne dla iOS zanieczyszczały sesję tworzenia aplikacji webowej)
- Agent zużywał tokeny na czytanie instrukcji nieistotnych dla bieżącego zadania
Objawy wskazują na problemy architektoniczne, a nie dokumentacyjne: sprzężenie, wyciek zakresu i marnotrawstwo zasobów. Te same siły napędzają decyzje w architekturze oprogramowania.3
Siedem warstw
Po sześciu miesiącach refaktoryzacji mój system kontekstu ustabilizował się w siedmiowarstwowej hierarchii. Każda warstwa służy odrębnemu celowi i ładuje się w określonym momencie:
| Warstwa | Zawartość | Kiedy się ładuje | Liczba |
|---|---|---|---|
| 1. Rdzeń | CLAUDE.md: filozofia, aktywne projekty, korekty |
Przy starcie każdej sesji | Jeden plik, 205 linii |
| 2. Reguły | Ograniczenia domenowe (projektowanie API, bezpieczeństwo, testowanie, git) | Przy starcie każdej sesji | Dziewięć plików |
| 3. Umiejętności | Moduły wiedzy wielokrotnego użytku z procedurami i przykładami | Na żądanie (wywoływane lub aktywowane automatycznie przez hooki) | 40 katalogów |
| 4. Agenci | Wyspecjalizowane specyfikacje recenzentów i generatorów | Na żądanie (przez narzędzie Task) | 19 plików |
| 5. Hooki | Automatyczne wstrzykiwanie kontekstu przy zdarzeniach cyklu życia | Zdarzeniowo (start sesji, pre-commit, post-tool) | 84 skrypty |
| 6. Konfiguracja | Parametry liczbowe (progi, budżety, limity) | Przywoływana przez hooki i umiejętności | 14 plików JSON |
| 7. Stan | Śledzenie na żywo (rodowód agentów, kalibracja pewności, koszty) | Przywoływany przez hooki | 36 plików |
Kluczowe spostrzeżenie to separacja warstw. Reguły ładują się przy każdej sesji, ponieważ mają zastosowanie uniwersalne. Umiejętności ładują się na żądanie, ponieważ są domenowe. Hooki uruchamiają się przy zdarzeniach, ponieważ liczy się moment. Załadowanie wszystkich 650 plików przy starcie sesji wyczerpałoby okno kontekstu, zanim agent przeczytałby pierwszą wiadomość użytkownika.4
Konkretny przykład każdej warstwy:
Layer 1 (Core): ~/.claude/CLAUDE.md — philosophy, active projects, corrections
Layer 2 (Rules): ~/.claude/rules/security.md — "Validate ALL user input at boundaries"
Layer 3 (Skills): ~/.claude/skills/fastapi/SKILL.md — endpoint patterns, Pydantic models
Layer 4 (Agents): ~/.claude/agents/security-reviewer.md — OWASP-focused review spec
Layer 5 (Hooks): ~/.claude/hooks/pre-commit-check.sh — blocks commits with TODO/FIXME
Layer 6 (Config): ~/.claude/config/thresholds.json — {"max_spawn_children": 12}
Layer 7 (State): ~/.claude/state/agent-lineage.json — tracks active agent tree
Każdy plik w hierarchii ma jedną odpowiedzialność i jasny wyzwalacz ładowania. Hook (warstwa 5) uruchamia się przy pre-commit niezależnie od typu projektu. Umiejętność (warstwa 3) ładuje się dopiero wtedy, gdy zaczyna się zadanie związane z FastAPI. To rozróżnienie decyduje o koszcie w tokenach.
Trzy awarie, które ukształtowały architekturę
Awaria 1: Monolityczny CLAUDE.md
Mój pierwotny CLAUDE.md zawierał reguły iOS, reguły webowe, wzorce projektowania API, konwencje git, zarządzanie danymi uwierzytelniającymi i zasady filozoficzne, wszystko w jednym pliku. Agent czytał go w całości przy każdej sesji, nawet budując projekt webowy, który nigdy nie miał styczności ze SwiftUI.
Koszt: Nieistotny kontekst zużywał szacunkowo 4000 tokenów na sesję. W ciągu 50 sesji to łącznie około 200 000 tokenów wydanych na instrukcje, których agent nigdy nie użył.
Rozwiązanie: Przeniesienie treści domenowych do plików rules/. rules/security.md ładuje się przy każdej sesji (bezpieczeństwo dotyczy wszystkiego). rules/ios-security.md ładuje się tylko wtedy, gdy sesja dotyczy projektów iOS. Post o zarządzaniu oknem kontekstu dokumentuje ekonomię tokenów, która stała za tą decyzją.
Awaria 2: Umiejętności, które się zdezaktualizowały
Stworzyłem umiejętność fastapi z przykładami z FastAPI 0.109. Trzy miesiące później projekt używał FastAPI 0.115 z innymi wzorcami. Umiejętność po cichu uczyła przestarzałych konwencji. Agent generował działający kod, który nie pasował do aktualnej bazy kodu.
Koszt: 45-minutowe debugowanie w poszukiwaniu przyczyny, dla której nowy endpoint używał innego wzorca wstrzykiwania zależności niż wszystkie pozostałe endpointy. Wzorzec pochodził z przestarzałej umiejętności, a nie z bazy kodu.
Rozwiązanie: Umiejętności odwołują się do wersjonowanej dokumentacji i zawierają daty „ostatniej weryfikacji”. Co ważniejsze, pętla jakości wymaga, by generowany kod odpowiadał istniejącym wzorcom bazy kodu. To metapoznawcza kontrola, która wyłapuje dryf przestarzałych umiejętności niezależnie od ich treści.
Awaria 3: Sprzeczne reguły na różnych warstwach
CLAUDE.md mówił „preferuj proste rozwiązania”. Umiejętność mówiła „dodaj dokładną obsługę błędów z logiką ponownych prób i wyłącznikami awaryjnymi”. Każda z tych instrukcji z osobna była rozsądna. Razem dawały niespójne wyniki (czasem minimalistyczne, czasem przekombinowane), zależnie od tego, której instrukcji agent nadał większą wagę w danej turze.
Koszt: Nieprzewidywalna jakość wyników. Ten sam typ zadania dawał różne poziomy jakości w różnych sesjach, co czyniło system zawodnym. Oto faktycznie sprzeczne instrukcje:
# In CLAUDE.md (Layer 1):
- Prefer simple solutions. Avoid over-engineering.
# In skills/fastapi/SKILL.md (Layer 3):
- Add thorough error handling with retry logic and circuit breakers
for all external API calls.
Z osobna obie są poprawne. „Preferuj proste rozwiązania” to dobra rada ogólna. „Dodaj logikę ponownych prób dla wywołań zewnętrznych” to dobra rada domenowa. Agent, który czyta obie, czasem jednak pominie logikę ponownych prób (kierując się zasadą prostoty), a czasem przekombinuje prostą funkcję (kierując się instrukcją dotyczącą obsługi błędów).
Rozwiązanie: Ustanowienie jasnej hierarchii pierwszeństwa. CLAUDE.md określa zasady („preferuj prostotę”). Reguły określają ograniczenia („waliduj wszystkie dane wejściowe użytkownika”). Umiejętności określają procedury („oto jak zbudować endpoint FastAPI”). Gdy dochodzi do konfliktu, wygrywa warstwa bardziej szczegółowa: procedura umiejętności nadpisuje wskazówkę wynikającą z zasady w konkretnym zadaniu, które ta umiejętność obejmuje. Takie rozstrzygnięcie odzwierciedla sposób, w jaki języki programowania obsługują zakres: lokalny nadpisuje globalny.5 Poprawka dla powyższego przykładu polega na dodaniu do umiejętności zastrzeżenia: „Dodaj logikę ponownych prób dla zewnętrznych wywołań API (to nadpisuje ogólną zasadę prostoty w kodzie zależnym od sieci, ponieważ wywołania zewnętrzne zawodzą sporadycznie, a ponowne próby nie są przekombinowaniem).”
Budżet kontekstu jako ograniczenie architektoniczne
Okno kontekstu nie jest nieskończone. Standardowe okno kontekstu Claude o pojemności 200 tysięcy tokenów6 brzmi imponująco, dopóki nie zmierzy się, co je zużywa. (Przez nagłówek API dostępna jest wersja beta z 1 milionem tokenów, która proporcjonalnie powiększa budżet, ale nie usuwa kompromisów: załadowanie 650 plików wyczerpałoby nawet milion tokenów.)
| Konsument | Typowa liczba tokenów | % okna |
|---|---|---|
| Prompt systemowy + CLAUDE.md + reguły | 8000-12 000 | 4-6% |
| Historia konwersacji | 20 000-80 000 | 10-40% |
| Odczyty plików (na plik) | 5000-20 000 | 2,5-10% |
| Wyniki narzędzi (na wywołanie) | 1000-10 000 | 0,5-5% |
| Kontekst umiejętności/agenta (na żądanie) | 3000-15 000 | 1,5-7,5% |
Pomiary zużycia tokenów pochodzą z 50 sesji Claude Code, które śledziłem od sierpnia 2025 do lutego 2026.7 Intensywna 90-minutowa sesja może wyczerpać okno samymi zwykłymi odczytami plików i interakcjami z narzędziami. Warto zauważyć, że 200 tysięcy tokenów to całkowita pojemność wejścia; efektywna uwaga modelu, czyli ta część, którą obejmuje z wysoką wiernością, to inna, mniejsza liczba. Dyscyplina budżetu kontekstu ma znaczenie nawet wtedy, gdy całkowite zużycie tokenów jest daleko poniżej limitu, ponieważ instrukcje na początku długiego kontekstu otrzymują bardziej niezawodną uwagę niż instrukcje w jego środku. Budżet kontekstu wymusza kompromisy architektoniczne:
Ładować zawsze: podstawową filozofię, aktywne korekty i reguły bezpieczeństwa. Wszystkie trzy są tanie (4-6% budżetu) i mają uniwersalne zastosowanie. Koszt ich załadowania, gdy nie są potrzebne, jest znikomy. Koszt ich pominięcia, gdy są potrzebne, to błędny wynik.
Ładować na żądanie: umiejętności, specyfikacje agentów i dokumentację referencyjną. Każda umiejętność kosztuje 5-15% okna i dotyczy jednej domeny. Ładowanie ich tylko wtedy, gdy są istotne, chroni budżet na właściwą pracę. Wyzwalaczem załadowania umiejętności jest typ zadania, a nie typ sesji: sesja tworzenia aplikacji webowej, która natrafi na migrację bazy danych, potrzebuje umiejętności bazodanowej, nawet jeśli nie została ona załadowana przy starcie.
Nigdy nie ładować: przestarzałych dokumentów przekazania, wycofanych konfiguracji ani historycznego stanu. Każdy przestarzały plik zużywa budżet, nie poprawiając wyników. Co gorsza, przestarzały kontekst aktywnie pogarsza wyniki, ucząc nieaktualnych wzorców. Wzorzec kumulującej się inżynierii wymaga okresowego przycinania kontekstu, który nie zarabia już na swój koszt w tokenach.
Budżetowanie kontekstu odzwierciedla kompromis, który w tradycyjnym oprogramowaniu napędza indeksowanie baz danych, strategie cache’owania i zarządzanie pamięcią.8 Ograniczenie jest inne (tokeny zamiast bajtów), ale dyscyplina architektoniczna pozostaje identyczna.
Propagacja kontekstu w systemach wieloagentowych
Gdy główny agent uruchamia subagenta przez narzędzie Task, wybór kontekstu do propagacji determinuje wszystkie pozostałe decyzje projektowe. Mój system wieloagentowej deliberacji używa 10 agentów badawczych. Każdy agent potrzebuje dość kontekstu, by oceniać niezależnie, ale zbyt dużo współdzielonego kontekstu powoduje problem konwergencji opisany w poście o boidach: agenci współdzielący zbyt dużo kontekstu dochodzą do identycznych wniosków.
Reguły propagacji:
| Typ kontekstu | Propagowany? | Dlaczego |
|---|---|---|
| Podstawowa filozofia | Tak | Spójność między agentami |
| Reguły domenowe | Tak | Wspólne standardy jakości |
| Instrukcje specyficzne dla zadania | Tak | Właściwa praca |
| Historia konwersacji | Nie | Niezależność wymaga izolacji |
| Ustalenia innych agentów | Nie (do etapu syntezy) | Zapobiega przedwczesnej konwergencji |
| Procedury umiejętności | Selektywnie | Tylko umiejętności istotne dla roli agenta |
Architektura Ralph rozwiązuje pokrewny problem: propagację kontekstu w czasie (między iteracjami), a nie między agentami (procesami równoległymi). Oba podejścia łączy ta sama zasada: propagować ograniczenia i zasady, izolować szczegóły implementacyjne.
Propagacja w praktyce
Konkretny przykład dobrze ilustruje ten kompromis. Gdy główny agent uruchamia subagenta recenzenta bezpieczeństwa, prompt dla Task zawiera:
## Propagated Context
- Core philosophy: Quality is the only variable (from CLAUDE.md)
- Security rules: OWASP Top 10, input validation at boundaries (from rules/security.md)
- Task: Review the authentication endpoint changes in app/auth.py
## NOT Propagated
- The main agent's conversation history (50+ messages about UI layout)
- Findings from the architecture reviewer (would bias security analysis)
- The FastAPI skill (irrelevant to a security-focused review)
Recenzent bezpieczeństwa otrzymuje 2000 tokenów kontekstu zamiast 40 000. Ocenia kod pod kątem kryteriów bezpieczeństwa, nie rozpraszając się decyzjami dotyczącymi UI ani nie ulegając wnioskom innego agenta. Izolacja daje niezależną ocenę. Jeśli recenzent bezpieczeństwa i recenzent architektury niezależnie wskażą ten sam problem, ustalenie jest bardziej wiarygodne, niż gdyby jeden z nich zobaczył raport drugiego i się z nim zgodził.
Pomiar jakości kontekstu
Liczba tokenów to metryka zastępcza. Prawdziwa miara jakości kontekstu brzmi: czy agent daje poprawny wynik za pierwszym podejściem?
Po śledzeniu 50 sesji wyodrębniłem trzy sygnały jakości:
Wskaźnik sukcesu przy pierwszej próbie. Jak często pierwsza odpowiedź agenta nie wymaga korekty? Przy monolitycznym CLAUDE.md wskaźnik wynosił mniej więcej 60%. Po wdrożeniu siedmiowarstwowej architektury wzrósł do około 80%. Poprawa wynikała z usunięcia nieistotnego kontekstu (mniej rozpraszaczy) i dodania umiejętności domenowych (więcej trafnej wiedzy).9
Oto reprezentatywne porównanie przed i po z dziennika pomiarów. Zadanie jest identyczne: „dodaj ograniczanie liczby żądań (rate limiting) do endpointu API”.
Przed (monolityczny CLAUDE.md, lipiec 2025). Pierwsza odpowiedź agenta importowała bibliotekę do ograniczania liczby żądań, której projekt nie używał (agent poszedł za przykładem z przestarzałej umiejętności FastAPI, załadowanej razem z regułami iOS, regułami bezpieczeństwa i 150 liniami niezwiązanej treści). Korekta: „użyj istniejącej klasy RateLimiter w app/middleware.py”. Jedna korekta, sklasyfikowana jako „błąd faktograficzny: brak kontekstu bazy kodu”.
Po (architektura siedmiowarstwowa, listopad 2025). Ten sam typ zadania, inny endpoint. Pierwsza odpowiedź agenta użyła istniejącego middleware RateLimiter, zachowała konwencję nazewnictwa parametrów z sąsiednich endpointów i wskazała źródło wzorca: „zgodnie ze wzorcem ograniczania liczby żądań w app/middleware.py:42”. Korekta nie była potrzebna. Umiejętność FastAPI (warstwa 3) załadowała się na żądanie i zawierała aktualne wzorce; reguły iOS się nie załadowały, ponieważ sesja nie dotyczyła iOS.
Aby śledzić to samodzielnie, wystarczy oznaczać w dzienniku każdą sesję agenta etykietą „zaakceptowano” lub „poprawiono” po pierwszej odpowiedzi, a następnie co miesiąc liczyć proporcję. Szczegółowość nie musi być duża: kierunkowe trendy z ponad 20 sesji są bardziej przydatne niż dokładne wartości procentowe.
Typ korekty. Gdy agent wymaga korekty, czy błąd jest faktograficzny (złe API, zły wzorzec), czy dotyczy oceny (złe podejście, złe priorytety)? Błędy faktograficzne wskazują na brakujący kontekst: agentowi zabrakło informacji potrzebnych do udzielenia poprawnej odpowiedzi. Błędy oceny wskazują na sprzeczny lub niejednoznaczny kontekst: agent miał informacje, ale źle wyważył konkurujące instrukcje. To rozróżnienie ma znaczenie, ponieważ naprawa wygląda inaczej: błędy faktograficzne wymagają dodania kontekstu (nowej reguły lub umiejętności), a błędy oceny wymagają doprecyzowania kontekstu (rozstrzygnięcia konfliktu między istniejącymi warstwami). Śledzenie typów korekt pokazuje, która warstwa wymaga uwagi.
Presja kontekstu przy zakończeniu zadania. Ile budżetu kontekstu zostaje, gdy zadanie się kończy? Jeśli okno jest zapełnione w 90%, zanim zadanie jest w połowie, architektura kontekstu ładuje zbyt dużo nieistotnego materiału. Mój system hooków zawiera monitor presji kontekstu, który ostrzega, gdy wykorzystanie przekracza 70%.
Przebieg sesji: co ładuje się kiedy
Konkretny przebieg pokazuje, jak siedem warstw współdziała podczas prawdziwego zadania. Scenariusz: proszę Claude Code, by w projekcie blakecrosley.com „dodał ograniczanie liczby żądań do endpointu /api/ab/event”.
Start sesji (0 s). Claude Code ładuje warstwę 1 (CLAUDE.md, 205 linii, około 800 tokenów) i warstwę 2 (wszystkie 9 plików reguł, około 3200 tokenów). Łącznie zużyty kontekst: około 4000 tokenów (2% okna 200 tysięcy). Agent zna już moją filozofię kodowania, wymagania bezpieczeństwa, konwencje projektowania API i przepływ pracy w git, niezależnie od tego, o co go poproszę.
Początek zadania (2 s). Agent czyta zadanie i rozpoznaje je jako modyfikację endpointu FastAPI. Uruchamia się warstwa 5 (hooki): hook UserPromptSubmit wstrzykuje bieżącą datę i kontekst sesji (około 200 tokenów). Agent nie ładuje umiejętności SwiftUI, reguł bezpieczeństwa iOS ani umiejętności do promptów Midjourney. Te pliki istnieją, ale są nieistotne. Ich wykluczenie oszczędza około 8000 tokenów.
Odczyty plików (5-30 s). Agent czyta app/main.py, istniejący kod endpointu i plik testów. Każdy odczyt pliku zużywa 5000-15 000 tokenów kontekstu. Po przeczytaniu trzech plików zużyte jest około 30 000-50 000 tokenów (15-25% okna).
Aktywacja umiejętności (w razie potrzeby). Jeśli agent potrzebuje wzorców specyficznych dla FastAPI, ładuje warstwę 3 (skills/fastapi/SKILL.md, około 2500 tokenów). Umiejętność ładuje się, ponieważ wymaga jej zadanie, a nie dlatego, że rozpoczęła się sesja. Gdyby było to zadanie wyłącznie w CSS, umiejętność FastAPI nigdy by się nie załadowała.
Implementacja i weryfikacja (30 s-5 min). Agent pisze kod, uruchamia testy i raportuje wyniki. W chwili ukończenia zadania zużycie kontekstu wynosi zwykle 60 000-100 000 tokenów (30-50% okna). Pozostały budżet wystarcza na dodatkowe pytania, korekty lub drugie zadanie w tej samej sesji.
Kluczowa obserwacja: warstwy 1 i 2 zużywają 2% okna i dotyczą każdego zadania. Treści z warstw 3-7 ładują się selektywnie i zużywają 5-25% tylko wtedy, gdy są istotne. Gdyby wszystkie 650 plików załadowało się przy starcie sesji, zużyłoby około 150 000-200 000 tokenów, nie zostawiając prawie miejsca na właściwą pracę.
Wzorzec architektury rozproszonej
Nic w systemie siedmiu warstw nie jest unikalne dla agentów AI. Odzwierciedla on ugruntowane wzorce oprogramowania:
| Wzorzec oprogramowania | Odpowiednik w kontekście |
|---|---|
| Zmienne środowiskowe | Rdzeń CLAUDE.md (zawsze załadowany, globalny) |
| Pliki konfiguracyjne | Reguły (ładowane przy starcie, domenowe) |
| Biblioteki/moduły | Umiejętności (ładowane na żądanie, samodzielne) |
| Mikroserwisy | Agenci (izolowani, komunikujący się przez protokoły) |
| Handlery zdarzeń | Hooki (wyzwalane przez zdarzenia cyklu życia) |
| Baza danych | Pliki stanu (trwałe, odpytywalne) |
| Kontrakty API | Schematy konfiguracji (współdzielone parametry liczbowe) |
Ta paralela nie jest metaforą. Te same siły (sprzężenie, spójność, zakres, cykl życia) prowadzą do identycznych decyzji architektonicznych.10 Inżynieria kontekstu to inżynieria oprogramowania dla substratu, w którym „pamięć” jest zasobem rzadkim i podatnym na degradację, a nie obfitym i trwałym.11
Niezależne potwierdzenie tej architektury przynosi projekt obra/superpowers, który samodzielnie wypracował podobną wielowarstwową strukturę kontekstu dla Claude Code: podstawowe zasady w pliku globalnym, umiejętności domenowe ładowane na żądanie oraz procedury weryfikacji oddzielone od instrukcji behawioralnych.12 Ta zbieżność sugeruje, że architektura warstwowa nie jest osobliwym wyborem projektowym, lecz naturalną odpowiedzią na ograniczenia substratu.
Kluczowe wnioski
Dla inżynierów budujących systemy agentowe:
-
Kontekst należy projektować jak architekturę oprogramowania, a nie jak dokumentację. To, co ładuje się kiedy, co nadpisuje co i co propaguje się do subagentów, determinuje zachowanie agenta bardziej niż jakakolwiek pojedyncza instrukcja. Warto stosować tę samą dyscyplinę separacji odpowiedzialności, która obowiązuje w kodzie.
-
Warstwy należy rozdzielać według cyklu życia. Uniwersalne reguły ładują się przy każdej sesji. Wiedza domenowa ładuje się na żądanie. Stan sesji pozostaje przejściowy. Mieszanie cykli życia w jednym pliku tworzy problemy ze sprzężeniem, do których rozwiązywania istnieje architektura oprogramowania.
Dla zespołów skalujących przepływy pracy AI:
-
Okno kontekstu warto traktować jak budżet. Prompty systemowe, odczyty plików i wyniki narzędzi zużywają okno 200 tysięcy tokenów. Każda trwała instrukcja konkuruje z pamięcią roboczą. Należy mierzyć to, co się ładuje, i przycinać to, co nie zarabia na swoje tokeny.
-
Reguły propagacji determinują jakość systemów wieloagentowych. Subagenci potrzebują wspólnych zasad dla spójności i izolowanego stanu dla niezależności. Propagowanie zbyt dużej ilości kontekstu powoduje konwergencję. Propagowanie zbyt małej powoduje niespójność.
Ćwiczenie: audyt własnego systemu kontekstu. Proszę utworzyć następującą strukturę katalogów i wypełnić ją istniejącymi instrukcjami:
mkdir -p .claude/{rules,skills,agents,hooks,config,state}
# Move domain-specific sections from CLAUDE.md into rules/
# Move reusable procedures into skills/
# Move agent specs into agents/
Następnie warto odpowiedzieć na pytania: które pliki ładują się przy każdej sesji, choć powinny ładować się na żądanie? Których plików ładowanych na żądanie brakuje? Odpowiedzi można śledzić w prostym dzienniku: oznaczać każdą sesję jako „poprawna za pierwszym podejściem” lub „wymagała korekty” i przejrzeć proporcję po 20 sesjach.
Często zadawane pytania
Jak zorganizować pliki kontekstu dla agentów AI piszących kod?
Treści domenowe warto przenieść do osobnych plików, gdy przekraczają 20-30 linii i gdy przynajmniej w części sesji byłyby nieistotne. Jeśli reguły specyficzne dla iOS i reguły webowe znajdą się w tym samym CLAUDE.md, agent przeczyta oba zestawy niezależnie od bieżącego projektu. Uniwersalne ograniczenia (reguły bezpieczeństwa, standardy kodowania, zasady filozoficzne) należy pozostawić w pliku głównym. Wzorce domenowe (endpointy FastAPI, konwencje SwiftUI, zapytania do bazy danych) lepiej przenieść do plików ładowanych na żądanie, czyli tylko wtedy, gdy wymaga ich zadanie.
Skąd wiadomo, że umiejętność się zdezaktualizowała?
Są dwa sygnały: agent generuje kod, który działa, ale nie pasuje do aktualnych wzorców bazy kodu, albo agent odwołuje się do API lub wzorców ze starszej wersji frameworka. Warto dodać do każdej umiejętności datę „ostatniej weryfikacji” i sprawdzać ją raz na kwartał. Co ważniejsze, pętla jakości (czy wygenerowany kod pasuje do istniejących wzorców?) wyłapuje dryf przestarzałych umiejętności niezależnie od ich treści.
Jaki rozmiar budżetu kontekstu jest właściwy?
Przy oknie 200 tysięcy tokenów należy zarezerwować 4-6% na prompt systemowy i reguły (ładowane zawsze), zostawić 40-60% na historię konwersacji i odczyty plików (właściwą pracę) oraz przeznaczyć 10-15% budżetu na umiejętności ładowane na żądanie i kontekst agentów. Jeśli presja kontekstu przekroczy 70%, zanim zadanie dojdzie do połowy, ładuje się zbyt dużo nieistotnego materiału. Konkretne proporcje zależą od złożoności zadania: refaktoryzacja wielu plików zużywa więcej kontekstu niż poprawka błędu w jednej funkcji.
Jak radzić sobie ze sprzecznymi instrukcjami między warstwami?
Należy zastosować pierwszeństwo oparte na zakresie: wygrywa warstwa bardziej szczegółowa. Umiejętności (zakres lokalny) nadpisują reguły (zakres modułu), które z kolei nadpisują CLAUDE.md (zakres globalny). Po wykryciu konfliktu warto jawnie zapisać jego rozstrzygnięcie, zamiast liczyć, że model rozwiąże go probabilistycznie. W bardziej szczegółowej warstwie należy dodać adnotację: „W tym konkretnym kontekście nadpisuje to ogólną zasadę X, ponieważ Y.”
Ten post rozwija wątki z Zarządzania oknem kontekstu (ekonomia tokenów) i Systemu Ralph (pamięć w systemie plików). System hooków Claude Code implementuje warstwę automatyzacji. Wzorce koordynacji agentów opisują Deliberacja wieloagentowa oraz Od boidów do agentów.
-
Birgitta Böckeler, “Context Engineering for Coding Agents,” martinfowler.com, February 2026. martinfowler.com/articles/exploring-gen-ai/context-engineering-coding-agents.html. Böckeler’s colleague Bharani Subramaniam defines context engineering as “curating what the model sees so that you get a better result.” The definition is correct. The present post argues that the structure of how that information is organized and delivered is an architectural discipline, not a documentation exercise. ↩
-
Daniel Miessler, “How to Talk to AI,” danielmiessler.com, June 2025. danielmiessler.com/blog/how-to-talk-to-ai. Miessler argues that the real skill underlying both prompt engineering and context engineering is clear thinking: the ability to articulate exactly what you want to accomplish. The framing complements the present post, which focuses on the structural discipline of organizing context rather than thinking clearly about it. ↩
-
The software architecture parallel is deliberate. Robert C. Martin, Clean Architecture: A Craftsman’s Guide to Software Structure and Design, Prentice Hall, 2017, Part III (Design Principles) and Part V (Architecture). Martin identifies the same forces: coupling, cohesion, and the separation of concerns. The difference in AI context systems is that “memory” is ephemeral and bounded, adding a constraint that traditional architecture does not face. ↩
-
The 650-file count is the author’s measurement as of February 2026. Global context: ~400 files (rules, skills, agents, hooks, configs, state, docs, handoffs). Project-specific context (blakecrosley.com): ~250 files (PRDs, docs, plans, workflows, i18n configs). Only a fraction loads per session. ↩
-
Variable scope resolution in programming languages (local, enclosing, global, built-in) is the direct analogy. Python’s LEGB rule defines the same hierarchy: local scope, enclosing function scope, global scope, built-in scope. See Python Software Foundation, “Execution Model,” section 4.2.2, “Resolution of names.” docs.python.org/3/reference/executionmodel.html. Skills (local scope) override rules (module scope) which override CLAUDE.md (global scope). The analogy breaks down slightly because LLM instruction following is probabilistic, not deterministic, but the architectural principle holds. ↩
-
Anthropic, “Models overview,” platform.claude.com, 2025. platform.claude.com/docs/en/docs/about-claude/models. All current Claude models (Opus 4.6, Sonnet 4.6, Haiku 4.5) specify a 200K token context window, with Opus 4.6 and Sonnet 4.6 supporting 1M tokens in beta. ↩
-
Token consumption measurements from 50 Claude Code sessions I tracked between August 2025 and February 2026. See Context Window Management for the full methodology. ↩
-
The analogy between token budgets and memory hierarchies follows the framework in Hennessy, J.L. and Patterson, D.A., Computer Architecture: A Quantitative Approach, 6th edition, Morgan Kaufmann, 2017, Chapter 2 (Memory Hierarchy Design). Hennessy and Patterson’s treatment of cache hierarchies, locality of reference, and the cost of memory access at different levels maps directly to context engineering: frequently needed context (L1 cache / core rules) loads fastest, while rarely needed context (disk / on-demand skills) loads only when referenced. ↩
-
First-attempt success rate is a rough metric based on the author’s subjective assessment of whether the first response required correction. It is not a controlled experiment. The directional improvement (60% to 80%) is consistent across session types but should not be cited as precise measurement. ↩
-
James Lewis and Martin Fowler, “Microservices,” martinfowler.com, March 2014. martinfowler.com/articles/microservices.html. Lewis and Fowler define microservices as “a suite of small services, each running in its own process and communicating with lightweight mechanisms.” The forces they identify (independent deployment, decentralized governance, bounded contexts) map directly to the agent isolation and protocol-based communication in the context architecture described here. ↩
-
The “context as architecture” framing draws from Xu et al., “Everything is Context: Agentic File System Abstraction for Context Engineering,” arXiv, December 2025. arxiv.org/abs/2512.05470. The paper proposes a file-system abstraction for managing context in generative AI systems, treating diverse knowledge artifacts, memory, and tools as context within token constraints. The theoretical framework supports the practical architecture described here. ↩
-
obra/superpowers, github.com/obra/superpowers. The superpowers project organizes agent context into core instructions, on-demand skills, and verification procedures, a structure that converged with the seven-layer architecture described here despite being developed independently. The convergence supports the thesis that layered context is a natural architectural response to bounded context windows. ↩