Dokumentacja jako efektywny kontekst AI

Dokumentacja jako kontekst oznacza zakodowanie wiedzy specyficznej dla projektu — komend budowania, stylu kodu, decyzji architektonicznych — w plikach takich jak CLAUDE.md, .cursor/rules i AGENTS.md, które AI czyta automatycznie na początku każdej sesji, zamiast odkrywać ją na nowo, czytając kod. Skuteczne wersje pozostają konkretne, zwięzłe i aktualne, bo rozdęty lub nieaktualny plik bywa ignorowany albo aktywnie wprowadza asystenta w błąd.

Właśnie wdrożyłeś nowego programistę. Spędza pierwszy tydzień zadając te same pytania: “Jak uruchomię testy?” “Jaki jest proces wdrażania?” “Dlaczego używamy tego wzorca zamiast tamtego?” Teraz wyobraź sobie, że ten programista zadaje te same pytania każdego ranka, bo zapomina przez noc.

Tak wygląda praca z asystentem AI do kodowania bez dokumentacji-jako-kontekstu. Każda nowa sesja AI zaczyna od zera. Nie zna twoich komend budowania, konwencji zespołu ani decyzji architektonicznych. Odkrywa je ponownie czytając pliki — paląc tokeny kontekstu na informacje, które mógłbyś mu podać w 10 liniach.

Co wyniesiesz z tej sekcji o dokumentacji jako kontekście

• Szablon dla pliku konfiguracyjnego każdego narzędzia (CLAUDE.md, .cursor/rules, AGENTS.md)
• Wskazówki, co uwzględniać, a co pomijać
• Prompty do bootstrapowania dokumentacji z istniejącej bazy kodu
• Strategia utrzymywania aktualności dokumentacji w miarę ewolucji projektu

Trzy systemy instrukcji

Każde narzędzie ma własny mechanizm trwałej dokumentacji na poziomie sesji. Mimo różnych nazw, służą temu samemu celowi: przekazywanie AI wiedzy specyficznej dla projektu, której nie może wywnioskować z samego kodu.

Cursor

Project Rules znajdują się w .cursor/rules/ jako pliki markdown. Mogą być ograniczone wzorcem plików, stosowane zawsze lub wywoływane ręcznie. Cursor obsługuje zarówno .md (zwykły tekst, zawsze stosowany), jak i .mdc (niesie frontmatter dla description, globs i alwaysApply). Tylko pliki .mdc honorują te metadane — w zwykłej regule .md frontmatter jest ignorowany, a plik jest stosowany w niezmienionej postaci.

.cursor/rules/
  code-style.mdc         # alwaysApply: true we frontmatter
  testing.mdc            # Stosowane do plików testowych (przez globs)
  api-conventions.mdc    # Agent decyduje (przez description)
  deployment.md          # Zwykła reguła, @-wzmianka do ręcznego wywołania

Cursor obsługuje również User Rules (globalne preferencje w Cursor Settings) oraz AGENTS.md jako prostszą alternatywę dla .cursor/rules. Cursor czyta AGENTS.md natywnie w katalogu głównym projektu i w dowolnym podkatalogu, stosując go automatycznie przy pracy z plikami w tym katalogu lub jego dzieciach.

Kluczowe możliwości:

• Reguły ograniczone globami: Stosowane tylko przy pracy z pasującymi plikami
• Reguły decydowane przez agenta: Stosowane gdy Cursor uzna je za istotne
• Team Rules: Reguły organizacyjne zarządzane z dashboardu (plany Team/Enterprise)
• Zdalne reguły: Import reguł z repozytoriów GitHub, które są synchronizowane

Claude Code

Pliki CLAUDE.md to główny mechanizm instrukcji. Claude czyta je na początku każdej sesji.

project/
  CLAUDE.md              # Współdzielone instrukcje zespołowe
  CLAUDE.local.md        # Twoje osobiste preferencje (w gitignore)
  .claude/
    CLAUDE.md            # Alternatywna lokalizacja
    rules/
      code-style.md      # Modularne reguły
      testing.md         # Wskazówki tematyczne
      api/
        conventions.md   # Reguły specyficzne dla ścieżki

Kluczowe możliwości:

• Hierarchiczne ładowanie: pliki CLAUDE.md powyżej twojego katalogu roboczego ładują się w całości przy starcie; pliki w podkatalogach poniżej niego ładują się na żądanie, gdy Claude czyta stamtąd plik
• Reguły specyficzne dla ścieżki: Użyj frontmatter YAML z polem paths dla reguł warunkowych — to jedyne reguły, które pozostają poza kontekstem, dopóki nie zostanie dotknięty pasujący plik
• Importy: Odwołuj się do innych plików składnią @path/to/file. Uwaga: importy są rozwijane i ładowane przy starcie, więc pomagają w organizacji, ale nie redukują kontekstu
• Auto-pamięć: Claude zapisuje własne notatki do ~/.claude/projects/<project>/memory/
• Reguły użytkownika: ~/.claude/CLAUDE.md stosuje się do wszystkich projektów

Codex

Pliki AGENTS.md dostarczają instrukcje na poziomie globalnym i projektu. Codex czyta je na początku każdej sesji.

~/.codex/
  AGENTS.md              # Globalne domyślne dla wszystkich repozytoriów
  AGENTS.override.md     # Tymczasowe globalne nadpisanie

project/
  AGENTS.md              # Instrukcje na poziomie projektu
  services/
    payments/
      AGENTS.override.md # Nadpisania specyficzne dla serwisu

Kluczowe możliwości:

• Łańcuch pierwszeństwa: Globalny, potem root, potem zagnieżdżone — bliższe pliki nadpisują wcześniejsze
• Pliki override: AGENTS.override.md ma priorytet nad AGENTS.md w tym samym katalogu
• Zapasowe nazwy plików: Konfiguracja niestandardowych nazw plików instrukcji (np. TEAM_GUIDE.md)
• Limit rozmiaru: 32 KiB domyślnie, konfigurowalny przez project_doc_max_bytes. Obejmuje wyłącznie pliki projektowe — globalny ~/.codex/AGENTS.md się do niego nie liczy. Plik przekraczający limit jest ucinany od przodu, a wszystko po nim pomijane; ponieważ pliki ładują się od katalogu głównego, cięte są te najbliższe katalogowi startowemu. Loader ostrzega, ale nigdy w TUI

Co uwzględniać

Złota zasada: jeśli usunięcie tej linii spowodowałaby, że AI popełni błąd, zachowaj ją. Jeśli AI już robi to poprawnie bez tej linii, usuń ją.

Zawsze uwzględniaj

Kategoria	Przykład
Komendy budowania	npm run build, make test, docker compose up
Komendy testowe	npm test -- --testPathPattern=auth, pytest -x
Reguły stylu kodu odbiegające od domyślnych	“Używaj pojedynczych cudzysłowów”, “2-spacjowe wcięcia”
Wzorce architektoniczne	“Wzorzec Repository do dostępu do danych”, “Wszystkie route API w src/pages/api/”
Nieoczywiste ograniczenia	“Redis musi być uruchomiony do testów integracyjnych”, “Używaj pnpm, nie npm”
Konfiguracja środowiska	“Uruchom cp .env.example .env przed pierwszym budowaniem”

Nigdy nie uwzględniaj

Kategoria	Dlaczego
Standardowe konwencje językowe	AI już je zna
Opisy plik po pliku	AI może przeczytać pliki
Długie tutoriale lub wyjaśnienia	Za dużo tekstu sprawia, że AI ignoruje ważne reguły
Informacje, które często się zmieniają	Staną się przestarzałe i zmylą AI
Oczywiste praktyki	“Pisz czysty kod” nic nie wnosi

Generuj szkic, a nie plik

Najbardziej bezpośrednie badanie plików kontekstu w repozytorium (Gloaguen i in., ETH Zurich) w wersji v1 wykazało, że pliki kontekstu generowane przez LLM wypadały gorzej niż brak pliku, podczas gdy pisane przez ludzi dawały niewielki zysk. Abstrakt v2 idzie dalej i nie stwierdza ogólnej poprawy wskaźnika sukcesu zadań dla żadnego z tych rodzajów, przy średnio ponad 20% wyższym koszcie inferencji — choć ta średnia nie rozkłada się równo: drogim końcem są pliki generowane, a pisane przez ludzi wypadają niżej. Generowanie nadal jest użytecznym skrótem — wydobywa komendy i konwencje, których inaczej musiałbyś szukać — ale to, co produkuje, jest pierwszym szkicem do przycięcia, nigdy plikiem do wdrożenia. Poniższy prompt jest napisany zgodnie z tą zasadą.

Prompt do skopiowania: Szkic dokumentacji z istniejącej bazy kodu

Analyze this project and draft a [CLAUDE.md / .cursor/rules / AGENTS.md] file
for me to cut down. This is a draft, not a finished file.

Include only:
1. Build, test, and lint commands (try running them to verify they work), and
   flag which of them I could NOT have guessed from package.json
2. Code style conventions that differ from language defaults
3. Any non-obvious setup requirements or prerequisites
4. Decisions where the obvious approach is not the one this repo took, with the
   reason — those are the ones you would otherwise get wrong

Do NOT include a project overview, an architecture summary, or a file-by-file
map of where things live. I can derive all three by reading the code, and the
file map goes stale and starts actively misleading you.

Target under 100 lines. Every line must contain information you could NOT
figure out by reading the code. Mark any line you are unsure about rather than
padding the file to look thorough.

Pisanie skutecznych reguł

Różnica między dokumentacją, która działa, a dokumentacją ignorowaną przez AI, sprowadza się do konkretności i zwięzłości.

Źle: Ogólnikowo i rozwlekle

# Code Quality
We care deeply about code quality. Always write clean, maintainable,
well-documented code that follows best practices. Make sure to handle
errors properly and write tests for your code.

Dobrze: Konkretnie i wykonalnie

# Code Style
- Use ES modules (import/export), not CommonJS (require)
- Prefer async/await over .then() chains
- Error responses: { error: string, code: number } shape

# Testing
- Run single tests with: npm test -- --testPathPattern=<name>
- Never mock the database in integration tests
- Test file location: src/**/__tests__/<name>.test.ts

# Workflow
- Run npm run type-check after making code changes
- NEVER commit to main directly. Always create a branch.

Cursor

Dziel reguły na skupione pliki. Aby kontrolować, kiedy reguła jest stosowana, przez description lub globs, plik musi mieć rozszerzenie .mdc (np. api-conventions.mdc) — frontmatter w zwykłej regule .md jest ignorowany:

---
description: "API endpoint conventions"
globs:
  - "src/api/**/*.ts"
  - "src/routes/**/*.ts"
---

# API Conventions
- All endpoints return { data: T } on success, { error: string } on failure
- Use Zod for request validation
- Include rate limiting middleware on all public endpoints
- Reference @src/api/users.ts as the canonical example

Claude Code

Utrzymuj główny CLAUDE.md zwięzły. Użyj importów dla szczegółowej dokumentacji:

# Project: Acme API
See @README.md for project overview.
See @package.json for available commands.

# Commands
- Build: npm run build
- Test: npm test -- --testPathPattern=<name>
- Lint: npm run lint

# Conventions
- TypeScript strict mode, no @ts-ignore
- All API routes in src/pages/api/
- Database queries use Drizzle ORM (see @src/lib/db/schema.ts)

Użyj .claude/rules/ dla modularnych reguł tematycznych. Reguły specyficzne dla ścieżki używają frontmatter YAML:

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

# API Rules
- Validate all input with Zod schemas
- Return consistent error shapes

Codex

Utrzymuj AGENTS.md skupiony na najważniejszych informacjach:

# Acme API

## Commands
- Build: npm run build
- Test: npm test -- --testPathPattern=<name>
- Lint: npm run lint

## Working Agreements
- Always run tests after modifying code
- Use pnpm for dependency management
- TypeScript strict mode, no any types
- API routes follow RESTful conventions in src/routes/

Użyj zagnieżdżonego AGENTS.md dla nadpisań specyficznych dla serwisu, które nie powinny być stosowane globalnie.

Prompt do skopiowania: Audyt i poprawa istniejącej dokumentacji

Read our [CLAUDE.md / .cursor/rules / AGENTS.md] files. Evaluate them:

1. Are there any rules the AI would follow correctly without being told?
   (Remove these -- they waste context)
2. Are there any rules that are too vague to be actionable?
   (Make them specific)
3. What important commands or conventions are MISSING?
   (Add them based on package.json, Makefile, etc.)
4. Is the file too long? Claude Code's docs target under 200 lines per file and
   Cursor's target under 500 per rule, but on a frontier model you can usually
   get the main file well under 100. Report the current count.

Show me the improved version with your changes explained.

Utrzymywanie aktualności dokumentacji

Dokumentacja, która staje się przestarzała, jest gorsza niż brak dokumentacji — aktywnie wprowadza AI w błąd.

1. Przeglądaj co miesiąc, a ponownie przy każdej zmianie modelu. To zmiana modelu jest wyzwalaczem, który naprawdę ma znaczenie — mocniejszy model potrzebuje mniej rusztowania niż ten, pod który pisałeś plik, a tańszy potrzebuje więcej.
2. Traktuj jak kod. Commituj pliki instrukcji do git. Przeglądaj zmiany w PR. Pozwól zespołowi kontrybuować.
3. Dodawaj regułę dopiero, gdy ten sam błąd powtórzy się dwa razy. Po trudnej sesji debugowania kusi, żeby od razu poprosić AI o napisanie reguły, ale pojedyncza wpadka to szum. Każda linia jest czytana przy każdej turze, na zawsze, więc reguła dopisana na wyrost kosztuje cię trwale za problem, którego być może nie masz.
4. Kasuj więcej, niż dodajesz. Przycinaj według harmonogramu, a nie tylko wtedy, gdy coś się zepsuje. Własny wpis Anthropic o inżynierii kontekstu dla generacji Claude 5 opisuje usunięcie ponad 80% promptu systemowego Claude Code bez mierzalnej straty, a członkom zespołu przypisuje się rekomendację, by okresowo kasować pliki instrukcji w całości i dopisywać z powrotem wyłącznie to, co bez nich w sposób sprawdzalny się psuje. Tę mocniejszą wersję traktuj jako relacjonowaną rekomendację, a nie udokumentowaną politykę — oficjalna dokumentacja nadal ujmuje to jako dopisanie reguły po drugim wystąpieniu tego samego błędu. Pełny protokół, tak czy inaczej, znajdziesz w Przycinanie CLAUDE.md i AGENTS.md.
5. Obserwuj ignorowane reguły. Jeśli AI wciąż łamie regułę, plik jest prawdopodobnie za długi i reguła gubi się. Przycinaj agresywnie.

Prompt do skopiowania: Dodanie lekcji do dokumentacji projektu

We just discovered that [DESCRIBE THE ISSUE]. Add a rule to our
[CLAUDE.md / .cursor/rules / AGENTS.md] to prevent this in the future.

The rule should be:
- One or two sentences maximum
- Specific and actionable (not "be careful with X")
- Placed in the most relevant section of the file

Gdy dokumentacja jako kontekst zawodzi

Plik jest za długi i reguły są ignorowane. To najczęstszy problem, a rozwiązanie jest wbrew intuicji: skróć plik, nie dokładaj wyróżnień. Przepisanie reguły pogrubieniem i słowem “IMPORTANT” z przodu to odruch, który rzadko działa, bo dokładanie instrukcji pogarsza przestrzeganie wszystkich, nie tylko nowej. Właściwą poprawką jest zwykle skasowanie czterech innych reguł. Przenoś szczegółowe wytyczne do plików tematycznych (.claude/rules/ z globem paths, ograniczone .cursor/rules/), a jeśli reguła naprawdę musi być przestrzegana, a nie tylko rozważona, zrób z niej hook zamiast zdania.

Różni członkowie zespołu dodają sprzeczne reguły. Traktuj pliki instrukcji jak kod: przeglądaj zmiany, rozwiązuj konflikty, utrzymuj jedno źródło prawdy. W Claude Code użyj głównego CLAUDE.md do reguł zespołowych i CLAUDE.local.md do osobistych preferencji.

AI stosuje przestarzałe reguły. Jeśli twój framework testowy się zmienił, ale plik instrukcji wciąż odwołuje się do starego, AI będzie używać złych komend i się pogubi. Regularnie audytuj.

Za dużo plików reguł w monorepo. Przy zagnieżdżonych plikach instrukcji w pakietach, łączny kontekst może przekroczyć limity. W Codex project_doc_max_bytes (domyślnie 32 KiB) ogranicza sumę plików projektowych — plik przekraczający limit jest ucinany od przodu, a każdy po nim pomijany, bez żadnego ostrzeżenia w TUI. Ponieważ pliki są konkatenowane od katalogu głównego, cięte są te najbliższe katalogowi startowemu, więc tracisz najbardziej szczegółowe instrukcje, a ogólne z korzenia przeżywają. W Claude Code tylko pierwsze 200 linii auto-pamięci MEMORY.md jest ładowanych. Utrzymuj każdy plik skupiony.

Dokąd dalej z dokumentacją jako kontekstem

Przycinanie CLAUDE.md i AGENTS.md Kierunek odwrotny: co skasować, co przenieść do plików w podkatalogach i skilli, oraz dziewięć promptów, które wykonają cięcie.

Wzorce pamięci Wyjdź poza statyczne pliki dzięki auto-pamięci, wyuczonym wzorcom i wiedzy międzysesyjnej.

Indeksowanie bazy kodu Jak wyszukiwanie i indeksowanie uzupełnia dokumentację w znajdowaniu odpowiedniego kodu.

Organizacja plików Zorganizuj projekt tak, aby AI mogło nawigować z minimalną dokumentacją.