Dokumentacja jako efektywny kontekst AI

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.

Czego się nauczysz

• 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/rules/
  code-style.md          # Stosowane zawsze
  testing.mdc            # Stosowane do plików testowych (przez globs)
  api-conventions.md     # Agent decyduje na podstawie trafności
  deployment.md          # Tylko ręczne wywołanie

Cursor obsługuje również User Rules (globalne preferencje w Cursor Settings) oraz AGENTS.md jako prostszą alternatywę dla .cursor/rules.

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: CLAUDE.md w katalogach nadrzędnych ładuje się automatycznie
• Reguły specyficzne dla ścieżki: Użyj frontmatter YAML z polem paths dla reguł warunkowych
• Importy: Odwołuj się do innych plików składnią @path/to/file
• 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

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

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

Analyze this project and generate a [CLAUDE.md / .cursor/rules / AGENTS.md] file.

Include:
1. Build, test, and lint commands (try running them to verify they work)
2. Key architectural patterns you observe
3. Code style conventions that differ from language defaults
4. Important file locations and their purposes
5. Any non-obvious setup requirements

Keep it under 50 lines. Every line should contain information you could NOT
figure out by just reading the code. Prioritize commands and constraints
over descriptions.

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. Użyj frontmatter do kontroli, kiedy są stosowane:

---
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? (Target under 50 lines for the main file)

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. Zaplanuj 10-minutowy przegląd plików instrukcji. Usuń reguły, które już nie obowiązują. Dodaj reguły dla błędów, które AI wciąż popełnia.
2. Traktuj jak kod. Commituj pliki instrukcji do git. Przeglądaj zmiany w PR. Pozwól zespołowi kontrybuować.
3. Użyj AI do utrzymywania. Po trudnej sesji debugowania poproś AI o dodanie reguły zapobiegającej temu samemu problemowi następnym razem.
4. 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 coś nie działa

Plik jest za długi i reguły są ignorowane. To najczęstszy problem. Utrzymuj główny plik instrukcji poniżej 50 linii. Przenoś szczegółowe wytyczne do plików tematycznych (.claude/rules/, ograniczone .cursor/rules/). Użyj wyróżnienia (“IMPORTANT:”, “YOU MUST”) dla kluczowych reguł, ale oszczędnie — jeśli wszystko jest ważne, nic nie jest.

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 ustawienie project_doc_max_bytes (domyślnie 32 KiB) ogranicza całość. W Claude Code tylko pierwsze 200 linii auto-pamięci MEMORY.md jest ładowanych. Utrzymuj każdy plik skupiony.

Co dalej

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ą.