Dokumentacja jako efektywny kontekst AI

Dokumentacja jako kontekst to wiedza o projekcie zapisana w plikach, które agent do kodowania wczytuje sam: CLAUDE.md w Claude Code, AGENTS.md w Codeksie i Rules w Cursorze. Plik zawiera to, czego nie widać w kodzie: komendy, konwencje i świadome wyjątki. Pomaga tylko wtedy, gdy jest krótki, konkretny i sprawdzany względem repozytorium.

Ta strona jest dla programistów, którzy konfigurują agenta w repozytorium, i dla tech leadów, którzy odpowiadają za wspólny plik instrukcji. Znasz ten problem: agent uruchamia npm test, choć repozytorium używa pnpm vitest, pisze od nowa helper, który już istnieje, albo „naprawia” wzorzec, który zespół wybrał celowo. Każda sesja zaczyna się bez pamięci poprzedniej, więc agent płaci za ponowne odkrywanie tych samych faktów i czasem odkrywa je źle. Jeśli budżet kontekstu to dla ciebie nowy temat, zacznij od strony Okna kontekstu. Skróconą wersję tego, co powinien zawierać plik w repozytorium, znajdziesz w AGENTS.md i CLAUDE.md: zwięzły kontekst repozytorium.

Co zyskasz, traktując dokumentację jako kontekst

• Jasny podział na to, co należy do pliku wczytywanego zawsze, i to, co powinno ładować się dopiero na żądanie.
• Wiedzę, jak Claude Code, Codex i Cursor znajdują i łączą pliki instrukcji, łącznie z limitami, które po cichu ucinają pliki.
• Trzy prompty do skopiowania: szkic pliku, audyt i zapisanie lekcji po powtórzonym błędzie.
• Kontrolę w CI i test świeżej sesji, które pokazują, że plik nadal jest prawdziwy, bez ponownego czytania go linijka po linijce.

Jaką dokumentację agent powinien wczytywać i kiedy?

Dokumentacja dla agenta ma trzy warstwy. Pliki puchną, gdy wszystkie trzy trafiają do pierwszej.

Warstwa	Co zawiera	Kiedy się wczytuje	Gdzie leży
Zawsze wczytywana	Komendy, konwencje odbiegające od domyślnych, zakazy typu „nigdy nie rób X”	W każdej sesji, w każdej turze	CLAUDE.md, AGENTS.md, reguły Cursora stosowane zawsze
Na żądanie	Reguły dla jednego katalogu lub typu plików, procedury wieloetapowe, decyzje projektowe	Gdy agent dotyka pasujących plików albo uzna skill za przydatny	Reguły z zakresem ścieżek, zagnieżdżone pliki instrukcji, skille, dokumenty wskazane w pliku
Pobierana na żywo	API bibliotek zewnętrznych, dokumentacja wewnętrzna spoza repozytorium	Gdy agent wywołuje narzędzie	Serwery MCP, np. Context7

Warstwa zawsze wczytywana jest droga, bo za każdą linijkę płacisz w każdej turze. Linijka zasługuje na miejsce w tej warstwie tylko wtedy, gdy bez niej agent zrobiłby coś źle. Pozostałe dwie warstwy kosztują kontekst dopiero wtedy, gdy agent z nich korzysta.

Jak Claude Code, Codex i Cursor wczytują pliki instrukcji?

Trzy narzędzia dzielą ten sam pomysł, ale różnią się nazwami plików, kolejnością łączenia i limitami. Od tych szczegółów zależy, czy najbardziej szczegółowe instrukcje w ogóle dotrą do modelu.

Claude Code

Claude Code czyta CLAUDE.md na początku każdej sesji (dokumentacja pamięci, odczyt 2026-09-26).

repo/
  CLAUDE.md            # team instructions, committed (or .claude/CLAUDE.md)
  CLAUDE.local.md      # personal notes, add to .gitignore
  .claude/rules/
    testing.md         # no `paths:` frontmatter, loads at launch
    api.md             # `paths: ["src/api/**/*.ts"]`, loads only for matching files
  packages/web/
    CLAUDE.md          # loads when Claude reads a file in packages/web/

• Hierarchia. Pliki z katalogu roboczego i wszystkich katalogów nad nim wczytują się przy starcie i są sklejane od korzenia, więc plik najbliższy miejscu startu Claude czyta na końcu. Pliki z podkatalogów wczytują się, gdy Claude przeczyta w nich jakiś plik.
• Reguły z zakresem ścieżek. Reguła w .claude/rules/ z listą paths we frontmatterze wczytuje się tylko wtedy, gdy Claude czyta pasujący plik. paths to jedyne pole frontmattera, które Claude Code odczytuje z reguły.
• Importy nie oszczędzają kontekstu. @path/to/file rozwija się przy starcie, więc import porządkuje długi plik, ale go nie odchudza.
• Darmowe notatki dla opiekunów. Blokowe komentarze HTML (<!-- ... -->) są usuwane, zanim plik trafi do modelu.
• AGENTS.md. Od v2.1.277 (v2.1.281 w sesjach przez Bedrock, Google Cloud, Foundry i bramy LLM oraz z wyłączoną telemetrią; 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 nad nim nie ma CLAUDE.md, .claude/CLAUDE.md ani CLAUDE.local.md. Jeśli istnieją oba, czyta tylko pliki CLAUDE.md. Żeby utrzymać jeden wspólny plik, wpisz @AGENTS.md na początku CLAUDE.md, a linijki tylko dla Claude dodaj pod spodem, albo ustaw Project instructions w /config na claude-md-and-agents-md, żeby wczytywać oba pliki.
• Rozmiar. Dokumentacja zaleca poniżej 200 linii na CLAUDE.md. Próg 200 linii (lub 25 KB) dotyczy pliku MEMORY.md z auto memory, nie CLAUDE.md, który wczytuje się w całości do 4 MiB.

Codex

Codex czyta AGENTS.md, zanim zacznie jakąkolwiek pracę. Opisany niżej mechanizm sprawdziliśmy w kodzie Codeksa 0.157.1 (codex-rs/core/src/agents_md.rs).

repo/                      # project root = nearest ancestor with .git
  AGENTS.md
  services/payments/
    AGENTS.override.md     # used instead of AGENTS.md in this directory
    AGENTS.md              # ignored while the override exists

• Jeden plik na katalog. Codex przechodzi od korzenia projektu do katalogu, w którym go uruchomiono, nigdy ponad korzeń i nigdy poniżej katalogu startowego. W każdym katalogu bierze pierwszy znaleziony plik w kolejności: AGENTS.override.md, AGENTS.md, potem nazwy z project_doc_fallback_filenames. Override zastępuje więc sąsiedni AGENTS.md, a nie go uzupełnia.
• Sklejanie od korzenia. Znalezione pliki są łączone w kolejności od korzenia do katalogu startowego.
• Budżet 32 KiB. project_doc_max_bytes domyślnie wynosi 32 KiB na wszystkie pliki projektu. Plik, który przekracza budżet, zostaje ucięty, a każdy kolejny pominięty. Najbardziej szczegółowe pliki są na końcu, więc to one przepadają. Ostrzeżenie trafia do logu Codeksa, nie do interfejsu w terminalu.
• Zaufanie. Od 0.150.0 niezaufany projekt w ogóle nie dostarcza AGENTS.md na poziomie projektu.
• /init tworzy startowy AGENTS.md.

Cursor

Mechanizmem Cursora są Rules, czyli „system-level instructions to Agent” (dokumentacja Rules, odczyt 2026-08-28).

Format pliku reguły według dokumentacji Cursora (sprawdzone 2026-10-12):

• Reguły projektu leżą w .cursor/rules jako pliki .mdc; zwykły plik .md w tym katalogu jest ignorowany.
• Pola frontmattera to description, globs i alwaysApply; reguły działają w Agencie (Chat), a nie w uzupełnianiu Tab ani w Inline Edit.
• Cursor obsługuje AGENTS.md w katalogu głównym projektu i w podkatalogach, przy czym pierwszeństwo ma bardziej szczegółowy zagnieżdżony plik, a CLAUDE.md czyta tak samo, stosując go zawsze w każdej rozmowie.
• Jak potwierdzić, że reguła z zakresem się wczytała: po otwarciu pasującego pliku zapytaj agenta, które reguły zastosował.

Reguły projektu w Cursorze pokazują na tej stronie, jak pisać reguły i zawężać ich zakres.

Rady dotyczące treści z tej strony obowiązują bez zmian: jeden temat na regułę, komendy i wyjątki zamiast ogólnych porad oraz zawężanie zakresu wszystkiego, co ma znaczenie tylko w jednej części kodu.

Co powinno trafić do pliku instrukcji dla agenta?

Każdą linijkę sprawdź jednym testem: czy bez niej agent zrobiłby to źle? Jeśli nie, usuń ją.

Zostaw	Przykład
Komendy, których agent nie zgadnie	pnpm vitest run src/billing, make db-reset przed testami integracyjnymi
Konwencje odbiegające od domyślnych	„Kwoty to całkowite grosze; nigdy nie używaj floatów”
Świadome wyjątki wraz z powodem	„W src/reports/ nie używamy ORM-a; surowy SQL jest tu szybszy”
Twarde ograniczenia	„Nigdy nie edytuj plików w generated/; uruchom pnpm codegen”
Gdzie szukać, a nie co tam jest	„Wzorcowy handler API to src/api/users.ts”

Wytnij	Dlaczego
Opis projektu albo streszczenie architektury	Agent szybciej przeczyta kod niż twoje streszczenie, a streszczenie się rozjeżdża
Mapa plik po pliku	Nieaktualna po kilku tygodniach, a nieaktualna mapa aktywnie wprowadza w błąd
Konwencje języka i „pisz czysty kod”	Model i tak ich przestrzega; linijka to czysty koszt
Długie procedury, np. checklista wydania	Przenieś je do skilla albo dokumentu wczytywanego na żądanie
Wszystko, co zmienia się co tydzień	Trzymaj to tam, gdzie powstaje, a nie tam, gdzie się to pamięta

Konkret działa lepiej niż emfaza. Porównaj dwie wersje tej samej intencji:

# Weak: nothing here changes what the agent does
We care about quality. Write clean, well-tested code and handle errors properly.

# Strong: each line prevents a specific mistake
- Run one test file: pnpm vitest run <path>
- API errors return { error: string, code: number }; never throw from a handler
- Integration tests use the real database (docker compose up db); never mock it
- Never commit to main; open a branch and a pull request

Zbuduj plik instrukcji, którego agent przestrzega

1. Wygeneruj szkic, potem go przytnij. Uruchom /init w Claude Code lub Codeksie albo użyj pierwszego promptu poniżej w dowolnym narzędziu. Traktuj wynik jak surowiec. Wygenerowane pliki często powtarzają to, co widać w kodzie, więc spodziewaj się, że usuniesz sporą część.

2. Uruchom każdą komendę z pliku. Komenda, którą agent skopiuje z pliku i która potem nie zadziała, kosztuje więcej niż jej brak. Zostaw tylko komendy, które przechodzą na czystym checkoucie.

3. Wynieś reguły o wąskim zakresie z pliku głównego. Wszystko, co dotyczy tylko jednego katalogu, trafia do reguły z zakresem ścieżek (.claude/rules/ z paths), zagnieżdżonego AGENTS.md albo reguły Cursora zawężonej tak, jak opisuje to dokumentacja Rules. Procedury stają się skillami.

4. W zespole z kilkoma narzędziami wybierz jedno źródło prawdy. Wspólną treść trzymaj w AGENTS.md, a CLAUDE.md niech będzie jednolinijkowym importem @AGENTS.md plus ewentualne linijki tylko dla Claude. Cursor czyta AGENTS.md w katalogu głównym projektu i w podkatalogach (dokumentacja Cursora, sprawdzone 2026-10-12), więc nie potrzebuje kopii; potwierdź to testem świeżej sesji opisanym niżej. Katalog .cursor/rules zostaw na reguły potrzebne tylko Cursorowi, a nie na kopię wspólnego pliku. Tam, gdzie kopie dla poszczególnych narzędzi jednak trzymasz, użyj narzędzia do synchronizacji, jak opisuje Jedno źródło reguł dla każdego agenta. Dwie ręcznie utrzymywane kopie szybko się rozjadą.

5. Dodaj kontrolę rozjazdu i test świeżej sesji z następnej sekcji, a plik zacommituj z właścicielem wpisanym w CODEOWNERS.

6. Dodawaj regułę dopiero po drugim wystąpieniu. Gdy agent popełni ten sam błąd dwa razy, dodaj jedną konkretną linijkę. Po pojedynczej porażce popraw kod i idź dalej. Przycinanie CLAUDE.md i AGENTS.md opisuje kierunek odwrotny: usuwanie linijek, które przestały się opłacać.

Prompt do skopiowania: szkic pliku instrukcji na podstawie istniejącego kodu

Draft an AGENTS.md for this repository that I will cut down. It is a draft,
not a finished file.

Include only:
1. Build, test, lint, and single-test commands. Run each one and report
   which pass on this checkout. Mark any command I could not guess from
   package.json, the Makefile, or the CI config.
2. Conventions that differ from the language's defaults, each with one
   file path that shows it.
3. Setup steps a new clone needs before the tests pass.
4. Places where this repo deliberately does not do the obvious thing,
   with the reason if the code or commit history shows it.

Do not include a project overview, an architecture summary, or a map of
directories. Stay under 80 lines. Put a "(?)" after any line you are not
sure about instead of padding the file.

Prompt do skopiowania: audyt istniejącego pliku instrukcji

Audit our agent instruction files (CLAUDE.md, CLAUDE.local.md, AGENTS.md,
.claude/rules/, and Cursor rules if present). Do not edit anything yet.

For each line, classify it as:
- KEEP: you would get this wrong without it
- CUT: you would do this correctly anyway, or it describes code you can read
- STALE: it names a command, path, script, or dependency that no longer
  exists (check package.json, the lockfile, and the file tree)
- MOVE: it matters for only one directory or task; name the path-scoped
  rule, nested file, or skill it should move to
- CONFLICT: it contradicts another line; quote both

Then report the current line count of each file and show the proposed
version of the root file as a diff.

Prompt do skopiowania: zapisz lekcję po powtórzonym błędzie

You have now made this mistake twice: you ran the whole test suite with
`pnpm test` when the change only touched src/billing, and it took 9 minutes.

Add one rule to AGENTS.md that prevents it. The rule must:
- be one line, with the exact command to use instead
- go in the existing Commands section, not a new section
- replace any existing line it overlaps with

Show me the diff. If a line of similar intent already exists, tell me
why it did not work instead of adding a second one.

W Claude Code podobny audyt tych samych plików uruchamia /doctor prompt-audit (v2.1.283 i nowsze, oba kanały wydań w dniu 2026-10-12). Proponuje zmiany, ale ich nie wprowadza. Audyt działa przez wbudowany skill /claude-api, więc jest niedostępny, gdy ustawiono disableBundledSkills albo ten skill wyłączono w skillOverrides.

Jak dowieść, że plik instrukcji nadal zgadza się z repozytorium?

Nikt nie czyta co tydzień pliku na 90 linijek, więc niech plik sprawdza się sam. Większość rozjazdów wyłapią dwie kontrole: skrypt w CI, który pada, gdy plik wskazuje nieistniejącą ścieżkę lub skrypt, i test, w którym świeża sesja agenta odpowiada na pytania, na które odpowiedź jest tylko w pliku.

1. Kontrola rozjazdu w CI. Zapisz to jako scripts/check-agent-docs.sh i uruchamiaj w tym samym jobie co linter. Skrypt pada, gdy plik przekracza budżet linii, wskazuje nieistniejącą ścieżkę w src/, scripts/, tests/, docs/ lub packages/ albo skrypt npm run, którego nie ma w package.json. Rozszerz wzorce o pnpm, make lub cokolwiek, czego używa twój plik.

#!/usr/bin/env bash
# Fails when an agent instruction file drifts from the repository.
set -uo pipefail
status=0
for f in AGENTS.md CLAUDE.md; do
  [ -f "$f" ] || continue
  n=$(wc -l < "$f")
  if [ "$n" -gt 200 ]; then echo "$f: $n lines, budget is 200"; status=1; fi
  # Every backticked repo path must exist (globs and <placeholders> are skipped).
  for p in $(grep -oE '`(src|scripts|tests|docs|packages)/[^` ]*`' "$f" | tr -d '`' | grep -v '[*<]' | sort -u); do
    [ -e "$p" ] || { echo "$f: path not found: $p"; status=1; }
  done
  # Every "npm run X" must be a script in package.json.
  for s in $(grep -oE 'npm run [A-Za-z0-9:_-]+' "$f" | awk '{print $3}' | sort -u); do
    node -e "process.exit(require('./package.json').scripts?.[process.argv[1]] ? 0 : 1)" "$s" \
      || { echo "$f: npm script not found: $s"; status=1; }
  done
done
exit $status

Dla pliku, który wskazuje usunięty katalog src/routes/ i skrypt npm run lint o zmienionej nazwie, wypisuje obie linijki i kończy się kodem 1.

2. Test świeżej sesji. Napisz pięć pytań, na które odpowiedź jest tylko w pliku instrukcji, np. „Która komenda uruchamia jeden plik testów?” i „Skąd biorą się pliki generowane?”. Zadawaj je w nowej sesji po każdej zmianie pliku.

Claude Code

--tools "" wyłącza wszystkie narzędzia, więc Claude może odpowiedzieć tylko na podstawie tego, co wczytał przy starcie. --tools przyjmuje listę, więc polecenie wpisz przed tą flagą (albo po --); inaczej zostanie odczytane jako nazwa narzędzia:

claude -p "From your project instructions only: which command runs a single test file, and which directory must you never edit by hand?" --tools ""

Codex

codex exec nie ma przełącznika, który wyłącza czytanie plików, więc zabroń tego w poleceniu i uruchom sesję tylko do odczytu. Uruchamiaj test w projekcie, któremu Codex już ufa; w niezaufanym checkoucie Codex nie wczytuje żadnego AGENTS.md i każda odpowiedź będzie błędna.

codex exec --sandbox read-only --ephemeral "Do not open any files. From your AGENTS.md instructions only: which command runs a single test file, and which directory must you never edit by hand?"

Cursor

Otwórz nowy czat i zadaj to samo pytanie z dopiskiem „Do not open any files”. Potem zapytaj, które reguły zostały zastosowane, żeby sprawdzić, czy reguła z zakresem się wczytała.

Błędna albo wymijająca odpowiedź oznacza, że linijki brakuje, jest zakopana albo przeczy jej inny plik. Porównaj odpowiedzi z oczekiwanymi w pull requeście, który zmienia plik. Zatwierdza go właściciel pliku z CODEOWNERS; kontrola w CI i test świeżej sesji są dowodem, więc recenzent czyta diff i odpowiedzi agenta, a nie cały plik.

Kiedy dokumentacja powinna pochodzić z serwera MCP, a nie z pliku?

Dokumentacja bibliotek nie należy do pliku instrukcji. Jest długa, zmienia się z każdym wydaniem, a agent potrzebuje tylko strony o API, które właśnie wywołuje. Pobieraj ją na żywo.

Context7 (Upstash) udostępnia przez MCP dokumentację bibliotek dla konkretnych wersji. To serwer MCP jednego przeznaczenia z największą liczbą gwiazdek w naszym katalogu: 62,4 tys. na GitHubie (upstash/context7, odczyt 2026-09-26). Klucz API jest opcjonalny i podnosi limity zapytań.

Claude Code

claude mcp add --scope user --transport http context7 https://mcp.context7.com/mcp

Codex

codex mcp add context7 --url https://mcp.context7.com/mcp

Cursor

Dodaj to do .cursor/mcp.json w projekcie albo do ~/.cursor/mcp.json dla wszystkich projektów (ścieżki i format z README Context7):

{ "mcpServers": { "context7": { "url": "https://mcp.context7.com/mcp" } } }

Context7 ma też tryb CLI + Skills bez serwera MCP: npx ctx7 setup --claude (albo --cursor) instaluje zamiast tego skill (npm ctx7 0.5.12, sprawdzone 2026-09-26). Kompromis: skill nie dokłada do kontekstu definicji narzędzi i pobiera dokumentację przez CLI dopiero wtedy, gdy się uruchomi; serwer MCP udostępnia resolve-library-id i query-docs jako narzędzia, które agent może wywołać w każdej sesji.

Potem dodaj jedną linijkę do pliku instrukcji, np.: „For any Next.js or Drizzle API, fetch the docs with context7 before writing code”. Plik zostaje krótki, a dokumentacja aktualna. Tak samo traktuj dokumentację wewnętrzną spoza repozytorium, np. runbooki i rekordy decyzji architektonicznych (ADR): linkuj ją albo udostępniaj, nie wklejaj. Serwery MCP z dokumentacją porównują dostępne opcje.

Co się psuje, gdy dokumentacja służy za kontekst?

Agent ignoruje regułę, która wyraźnie jest w pliku. Zwykle plik jest za długi albo regule przeczy inna linijka. Nie dopisuj „IMPORTANT” ani pogrubień: dokumentacja pamięci Anthropic zaznacza, że dłuższe pliki obniżają przestrzeganie instrukcji, więc każda dodana linijka osłabia pozostałe. Usuń inne linijki, żeby zrobić miejsce, wynieś reguły o wąskim zakresie i powtórz test świeżej sesji. Jeśli reguła musi obowiązywać zawsze, egzekwuj ją hookiem albo bramką w CI zamiast zdaniem.

Codex po cichu gubi najbardziej szczegółowe instrukcje. W monorepo pliki AGENTS.md z korzenia i katalogów pośrednich zużywają budżet 32 KiB, a plik najbliższy katalogowi roboczemu zostaje ucięty. Sprawdź łączny rozmiar przez wc -c na każdym pliku w łańcuchu, najpierw odchudź plik z korzenia albo podnieś project_doc_max_bytes w config.toml. Jeśli Codex nie wczytuje żadnego AGENTS.md projektu, najpierw sprawdź zaufanie: od 0.150.0 niezaufany projekt, np. świeży klon albo checkout w CI, nie dostarcza go wcale.

Claude Code nie wczytuje twojego AGENTS.md. Każdy CLAUDE.md, .claude/CLAUDE.md lub CLAUDE.local.md w drzewie katalogów ma pierwszeństwo, a build starszy niż v2.1.277 nie ma tej funkcji. Dodaj @AGENTS.md na początku CLAUDE.md, co działa w każdej wersji, albo ustaw Project instructions w /config na claude-md-and-agents-md, żeby wczytywać oba pliki. Pamiętaj, że sam prywatny CLAUDE.local.md wystarczy, by wyłączyć AGENTS.md.

Zacommitowany plik każe agentowi zrobić coś szkodliwego. Pliki instrukcji są częścią łańcucha dostaw: pull request może dodać linijkę, która każe agentowi uruchomić skrypt albo wysłać gdzieś dane. Przeglądaj zmiany w plikach instrukcji jak kod, wymagaj akceptacji właściciela z CODEOWNERS i nigdy nie pozwalaj agentowi w CI, który ma dostęp do sekretów, wczytywać plików instrukcji z niezaufanej gałęzi.

Plik i repozytorium rozjeżdżają się po migracji. Kontrola rozjazdu wyłapie zmienione nazwy skryptów i usunięte ścieżki. Nie wyłapie zmienionej konwencji, więc dopisz „zaktualizuj AGENTS.md” do checklisty każdego pull requesta, który zmienia narzędzia, i powtórz pytania testowe.

Plik odrasta po każdym incydencie. Każdy postmortem dodaje linijkę i nic nie znika. Ustaw budżet linii w kontroli rozjazdu i przycinaj plik regularnie oraz przy każdej zmianie modelu, korzystając z protokołu ablacji.

Co dalej: dokumentacja jako kontekst

Przycinanie CLAUDE.md i AGENTS.md Kierunek odwrotny: sprawdź, które linijki wciąż zmieniają zachowanie agenta, i usuń resztę.

Okna kontekstu Dlaczego każda zawsze wczytywana linijka kosztuje w każdej turze i gdzie leżą limity.

Wzorce pamięci Auto memory i notatki między sesjami: co agent zapisuje sam, a co piszesz ty.

AGENTS.md i CLAUDE.md: zwięzły kontekst repozytorium Krótka checklista tego, co musi zawierać plik instrukcji w repozytorium.

Jedno źródło reguł dla każdego agenta Utrzymuj AGENTS.md, CLAUDE.md i reguły Cursora w zgodzie dzięki Ruler lub rulesync.

Repozytorium gotowe dla agentów Testy, skrypty i struktura, dzięki którym agent sam weryfikuje swoją pracę, a plik może zostać krótki.