CLAUDE.md - kontrakt z AI, który koduje jak nadgorliwy stażysta

Persystentny kontekst zamiast powtarzania promptów #

Modele językowe nie utrzymują pamięci między sesjami. Cały kontekst musi być załadowany do okna kontekstowego przed każdą inferencją. Standardowy mechanizm „instrukcji systemowych” w API to jedno - ale dla pracy w konkretnym repozytorium potrzebujemy czegoś bardziej wbudowanego: plik w repozytorium, który narzędzie automatycznie czyta.

Stąd konwencja:

• Claude Code czyta CLAUDE.md z root projektu (i nadrzędnych katalogów - rekursywnie).
• Cursor czyta .cursorrules lub .cursor/rules/*.mdc.
• Continue używa config.json z polem systemMessage lub plików rules.
• Aider czyta .aiderules.
• OpenAI Codex CLI: pliki w ~/.codex/ plus AGENTS.md w repo.

Wszystkie sprowadzają się do tej samej idei: plik w repo definiuje, jak narzędzie ma się zachowywać. Reszta różnic to dialekt.

Struktura skutecznego CLAUDE.md #

Dobry plik CLAUDE.md ma kilka sekcji, w mniej-więcej tej kolejności:

1. Project context - co to za projekt, jakie warstwy, co jest w fazie eksperymentalnej.
2. Tech stack - języki, frameworki, version constraints.
3. Code style - importy, naming, konwencje.
4. Build & test commands - jak uruchomić linter, testy, dev server.
5. Hard rules - cztery filary Karpathy’ego, sformułowane jednoznacznie.
6. Don’t do this - explicit lista anty-wzorców z dotychczasowych incydentów.

4 filary - sformułowane technicznie #

Think before coding #

Model ma stop condition na ambiguity. Definicja niejednoznaczności:

• Prompt nie precyzuje zachowania w jednym z poniższych przypadków: null argument, pusta kolekcja, błąd I/O, brak uprawnień, race condition.
• Istnieje więcej niż jedna rozsądna implementacja, których behavioralne kontrakty się różnią.
• Wymagana zmiana wpływa na publiczne API (breaking change vs. additive).

Zachowanie: model formułuje pytanie z konkretnymi opcjami i zatrzymuje się przed pisaniem kodu.

Simplicity first #

Operacjonalizacja:

• No premature abstraction. Interfejs/klasa abstrakcyjna wymaga ≥ 2 rzeczywistych implementacji w aktualnym kodzie.
• No anticipation. Parametry, flagi, opcje konfiguracyjne tylko jeśli są wykorzystywane przez aktualne wywołanie.
• Line budget. Jeśli rozwiązanie alternatywne istnieje w < 50% linii i nie traci ważnej własności (testowalność, wydajność, czytelność) - jest preferowane.

To literalnie YAGNI z Extreme Programming, ale wymuszone na poziomie generation-time.

Surgical changes #

Diff hygiene:

• Każda zmieniona linia musi być uzasadniona w prompcie.
• No drive-by edits. Nie poprawiamy nazw, nie reorganizujemy importów, nie dodajemy brakujących typów - chyba że to wprost żądanie.
• No reformat. Jeśli plik ma niespójne wcięcia lub stary var x = ..., zostawiamy.
• Match existing style. Jeśli kod używa function expression zamiast arrow, model używa tego samego.

To pierwszy filar, na którym klasyczne LLM-y odpadają najbardziej, bo są wytrenowane na „czystym” kodzie z OSS-a i mają silną tendencję do unifikacji stylu.

Goal-driven execution #

Zamiast „write a function that does X”, piszesz:

Acceptance criteria (test-driven):
1. Test in tests/payment_test.cs::Should_RejectExpiredCard must pass.
2. Test ::Should_AcceptValidCard must pass.
3. dotnet build must succeed with zero warnings (TreatWarningsAsErrors=true).
4. dotnet format --verify-no-changes must succeed.

Run all four checks after each iteration. Continue until all pass.

Model wykonuje pętlę autonomicznie. Claude Code (jak również Cursor’s agent mode i Aider) ma do tego natywne wsparcie - może odpalić bash, sprawdzić exit code, przeczytać stderr.

Gotowy szablon #

<!-- title: CLAUDE.md -->
# Project: AcmePayments

## Stack
- .NET 9, C# 13, ASP.NET Core minimal API
- PostgreSQL 16 via Npgsql
- xUnit + FluentAssertions for tests
- Build tools: dotnet, just (Justfile)

## Commands
- Build: `just build` (= `dotnet build -c Release -warnaserror`)
- Test: `just test` (= `dotnet test --no-restore`)
- Lint: `just lint` (= `dotnet format --verify-no-changes`)
- Run: `just run`
- Migration: `just migrate <name>`

## Hard rules

### 1. Think before coding
Before writing any code, identify any ambiguity in the request. If multiple
reasonable interpretations exist (null handling, error semantics, edge cases),
STOP and ask. Do not silently pick one.

### 2. Simplicity first
- No premature abstractions. Interfaces require ≥ 2 implementations in this repo.
- No "future-proofing". If a feature isn't requested, it doesn't exist.
- If a 50-line solution exists, the 200-line one is wrong.

### 3. Surgical changes
- Change ONLY what the request requires.
- Do not reformat, rename, or "improve" adjacent code.
- Match existing style, even if it's not your preference.
- Each diff line must be justified by the prompt.

### 4. Goal-driven execution
- Run `just test` after each meaningful change.
- A task is not done until ALL of these pass:
  - `just build`
  - `just test`
  - `just lint`
- If anything fails, fix the root cause. Do not change the test to match the code.

## Don't do this
- Don't add `try/catch` that swallows exceptions silently.
- Don't add logging unless the prompt asks for it.
- Don't introduce new NuGet packages without confirmation.
- Don't write commit messages on my behalf - I'll write them.
- Don't push to remote.

## Project structure
- `src/Api/` - HTTP layer (controllers, middleware)
- `src/Domain/` - business logic, no framework dependencies
- `src/Infrastructure/` - DB, external APIs
- `tests/` - mirrors src structure

## Notes for the agent
- "Production" = `main` branch + `release/*` tags. Treat as immutable.
- We don't use feature flags - if it's merged, it's live.
- Database migrations are forward-only. No `down` script.

Hierarchia plików #

Claude Code (i większość agentów) ładuje pliki rekursywnie z góry:

• ~/.claude/CLAUDE.md - globalne preferencje użytkownika.
• <repo-root>/CLAUDE.md - reguły projektu.
• <repo-root>/<subfolder>/CLAUDE.md - reguły specyficzne dla podsystemu.

Konflikt rozstrzyga najgłębszy plik. Pozwala to mieć ogólne reguły w root, a w katalogu z eksperymentalnym kodem złagodzić niektóre (np. „w tym katalogu możesz dodawać abstrakcje swobodnie - to playground”).

Anty-wzorce #

• Plik z 800 linii - model dostaje go w kontekście za każdym razem. Każda linia kosztuje tokeny i rozcieńcza istotne reguły. Trzymaj < 200 linii.
• Wielowariantowe „it depends” - model nie umie miękko zinterpretować „raczej preferuj X, ale czasem Y”. Jeśli reguła nie jest deterministyczna, lepiej jej w ogóle nie pisać.
• Sprzeczne reguły - model wybiera tę, która brzmi pewniej, niekoniecznie tę, którą miałeś na myśli. Czytaj plik po napisaniu pod kątem konfliktów.
• Dezaktualizacja - reguła „nie używamy biblioteki X” po roku jest tym, co model rozumie jako prawdę, mimo że X jest już głównym frameworkiem projektu. Dorzuć CLAUDE.md do code review.

Integracja z Claude Code #

Claude Code szuka CLAUDE.md automatycznie:

# title: terminal
cd ~/projects/acme-payments
claude  # CLI sam załaduje ./CLAUDE.md i ~/.claude/CLAUDE.md

Można też wymusić konkretny kontekst flagą --context (przy debugowaniu reguł).

Plik nie wymaga restartu - przy każdej nowej sesji jest przeładowywany. Edycja CLAUDE.md w trakcie pracy z agentem ma efekt przy następnym promptcie.

Skrótowo #

CLAUDE.md to twardy kontekst, ładowany automatycznie przy każdej sesji. Cztery filary Karpathy’ego (think-before-coding, simplicity-first, surgical-changes, goal-driven-execution), spakowane do struktury stack → commands → hard rules → don’t-do. Trzymaj < 200 linii, unikaj „it depends”, aktualizuj jak code style guide. To narzędzie disciplinarne, nie kosmetyczne.