Wzorce · 10 / 15

CLAUDE.md i AGENTS.md

Najważniejszy plik w projekcie z AI: co w nim pisać, a czego nie.

Stan na: 7.11.2026

Najważniejszy plik w projekcie z AI

Każde narzędzie AI do kodu czyta plik z instrukcjami projektu na starcie sesji. Bez niego AI zgaduje. Z nim wie, jak pracujesz.

Narzędzie	Plik
Claude Code	`CLAUDE.md` albo `.claude/CLAUDE.md`, reguły w `.claude/rules/`, może też czytać `AGENTS.md`
Codex, Cursor, Gemini CLI, Aider i inne	`AGENTS.md` (Gemini CLI ma też `GEMINI.md`)
GitHub Copilot	`.github/copilot-instructions.md`, `.github/instructions/*.instructions.md`, `AGENTS.md`
Cursor	`.cursor/rules` albo `AGENTS.md`

Traktuj ten plik jak instrukcję dla nowej osoby w zespole: to samo, co powiedziałbyś jej pierwszego dnia.

W Claude Code polecenie /init analizuje kod i tworzy pierwszą wersję CLAUDE.md. Gdy plik już istnieje, proponuje poprawki.

Sześć sekcji

1. Opis projektu (dwie linie)

# Projekt: Faktury
API do obsługi faktur. Hono, Cloudflare Workers i D1.

2. Stos

## Stos
- Hono na Cloudflare Workers
- D1 (SQLite) z Drizzle ORM
- Zod do walidacji
- Vitest do testów

3. Struktura

## Struktura
- src/routes/  trasy API, jeden plik na zasób
- src/db/      schemat i migracje
- src/lib/     pomocnicze funkcje

4. Konwencje

## Konwencje
- eksporty nazwane, bez default
- każda trasa waliduje wejście schematem Zod
- błędy zwracamy jako { error, kod }

5. Polecenia i testy

## Polecenia
- `npm run dev`: serwer lokalny
- `npm test`: testy
- `npm run deploy`: wdrożenie
Przed commitem zawsze `npm test`.

6. Pułapki i zakazy

## Nie rób
- nie instaluj nowych zależności bez pytania
- nie używaj typu any

## Pułapki
- migracje D1 tylko przez wrangler CLI

Ta sekcja rośnie najszybciej. Za każdym razem, gdy AI popełni ten sam błąd drugi raz, dopisz go tutaj.

Przykład minimalny

# Portfolio
Astro i Tailwind, wdrożenie na Cloudflare Pages.

Dev: `npm run dev`. Build: `npm run build`.
Treści w src/content/ jako MDX.
Komponenty Astro, nie React (zero JS w przeglądarce).

Nawet dziesięć linii działa lepiej niż nic.

Warstwy w Claude Code

Poziom	Plik	Dla kogo
Organizacja	plik zarządzany przez IT, np. `/etc/claude-code/CLAUDE.md` na Linuksie	cała firma
Użytkownik	`~/.claude/CLAUDE.md`	Ty, we wszystkich projektach
Projekt	`./CLAUDE.md` albo `./.claude/CLAUDE.md`	zespół, przez Git
Lokalny	`./CLAUDE.local.md` (dopisz do `.gitignore`)	Ty, w tym projekcie

Pliki się nie nadpisują, tylko łączą. Claude czyta je od katalogu głównego w dół, więc instrukcje bliżej miejsca pracy czyta na końcu. Pliki CLAUDE.md z podkatalogów ładuje dopiero wtedy, gdy zaczyna pracować w danym katalogu.

Dodatkowo:

@sciezka/do/pliku importuje inny plik do CLAUDE.md;
.claude/rules/*.md dzieli instrukcje na tematy, a reguły z polem paths ładują się tylko przy pracy z pasującymi plikami;
automatyczna pamięć zapisuje to, czego Claude nauczył się z Twoich poprawek.

Antywzorce

Za długi. Dokumentacja Claude Code radzi trzymać się poniżej 200 linii na plik. Dłuższy plik zjada kontekst i obniża posłuszeństwo. Szczegóły przenieś do reguł z paths.
Za ogólny. „Pisz czysty kod” nic nie mówi. „Używaj wczesnych returnów” mówi.
Sprzeczny. Dwie sprzeczne zasady sprawią, że model wybierze jedną losowo.
Z sekretami. Plik trafia do repozytorium. Klucze trzymaj w .env, w pliku wpisz tylko nazwy zmiennych.
Nieaktualny. Zmieniła się konwencja albo struktura? Popraw plik od razu.

Instrukcje w CLAUDE.md to kontekst, nie twarda blokada. Jeśli coś ma być zablokowane bez wyjątków, użyj hooka albo ustawień uprawnień.

Jeden plik dla wielu narzędzi

Pracujesz z kilkoma narzędziami? Trzymaj wspólne zasady w AGENTS.md, które czyta większość z nich, a w CLAUDE.md zostaw to, co dotyczy tylko Claude Code, albo zaimportuj AGENTS.md przez @AGENTS.md.

Pielęgnacja

Popraw plik, gdy:

dochodzi duża zależność;
zmienia się konwencja;
AI drugi raz trafia na tę samą pułapkę;
zmienia się struktura katalogów.

Najlepszy CLAUDE.md czyta się jak notatkę, którą zostawiłbyś sobie przed tygodniowym urlopem. Krótko, praktycznie, bez waty.

Dokumentacja: pamięć w Claude Code, AGENTS.md.