Przejdź do głównej zawartości
AI Developer Toolkit

Sprawdź swój poziom — za darmo Kup Toolkit Kup Toolkit Kup Toolkit Kup Toolkit Otwórz przewodniki Czytaj
Menu nawigacji
Kup Toolkit Sprawdź swój poziom — za darmo Kup Toolkit Otwórz przewodniki Zaloguj się

Przycinanie CLAUDE.md i AGENTS.md: protokół ablacji

EN

Poziom 2 Poradnik Zaktualizowano

Przycinanie plików kontekstu polega na traktowaniu CLAUDE.md, AGENTS.md i reguł Cursora jak budżetu do cięcia, a nie dziennika do rozbudowy. Protokół ablacji archiwizuje plik, zapisuje, które błędy się powtarzają, przywraca tylko linie, które im zapobiegają, resztę przenosi do reguł z zakresem, skilli i hooków, a przy każdej zmianie modelu rusza od nowa.

Trzy miesiące temu dopisałeś linię, żeby agent nigdy nie uruchamiał pnpm build, gdy działa serwer deweloperski. Dziś rano uruchomił pnpm build przy działającym serwerze. Odruch podpowiada przepisać regułę wersalikami i dodać „IMPORTANT”. To wydłuża plik, a długość pliku to jeden z powodów, dla których reguła przepadła. Ta strona jest dla programisty, który odpowiada za konfigurację agentów w repozytorium, i dla tech leada, który musi utrzymać jeden plik użyteczny dla ośmiu osób i trzech narzędzi. Jeśli nie masz jeszcze pliku kontekstu, zacznij od zwięzłego kontekstu repozytorium i wróć tu, gdy plik urośnie.

Co daje przycinanie plików kontekstu

Dział zatytułowany „Co daje przycinanie plików kontekstu”
  • Mapę tego, co Claude Code, Codex i Cursor ładują na starcie, co ładują na żądanie i które „optymalizacje” niczego nie oszczędzają
  • Tabelę routingu, która odpowiada na pytanie „gdzie ma trafić ta linia” dla każdej zachowanej reguły
  • Sześć promptów do skopiowania, które archiwizują, audytują, przenoszą, konsolidują i ponownie testują pliki instrukcji
  • Skrypt budżetu bajtów dla Codeksa i bramkę liczby linii w CI, żeby plik nie odrósł po cichu
  • Pętlę weryfikacji, która dowodzi, że przycięty plik nadal działa

Dlaczego dłuższy plik kontekstu pogarsza pracę agenta

Dział zatytułowany „Dlaczego dłuższy plik kontekstu pogarsza pracę agenta”

Dokumentacja pamięci Anthropic mówi o koszcie wprost: celuj w mniej niż 200 linii na CLAUDE.md, bo dłuższe pliki „consume more context and reduce adherence”. Trzy kolejne mechanizmy wyjaśniają, czemu długość szkodzi:

  • Instrukcje to rada, nie konfiguracja. Claude Code dostarcza CLAUDE.md „as a user message after the system prompt”, bez „guarantee of strict compliance, especially for vague or conflicting instructions”. Gdy dwie linie sobie przeczą, „Claude may pick one arbitrarily”.
  • Każdą kopię płacisz od nowa. W Claude Code każdy subagent poza wbudowanymi Explore i Plan ładuje całą hierarchię CLAUDE.md, chyba że jego definicja ustawia omitClaudeMd: true (v2.1.271+). Uruchom dziesięć subagentów bez tego pola, a zapłacisz za plik jedenaście razy.
  • Codex obcina nadmiar. Codex ogranicza treść projektowych AGENTS.md domyślnie do 32 KiB (project_doc_max_bytes, sprawdzone w kodzie 0.157.1). Plik, który przekracza limit, zostaje ucięty, a każdy następny pominięty.

Akrecja to dopisywanie linii po każdej pomyłce: plik tylko rośnie. Ablacja to termin z badań nad uczeniem maszynowym: usuwasz składnik, żeby zmierzyć, co wnosił. Tutaj oznacza celowe kasowanie linii i przywracanie tylko tego, co w sprawdzalny sposób się psuje.

Ustaw pokrętło pod model, który czyta plik

Dział zatytułowany „Ustaw pokrętło pod model, który czyta plik”

Im mocniejszy model, tym mniej rusztowania potrzebuje repozytorium. Każda reguła to zakład, że model sam czegoś nie wywnioskuje, a nowsze modele wygrywają coraz więcej takich zakładów. Na dzień 2026-10-12 domyślne są Claude Opus 5.5 w Claude Code (od v2.1.280, na obu kanałach wydań) i GPT-6.1 Sol jako domyślny model wbudowany w Codeksa (od CLI 0.159.1); aktualną listę trzyma hub modeli.

  • Domyślne modele z czołówki. Tnij mocno. Zostaw tylko to, co model bez tej linii robi źle.
  • Tańsze lub starsze modele (alias sonnet lub haiku, model lokalny). Zostaw więcej jawnych instrukcji: menedżer pakietów, wymagania wstępne, jedno polecenie, którego nie wolno uruchamiać.
  • Zespoły mieszane. Jeśli ten sam plik czyta twoja sesja z Opusem, tańszy model kolegi i zadanie w CI, pisz dla najsłabszego czytelnika. Mocny model lepiej znosi lekko przesadnie opisany plik niż słaby model plik niedopowiedziany.

Dlatego audyt powtarzasz przy zmianie modelu, nie według kalendarza, jako jeden z kroków planu oceny nowego modelu. Claude Code ma do tego gotowe sprawdzenie: /doctor prompt-audit szuka „instructions written for older models”, odwołań do nieistniejących plików i poleceń oraz plików, które sobie przeczą (v2.1.283, oba kanały wydań w dniu 2026-10-12). Gdy dla oszczędności schodzisz niżej o klasę modelu, spodziewaj się przywrócenia części linii. To ruch pokrętła, nie regres.

Co ładują Claude Code, Codex i Cursor, i kiedy

Dział zatytułowany „Co ładują Claude Code, Codex i Cursor, i kiedy”

Główny plik ładuje się w każdej sesji. O tym, gdzie trafi każda ocalała linia, decyduje to, które inne mechanizmy ładują się dopiero na żądanie.

Na starcie, w całości: zarządzane pliki polityk, ~/.claude/CLAUDE.md, każdy CLAUDE.md i CLAUDE.local.md w katalogu roboczym i katalogach nad nim oraz każdy plik .claude/rules/*.md bez frontmattera paths. Pamięć automatyczna dokłada pierwsze 200 linii albo 25 KB pliku MEMORY.md, zależnie od tego, co nastąpi wcześniej.

Na żądanie: pliki .claude/rules/*.md z globem paths ładują się, gdy Claude czyta pasujący plik. Pliki CLAUDE.md w podkatalogach poniżej katalogu roboczego ładują się, gdy Claude czyta plik w danym katalogu.

AGENTS.md: od v2.1.277 (na obu kanałach wydań, odkąd stable osiągnął v2.1.287, sprawdzone 2026-10-12) Claude Code czyta AGENTS.md, gdy w katalogu roboczym ani wyżej nie ma CLAUDE.md, .claude/CLAUDE.md ani CLAUDE.local.md. Żeby ładować oba, ustaw Project instructions w /config na claude-md-and-agents-md.

Pułapki warte uwagi:

  • Importy @path nie zmniejszają kontekstu. Importowane pliki „are expanded and loaded into context at launch”. Pięć schludnych importów pliku na 400 linii nadal kosztuje 400 linii w każdej sesji.
  • Pamięć automatyczna to akrecja bez twojego udziału. Jest domyślnie włączona i zapisuje notatki w ~/.claude/projects/<project>/memory/. Jej indeks ładuje się w każdej sesji, więc należy do powierzchni, którą przycinasz.
  • CLAUDE.local.md wyłącza AGENTS.md. Dodanie go na prywatne notatki w repozytorium opartym tylko na AGENTS.md sprawia, że przy domyślnym ustawieniu Claude przestaje czytać AGENTS.md.
  • Komentarze HTML są darmowe. Blokowe komentarze <!-- ... --> są usuwane przed wstrzyknięciem, więc uzasadnienie dla ludzi nie kosztuje tokenów.
  • Claude Code sam sygnalizuje przerośnięty plik. Ostrzega na starcie i w /status, gdy plik instrukcji przekracza zalecaną długość, a sprawdzenie /doctor (v2.1.206+) proponuje wycięcie z zatwierdzonego w repozytorium CLAUDE.md treści, które da się odczytać z kodu, np. układu katalogów i listy zależności.

Co się załadowało, sprawdzisz przez /context (lista Memory files) i /memory.

Gdzie powinna trafić każda linia pliku kontekstu

Dział zatytułowany „Gdzie powinna trafić każda linia pliku kontekstu”

Gdy wiesz, co ładuje się dopiero na żądanie, pytanie „czy ta linia zostaje?” zamienia się w „gdzie ta linia ma trafić?”. Główny plik to tylko jedno z kilku miejsc.

Co maszClaude CodeCodexCursor
Reguła potrzebna w każdej sesjiCLAUDE.md (lub AGENTS.md), poniżej 200 liniigłówny AGENTS.mdreguła stosowana zawsze
Reguła dla jednego typu plików.claude/rules/<temat>.md z pathsAGENTS.md najbliżej tych plików (brak zakresu po globie)reguła z zakresem glob
Reguła dla jednego pakietu lub kataloguCLAUDE.md w podkataloguAGENTS.md w podkatalogu (AGENTS.override.md, by go przesłonić)reguła z zakresem
Procedura wieloetapowaskill w .claude/skills/<nazwa>/SKILL.mdskill w .agents/skills/<nazwa>/SKILL.mdskill
„Nigdy nie rób X”, co musi się utrzymaćhook PreToolUse lub Stophook albo sprawdzenie w CIhook
Dodatkowe wskazówki dla tańszego modeludefinicja subagenta z własnym modeldefinicja subagentadefinicja subagenta (sprawdź, czy da się w niej przypiąć model)
Subagent, który wszystko dostaje w prompcie delegacjiomitClaudeMd: true w jego definicji (v2.1.271+), żeby przestał płacić za CLAUDE.md——
Osobiste preferencjeCLAUDE.local.md lub ~/.claude/CLAUDE.md~/.codex/AGENTS.mdreguła użytkownika
Notatka dla ludzi utrzymujących repokomentarz HTML (zero tokenów)READMEREADME

Z tabeli wynikają dwie praktyczne zasady:

  • Jeśli reguła zaczyna się od „gdy”, nie należy do głównego pliku. „Gdy pracujesz nad handlerami API, waliduj wspólnym helperem schematów” to przebrana reguła z zakresem ścieżki.
  • Jeśli zirytuje cię, że agent ją zignorował, proza to złe narzędzie. „Nigdy nie uruchamiaj builda przy działającym serwerze deweloperskim” to hook, nie zdanie. Zobacz hooki jako deterministyczne zabezpieczenia.

Przeprowadź protokół ablacji

Dział zatytułowany „Przeprowadź protokół ablacji”

Sześć kroków poniżej wykonujesz po kolei: archiwizacja, audyt, przeniesienie, utwardzenie, konsolidacja, dowód. Każdy ma prompt działający w każdym z trzech narzędzi; zakładki zawierają tylko różnice między narzędziami.

  1. Zarchiwizuj plik i załóż dziennik ablacji. Nie zaczynaj od edycji. Najpierw ustal, co plik ci daje. Przez tydzień pracuj normalnie z minimalnym plikiem i zapisuj każde potknięcie. Linia wraca dopiero wtedy, gdy agent dwa razy pomyli się w ten sam sposób; jedna pomyłka to szum.

    Zarchiwizuj CLAUDE.md, CLAUDE.local.md i .claude/rules/. Na ten tydzień wstrzymaj pamięć automatyczną, bo inaczej odtworzy to, co usunąłeś: ustaw "autoMemoryEnabled": false w .claude/settings.local.json albo wyeksportuj CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. Przez /context potwierdź, że Memory files zawiera tylko to, czego się spodziewasz.

  2. Przeprowadź audyt archiwum linia po linii. Agent musi podać werdykt i uzasadnienie dla każdej linii. Dwadzieścia słabych uzasadnień z rzędu sprawia, że kasowanie przychodzi łatwo.

    Linie KEEP to kandydaci, a nie przywrócenia: linia KEEP wraca dopiero wtedy, gdy dziennik dwa razy pokaże pomyłkę, której zapobiega; do tego czasu trzymaj listę KEEP w dzienniku.

    W Claude Code najpierw uruchom /doctor prompt-audit (od v2.1.283, oba kanały wydań w dniu 2026-10-12; wymaga włączonych wbudowanych skilli; żeby sprawdzić jeden plik lub katalog, podaj ścieżkę, np. .claude/rules). Raportuje przestarzałe i sprzeczne instrukcje z propozycjami zmian i niczego nie zmienia, dopóki o to nie poprosisz. W Codeksie przed promptem uruchom skrypt budżetu bajtów, żeby wiedzieć, które instrukcje już przepadały.

  3. Wyprowadź reguły warunkowe z głównego pliku. Każdy werdykt MOVE-PATH staje się regułą z zakresem albo plikiem w podkatalogu. W monorepo główny plik zachowuje tylko to, co prawdziwe dla każdego pakietu; „prawie wszędzie” to nie „wszędzie”.

    Reguła bez paths ładuje się na starcie jak główny plik, więc to frontmatter czyni ją warunkową:

    ---
    paths:
      - "services/api/**/*.ts"
    ---
    

    # API handlers
    

    - Validate every request body with the shared schema helper in `services/api/lib/validate.ts`.
    - Error responses use the `{ error, code }` shape, never a bare string.

    paths to jedyne pole frontmattera, które Claude Code czyta z reguły. Jeśli YAML się nie parsuje, reguła ładuje się bezwarunkowo; błąd parsowania pokaże claude --debug.

  4. Zamień procedury w skille, a twarde reguły w hooki. Procedura w głównym pliku jest czytana w każdej turze. Skill jest czytany, gdy jego opis pasuje do zadania, więc szczegóły stają się tam tanie. „Nigdy” w prozie to mocna sugestia; hook to egzekwowanie.

    Hook dla reguły o pnpm build z początku strony, w pliku .claude/settings.json Claude Code:

    {
      "hooks": {
        "PreToolUse": [
          {
            "matcher": "Bash",
            "hooks": [
              { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/no-build-with-dev-server.sh" }
            ]
          }
        ]
      }
    }
    #!/bin/bash
    # .claude/hooks/no-build-with-dev-server.sh (chmod +x; needs jq and lsof)
    COMMAND=$(jq -r '.tool_input.command')
    if echo "$COMMAND" | grep -Eq 'pnpm( -[^ ]+)*( run)? build' && lsof -iTCP:3000 -sTCP:LISTEN >/dev/null 2>&1; then
      jq -n '{hookSpecificOutput: {hookEventName: "PreToolUse", permissionDecision: "deny",
        permissionDecisionReason: "Dev server is listening on :3000. Stop it before pnpm build."}}'
    fi
    exit 0

    Wzorzec dopasowania jest poglądowy: rozszerz go o każdy zapis, którego używa zespół. Hooki w Codeksie są w 0.157.1 stabilne i włączone, ale zanim się uruchomią, wymagają utrwalonego zaufania: zarejestruj podobny hook polecenia w .codex/hooks.json (albo w tabeli [hooks] w config.toml). Hooki jako deterministyczne zabezpieczenia pokazują rejestrację w Codeksie i obejście dla Cursora. Dla reguł formatowania i lintowania lepszym murem bywa sprawdzenie w CI, bo łapie też commity ludzi.

  5. Skonsoliduj wszystko do jednego źródła prawdy. Dwa pliki mówiące prawie to samo rozjeżdżają się w tempie, w jakim je edytujesz. AGENTS.md to otwarty format dla wielu narzędzi: wrzuć tam wszystko, co niezależne od narzędzia, a pliki specyficzne dla narzędzi utrzymuj prawie puste.

    Jeśli w repozytorium nie ma CLAUDE.md, Claude Code v2.1.277+ czyta AGENTS.md bezpośrednio. Jeśli potrzebujesz linii tylko dla Claude’a albo część sesji działa na starszej wersji, wstaw @AGENTS.md jako pierwszą linię CLAUDE.md i dopisz pod nią instrukcje dla Claude’a. Gdy ktokolwiek klonuje repo na Windowsie, wybierz import zamiast symlinku: symlink wymaga tam uprawnień administratora albo trybu Developer Mode.

  6. Udowodnij każdą zachowaną regułę i zaplanuj kolejną rundę na zmianę modelu. Jeśli nie potrafisz wskazać zachowania, które reguła zmienia, jest szumem, a szum nie jest darmowy.

Jak udowodnić, że przycięty plik nadal działa

Dział zatytułowany „Jak udowodnić, że przycięty plik nadal działa”

Przycinanie jest bezpieczne tylko wtedy, gdy potrafisz pokazać brak regresji bez ponownego czytania każdej linii i każdego diffu. Dowód opiera się na pięciu sprawdzeniach:

  1. Istniejące bramki pozostają zielone. Testy, sprawdzanie typów i lint w CI to sprawdzenie zachowania. Przycięty plik, który produkuje wadliwe PR-y, wyjdzie najpierw tam, a nie w przeglądzie samego pliku.
  2. Dziennik ablacji jest dowodem. Każda przywrócona linia powołuje się na co najmniej dwie datowane pomyłki. PR z opisem „usunięto 140 linii; trzy pomyłki w dwa tygodnie, przywrócono dwie linie, dziennik w załączniku” da się przejrzeć. Samego usunięcia 140 linii — nie.
  3. Ładowanie jest potwierdzone, nie zakładane. W Claude Code /context pokazuje załadowane pliki pamięci, a hook na zdarzeniu InstructionsLoaded może logować, które pliki CLAUDE.md i reguł się załadowały, kiedy i dlaczego. AGENTS.md czytany przez Claude Code bezpośrednio (bez CLAUDE.md) nie wywołuje InstructionsLoaded; potwierdź jego załadowanie przez /memory, które pokazuje go od v2.1.280. W Codeksie uruchom poniższy skrypt budżetu bajtów.
  4. Rozmiar jest pilnowany w CI. Bramka liczby linii poniżej odrzuca PR, który wydłuża dowolny plik instrukcji ponad 200 linii, więc akrecja wymaga świadomego wyjątku.
  5. Plik ma właściciela. Obejmij pliki instrukcji plikiem CODEOWNERS, żeby tech lead zatwierdzał każdy dopisek, i wymagaj wpisu w dzienniku przy każdym z nich.

Sprawdź budżet bajtów Codeksa

Dział zatytułowany „Sprawdź budżet bajtów Codeksa”

Zapisz to jako codex-agents-budget.sh i uruchom bash codex-agents-budget.sh w katalogu, w którym startujesz Codeksa (uruchom go przez bash, a nie source — wtedy exit nie zamknie ci terminala). Skrypt odtwarza kolejność Codeksa (najpierw korzeń projektu, jeden plik na katalog, AGENTS.override.md przed AGENTS.md) i wypisuje sumę narastającą:

codex-agents-budget.sh
#!/usr/bin/env bash
root=$(git rev-parse --show-toplevel) || { echo 'not a git repo'; exit 1; }
d=$PWD; dirs=()
while :; do
  dirs=("$d" "${dirs[@]}"); [ "$d" = "$root" ] && break
  [ "$d" = / ] && break; d=$(dirname "$d")
done
total=0
for d in "${dirs[@]}"; do
  for f in AGENTS.override.md AGENTS.md; do
    if [ -f "$d/$f" ]; then
      size=$(wc -c < "$d/$f"); total=$((total + size))
      printf '%7d bytes  running %7d  %s\n' "$size" "$total" "$d/$f"; break
    fi
  done
done
if [ "$total" -gt 32768 ]; then
  echo "Over 32 KiB: Codex truncates the file that crosses the line and skips the rest."
fi

Skrypt pomija project_doc_fallback_filenames i podniesiony project_doc_max_bytes; jeśli ustawiasz którekolwiek, popraw nazwy plików i limit.

Pilnuj długości plików instrukcji w CI

Dział zatytułowany „Pilnuj długości plików instrukcji w CI”
Okno terminala
# CI step: fail when any agent instruction file exceeds 200 lines
over=$(git ls-files '*CLAUDE.md' '*AGENTS.md' '*AGENTS.override.md' '.claude/rules/*.md' \
  | while read -r f; do
      n=$(wc -l < "$f")
      if [ "$n" -gt 200 ]; then echo "$f: $n lines"; fi
    done)
if [ -n "$over" ]; then
  echo "$over"; echo "Prune or split before merging."; exit 1
fi

Liczba 200 to rekomendacja Anthropic dla pojedynczego CLAUDE.md; dla repozytoriów tylko z Codeksem wybierz własną wartość, ale jakąś wybierz.

Kiedy przycinanie plików kontekstu idzie źle

Dział zatytułowany „Kiedy przycinanie plików kontekstu idzie źle”

Reguła jest ignorowana mimo skróconego pliku. Sprawdź trzy rzeczy po kolei. Po pierwsze: czy plik się załadował? W Claude Code plik nieobecny w /context wygląda dokładnie jak ignorowana reguła; w Codeksie sprawdź budżet bajtów i to, czy projekt jest zaufany. Po drugie: czy inna reguła jej nie przeczy? Agent może wybrać dowolną z nich i żadne wersaliki tego nie naprawią. Po trzecie: czy regułę da się sfalsyfikować? „Pisz utrzymywalny kod” nie da się ani przestrzegać, ani złamać, więc ją usuń.

Usunąłeś coś nośnego i wyłapało to CI. To protokół w działaniu i powód, dla którego krok 1 archiwizuje zamiast kasować. Przywróć jedną linię, opisz pomyłkę w dzienniku i nie przywracaj całej sekcji, z której pochodziła.

Codex słucha ogólnych reguł globalnych, a ignoruje precyzyjne lokalne. To cięcie na 32 KiB, a nie regres modelu. Ponieważ pliki projektu ładują się od korzenia, ucięty albo pominięty zostaje najbliższy, najbardziej szczegółowy plik. Uruchom skrypt budżetu bajtów, a potem przenieś procedury do skilli i podziel główny plik.

Pamięć automatyczna odbudowuje to, co usunąłeś. Pamięć automatyczna zapisuje twoje poprawki, więc kilka tygodni po ablacji może zawierać te same reguły, które usunąłeś, w pliku, którego nikt nie przegląda. Otwieraj /memory przy każdym przeglądzie głównego pliku albo wyłącz pamięć automatyczną dla projektu i prowadź notatki ręcznie.

AGENTS.md przestał się ładować w Claude Code. Ktoś dodał na ścieżce CLAUDE.md albo CLAUDE.local.md, które przy domyślnym ustawieniu mają pierwszeństwo. Ustaw Project instructions w /config na claude-md-and-agents-md albo wstaw @AGENTS.md na początek CLAUDE.md; import działa też w buildach starszych niż v2.1.277.

Zespół nie zgadza się co do tego, co wycięto. Przeglądaj dziennik, nie diff. Każda przywrócona linia potrzebuje dwóch datowanych pomyłek, a każde sporne cięcie rozstrzygnie prompt A/B z kroku 6.

Dokąd dalej po przycięciu plików kontekstu

Dział zatytułowany „Dokąd dalej po przycięciu plików kontekstu”
AGENTS.md i CLAUDE.md: zwięzły kontekst repozytorium Co powinny mówić linie, które przetrwały cięcie, i jak ocenić plik.
Pamięć Claude Code: CLAUDE.md, reguły i pamięć automatyczna Pełny opis hierarchii CLAUDE.md, reguł i pamięci automatycznej w Claude Code.
Nowy model na rynku: plan oceny w 48 godzin Zmiana modelu, która powinna uruchomić kolejną rundę ablacji, i sposób jej oceny.
Dokumentacja jako kontekst Gdzie trafia dłuższy materiał referencyjny po wyjściu z głównego pliku.
Wzorce długookresowego zachowywania kontekstu Pamięć automatyczna i notatki między sesjami: powierzchnia, która rośnie, gdy ty przycinasz.
Optymalizacja kosztu kontekstu Policz, ile kosztuje plik ładowany zawsze w skali miesiąca sesji.
Skille agentów: polityka jako przetestowany workflow Napisz skille, w które zamieniają się wydzielone procedury, z opisami, które je ładują.
Repozytorium gotowe na agentów Testy, skrypty i struktura, dzięki którym krótki plik kontekstu spełnia swoją rolę.
Wszystkie 577 przewodników Bezpłatne zasoby: Porównaj narzędzia Słownik Według roli

Autor:

Zobacz co nowego na platformie.

Polityka prywatności Regulamin Ustawienia cookie llms-pl.txt pricing-pl.md RSS