← Wszystkie wpisy

Inżynieria kontekstu to architektura: wnioski z 650 plików

10 min read

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 ujawniła, że inżynieria kontekstu to nie jest inżynieria promptów z większą liczbą plików. To architektura oprogramowania dla substratu, w którym pamięć degraduje się z każdym tokenem.

Kontekst to nie plik konfiguracyjny. To architektoniczny substrat, który determinuje, co agent AI może pomyśleć, co pamięta i co zapomina. Każda inna decyzja projektowa wynika z kontekstu. Poniżej przedstawiam sześć miesięcy produkcyjnej inżynierii kontekstu dla Claude Code: architekturę, awarie i system, który je przetrwał.

TL;DR

Artykuł Böckeler o inżynierii kontekstu (martinfowler.com, 2026)1 oraz framework jasnego myślenia Mieslera2 posuwają dyskusję naprzód, ale oba niedoceniają 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 rozproszonych w siedmiowarstwowej hierarchii. Architektura nie tkwi w samych plikach, lecz w tym, które pliki ładują się kiedy i co zostaje wykluczone.

Kontekst to nie plik

Cotygodniowy post „jak napisać CLAUDE.md” nie trafia w sedno. Napisanie dobrego CLAUDE.md jest konieczne i niewystarczające — tak samo jak napisanie dobrego kodu jest konieczne i niewystarczające do zbudowania dobrego systemu. Architektura to struktura determinująca sposób interakcji komponentów. W systemach agentowych kontekst jest tą strukturą.

Mój pierwszy CLAUDE.md był monolitem: 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 trzy rzeczy wydarzyły się jednocześnie:

  1. Plik rozrósł się powyżej 300 linii i zaczął wchodzić w konflikt sam ze sobą (reguła A mówiła „uprość”, reguła B mówiła „dodaj dokładną obsługę błędów”)
  2. Kontekst z projektu A wyciekał do projektu B (reguły specyficzne dla iOS zanieczyszczały sesję tworzenia aplikacji webowej)
  3. Agent zużywał tokeny na czytanie instrukcji nieistotnych dla bieżącego zadania

Objawy wskazują na problemy architektoniczne, 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 Wielokrotnie używalne moduły wiedzy z procedurami i przykładami Na żądanie (wywoływane lub auto-aktywowane przez hooki) 40 katalogów
4. Agenci Specjalizowane specyfikacje recenzentów/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 numeryczne (progi, budżety, limity) Odwoływane przez hooki i umiejętności 14 plików JSON
7. Stan Śledzenie na żywo (rodowód agentów, kalibracja pewności, koszty) Odwoływany przez hooki 36 plików

Kluczowe odkrycie 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

Trzy awarie, które ukształtowały architekturę

Awaria 1: Monolityczny CLAUDE.md

Mój oryginalny 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ł to 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ł około 4000 tokenów na sesję. W ciągu 50 sesji to łącznie 200 000 tokenów wydanych na instrukcje, których agent nigdy nie użył.

Rozwiązanie: Wyekstrahowanie 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 napędzała 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-minutowa sesja debugowania 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, 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 — metakognitywna kontrola, która wyłapuje dryf przestarzałych umiejętności niezależnie od ich treści.

Awaria 3: Konfliktujące 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”. Obie instrukcje były rozsądne w izolacji. Razem generowały niespójny wynik — czasem minimalistyczny, czasem nadmiernie złożony — w zależności od tego, którą instrukcję agent silniej ważył w danym kroku.

Koszt: Nieprzewidywalna jakość wyników. Ten sam typ zadania generował różne poziomy jakości w różnych sesjach, czyniąc system zawodnym.

Rozwiązanie: Ustanowienie jasnej hierarchii pierwszeństwa. CLAUDE.md definiuje zasady („preferuj prostotę”). Reguły definiują ograniczenia („waliduj wszystkie dane wejściowe użytkownika”). Umiejętności definiują procedury („oto jak zbudować endpoint FastAPI”). Gdy wchodzą w konflikt, bardziej szczegółowa warstwa wygrywa: procedura umiejętności nadpisuje wskazówkę zasady dla konkretnego zadania objętego tą umiejętnością. Rozwiązanie odzwierciedla sposób, w jaki języki programowania obsługują zakres: lokalny nadpisuje globalny.5

Budżet kontekstu jako ograniczenie architektoniczne

Okno kontekstu nie jest nieskończone. 200 tysięcy tokenów okna kontekstu Claude6 brzmi dużo, dopóki nie zmierzymy, co je zużywa:

Konsument Typowe tokeny % okna
Prompt systemowy + CLAUDE.md + reguły 8 000–12 000 4–6%
Historia konwersacji 20 000–80 000 10–40%
Odczyty plików (na plik) 5 000–20 000 2,5–10%
Wyniki narzędzi (na wywołanie) 1 000–10 000 0,5–5%
Kontekst umiejętności/agenta (na żądanie) 3 000–15 000 1,5–7,5%

Pomiary zużycia tokenów pochodzą z 50 sesji Claude Code, które śledziłem między sierpniem 2025 a lutym 2026.7 Intensywna 90-minutowa sesja może wyczerpać okno przez zwykłe odczyty plików i interakcje z narzędziami. Budżet kontekstu wymusza kompromisy architektoniczne:

Ładuj zawsze — podstawową filozofię, aktywne korekty i reguły bezpieczeństwa. Wszystkie trzy są tanie (4–6% budżetu) i uniwersalnie stosowalne.

Ładuj na żądanie — umiejętności, specyfikacje agentów i dokumentację referencyjną. Każda kosztuje 5–15% okna na umiejętność i dotyczy jednej domeny. Ładowanie ich tylko wtedy, gdy są istotne, zachowuje budżet na właściwą pracę.

Nigdy nie ładuj — przestarzałych dokumentów przekazania, wycofanych konfiguracji ani historycznego stanu. Każdy przestarzały plik zużywa budżet bez poprawy wyników. Wzorzec kumulującej się inżynierii wymaga okresowego przycinania kontekstu, który nie zarabia na swój koszt tokenowy.

Budżetowanie kontekstu odzwierciedla kompromisy napędzające indeksowanie baz danych, strategie cachowania i zarządzanie pamięcią w tradycyjnym oprogramowaniu.8 Ograniczenie jest inne (tokeny zamiast bajtów), ale dyscyplina architektoniczna jest identyczna.

Propagacja kontekstu w systemach wieloagentowych

Gdy główny agent uruchamia subagenta przez narzędzie Task, wybór kontekstu do propagacji napędza każdą inną decyzję projektową. Mój system wieloagentowej deliberacji używa 10 agentów badawczych. Każdy agent potrzebuje wystarczająco dużo kontekstu, by oceniać niezależnie, ale zbyt dużo współdzielonego kontekstu powoduje problem konwergencji udokumentowany w poście o boidach: agenci współdzielący zbyt dużo kontekstu wyciągają identyczne wnioski.

Reguły propagacji:

Typ kontekstu Propagowany? Dlaczego
Filozofia podstawowa Tak Spójność między agentami
Reguły domenowe Tak Wspólne standardy jakości
Instrukcje specyficzne dla zadania Tak Właściwa praca do wykonania
Historia konwersacji Nie Niezależność wymaga izolacji
Ustalenia innych agentów Nie (do 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 (iteracje), nie między agentami (procesy równoległe). Oba podejścia dzielą tę samą zasadę: propaguj ograniczenia i zasady, izoluj szczegóły implementacyjne.

Pomiar jakości kontekstu

Liczba tokenów to metryka zastępcza. Prawdziwa miara jakości kontekstu brzmi: czy agent generuje poprawny wynik przy pierwszej próbie?

Po śledzeniu 50 sesji zidentyfikował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ł około 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 (bardziej trafna wiedza).9

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. Błędy oceny wskazują na konfliktujący lub niejednoznaczny kontekst. Śledzenie typów korekt ujawnia, która warstwa wymaga uwagi.

Presja kontekstu przy zakończeniu zadania. Ile budżetu kontekstu pozostaje, gdy zadanie się kończy? Jeśli okno jest zapełnione w 90%, zanim zadanie jest wykonane 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%.

Wzorzec architektury rozproszonej

Nic w siedmiowarstwowym systemie nie jest unikalne dla agentów AI. Odzwierciedla on ustalone wzorce oprogramowania:

Wzorzec oprogramowania Odpowiednik kontekstowy
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 numeryczne)

Ta analogia nie jest metaforyczna. Te same siły (sprzężenie, kohezja, zakres, cykl życia) napędzają identyczne decyzje architektoniczne.10 Inżynieria kontekstu to inżynieria oprogramowania dla substratu, gdzie „pamięć” jest zasobem rzadkim i degradowalnym, a nie obfitym i trwałym.11

Kluczowe wnioski

Dla inżynierów budujących systemy agentowe:

  • Projektuj kontekst jak architekturę oprogramowania, nie jak dokumentację. To, co się ładuje kiedy, co nadpisuje co i co propaguje do subagentów, determinuje zachowanie agenta bardziej niż jakakolwiek pojedyncza instrukcja. Stosuj tę samą dyscyplinę separacji odpowiedzialności, której używasz w kodzie.

  • Rozdzielaj warstwy według cyklu życia. Uniwersalne reguły ładują się przy każdej sesji. Wiedza domenowa ładuje się na żądanie. Stan sesyjny pozostaje przejściowy. Mieszanie cykli życia w jednym pliku tworzy problemy sprzężenia, które architektura oprogramowania istnieje, by rozwiązywać.

Dla zespołów skalujących przepływy pracy AI:

  • Traktuj okno kontekstu jako 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ą. Mierz to, co ładujesz, i przycinaj 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. Propagacja zbyt dużej ilości kontekstu powoduje konwergencję. Propagacja zbyt małej ilości powoduje niespójność.

Ten post bazuje na Zarządzaniu oknem kontekstu (ekonomia tokenów) i Systemie Ralph (pamięć systemu plików). System hooków Claude Code implementuje warstwę automatyzacji. Wzorce koordynacji agentów opisano w Deliberacji wieloagentowej i Od boidów do agentów.

  1. 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. ↩

  2. 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. ↩

  3. The software architecture parallel is deliberate. Robert C. Martin, Clean Architecture: A Craftsman’s Guide to Software Structure and Design, Prentice Hall, 2017. 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. ↩

  4. 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. ↩

  5. 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. ↩

  6. 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. ↩

  7. Token consumption measurements from 50 Claude Code sessions I tracked between August 2025 and February 2026. See Context Window Management for the full methodology. ↩

  8. 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. 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. ↩

  9. 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. ↩

  10. 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. ↩

  11. 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. ↩