CLAUDE.md i AGENTS.md: co wpisuję po 42 projektach

👁 122 przeczytań

Na moim dysku leżą 42 pliki z instrukcjami dla agentów AI: 16 plików CLAUDE.md i 26 plików AGENTS.md, każdy w folderze innego projektu. Najkrótszy ma jedną linię, najdłuższy 402. Ten najdłuższy jest dwa razy dłuższy, niż zaleca Anthropic, i od niego zacznę, bo dobrze pokazuje, co do takiego pliku trafia naprawdę.

Czym jest CLAUDE.md

To zwykły plik Markdown, który Claude Code czyta na początku każdej sesji. Każda rozmowa z agentem startuje z pustą pamięcią, więc wszystko, czego nie da się wyczytać z kodu, trzeba mu powiedzieć od nowa. CLAUDE.md robi to za ciebie: komendy do testów, zasady projektu, rzeczy, których agentowi nie wolno, i pułapki, na które już się nadziałeś.

Dokumentacja Claude Code mówi wprost, że to kontekst, a nie twarda konfiguracja. Agent zwykle się do pliku stosuje, ale nie musi. Jeśli coś ma być zablokowane zawsze, na przykład kasowanie plików albo wdrożenie na serwer, służą do tego hooki i uprawnienia w ustawieniach, nie zdanie w CLAUDE.md.

Gdzie leży i co się wczytuje

Plików może być kilka naraz. Claude Code nie wybiera jednego, tylko skleja wszystkie znalezione w kolejności od najogólniejszego do najbliższego folderu, w którym pracujesz.

Pliki z folderów powyżej miejsca, w którym uruchomisz agenta, wczytują się od razu. Pliki z podfolderów dopiero wtedy, gdy agent zacznie w nich czytać albo zmieniać pliki. Dzięki temu w dużym repozytorium instrukcje dla frontendu nie zajmują miejsca, kiedy agent grzebie w bazie danych.

Pierwszą wersję możesz wygenerować komendą /init. Claude przejrzy kod i zapisze komendy oraz konwencje, które sam znajdzie. To dobry start, ale ja zawsze dopisuję resztę ręcznie, bo najcenniejsze linie to te, których z kodu wyczytać się nie da.

Mój najdłuższy plik: 402 linie

Dokumentacja zaleca, żeby jeden CLAUDE.md miał mniej niż 200 linii, bo dłuższy plik zjada kontekst i agent gorzej się go trzyma. Mój plik w projekcie Jantaris ma 402 linie i 46 095 bajtów. Z 16 plików CLAUDE.md tylko ten przekracza próg, mediana to 35 linii.

Nie powstał od razu. Rósł o kolejne pułapki, wpisywane po każdym błędzie: jak serwer cache’uje obrazy i dlaczego podmiana pliku pod tą samą nazwą dociera do ludzi dopiero po tygodniu, ile rejestracji na godzinę wpuszcza zabezpieczenie i jak testy muszą je resetować, gdzie stoi serwer i jak idzie poczta. Każda linia to ślad po konkretnym problemie. Razem zrobiło się z tego za dużo.

Moje zdanie jest takie: CLAUDE.md to nie dokumentacja projektu, tylko mapa min. Opis tego, jak działa aplikacja, agent znajdzie w kodzie i w README. W CLAUDE.md ma być to, czego w kodzie nie widać, a co już raz wybuchło. Gdy plik przekracza 200 linii, dzielę go na pliki tematyczne w .claude/rules/. Import przez @plik.md pomaga tylko w porządku, bo zaimportowany plik i tak wczytuje się w całości.

Plik, który pokazuję w kursie: 34 linie

Dobry przykład to CLAUDE.md projektu „Baza napraw”, aplikacji dla warsztatu samochodowego, którą budujemy od zera w moim kursie SaaS w weekend z Claude Code. Cały plik, bez skrótów:

# Baza napraw - notatki dla agenta

Produkt, ekrany i reguły: @SPEC.md
Buduj tylko sekcję MUSI BYĆ z ZAKRES.md. Pomysł spoza niej dopisz
do PÓŹNIEJ z warunkiem powrotu i zapytaj mnie.

## Stack
- Node 22.13+, zero zależności npm: node:http, node:sqlite, node:test, fetch.
- SQLite w data/app.db, migracje w migrations/NNN_nazwa.sql.
- HTML renderowany na serwerze, w przeglądarce czysty JS.

## Komendy
- npm run dev                 serwer na porcie 8080, restart po zmianie pliku
- npm test                    node --test "test/*.test.js" (glob w cudzysłowie)
- npm run reset               baza od zera + dane testowe + konta testowe
- python tools/zrzuty.py URL  zrzuty 1440 px i 390 px do data/shots/

## Zasady
- Kwoty w groszach jako INTEGER. Nigdy liczby zmiennoprzecinkowe.
- Limity planów (R1-R3) sprawdza serwer. Przeglądarka tylko je pokazuje.
- Każda reguła R ze SPEC.md ma test z jej numerem w nazwie.
- Pliki tekstowe zapisuj z końcami linii LF.
- W treściach tylko dywiz "-". Test sprawdza wszystkie szablony.

## Zakazy
- Nie czytaj .env. Nie wdrażaj. Nie rób git push, git reset ani git clean.
- Nie uruchamiaj testów na data/app.db (testy mają bazę w pamięci).
- Nie importuj danych fabrycznych (Autodata, HaynesPro, portale producentów):
  licencje producentów i ochrona baz danych w UE.

## Pułapki
- Git Bash przerabia ścieżki: MSYS_NO_PATHCONV=1 przed poleceniem z /...
- Pliki z wyrażeniami regularnymi zapisuj narzędziem do plików,
  nie heredokiem w bashu (gubi backslashe).

Każda sekcja ma swój powód:

• Odesłanie do specyfikacji. Opis produktu siedzi w SPEC.md, a CLAUDE.md go tylko importuje. Linia o sekcji MUSI BYĆ trzyma agenta przy zakresie. Bez niej po godzinie dostajesz funkcje, o które nikt nie prosił.
• Komendy z dokładną składnią. Glob w cudzysłowie przy testach to szczegół składni, który łatwo zgubić, a od niego zależy, czy uruchomią się wszystkie pliki z testami.
• Zasady, które da się sprawdzić. Kwoty w groszach, limity po stronie serwera, test do każdej reguły. Żadnych „pisz czysty kod”, bo tego nie da się zweryfikować.
• Zakazy. Te najważniejsze dubluję w ustawieniach uprawnień, bo plik jest tylko prośbą.
• Pułapki środowiska. Windows i Git Bash psują ścieżki zaczynające się od ukośnika. Agent o tym nie wie, dopóki komenda mu nie zawiedzie.

Linia, która kosztowała mnie przebieg redakcji

Najlepiej widać to na przykładzie. 30 października przy redakcji tekstów magazynu DYGOT skrypt, który pobiera aktualny stan z serwera, został uruchomiony między poprawkami a wgraniem. Nadpisał lokalne zmiany i pierwszy przebieg redakcji przepadł. Od tamtego dnia w pliku instrukcji tego projektu jest zdanie: „Uruchamiaj TYLKO przed pracą - między edycją a wgraniem nadpisze twoje zmiany”. Żaden generator by go nie napisał, bo z kodu skryptu nie wynika, kiedy wolno go odpalić.

AGENTS.md, czyli to samo dla innych agentów

AGENTS.md to taki sam plik z instrukcjami, tylko pod nazwą, którą czytają różne narzędzia: Codex od OpenAI, Cursor, Gemini CLI, agent GitHub Copilot i kilkanaście innych. Format prowadzi Agentic AI Foundation przy Linux Foundation. Mam ich 26 i są krótkie, mediana to 8 linii, bo większość opisuje pojedyncze zadania graficzne dla Codexa.

Claude Code też umie czytać AGENTS.md, od wersji 2.1.277. Domyślnie robi to tylko wtedy, gdy w projekcie nie ma pliku CLAUDE.md. Jeśli są oba, Claude czyta swój, a AGENTS.md pomija. Żeby oba narzędzia dostawały te same zasady, najprościej trzymać je w AGENTS.md i dodać w CLAUDE.md jedną linię z importem @AGENTS.md. Jak przenieść cały zestaw, także skille i serwery MCP, opisałem w tekście jak przenieść Claude Code do Codexa.

W projektach, nad którymi pracują na zmianę Claude i Codex, mam jeszcze jedną zasadę na końcu pliku: po pracy dopisz wpis do wspólnego dziennika agentów, z datą, nazwą agenta i listą zmian. Następny agent czyta dziennik przed startem i wie, co zmienił poprzedni. To prostsze niż synchronizowanie pamięci obu narzędzi.

Czego nie wpisuję

• Kluczy i haseł. Plik projektu często trafia do repozytorium. W moich plikach jest raczej zakaz czytania .env niż jego zawartość.
• Struktury folderów. Agent zobaczy ją sam w kilka sekund, a opis w pliku zestarzeje się przy pierwszej zmianie.
• Ogólników. „Dbaj o jakość” nic nie zmienia. „Każda reguła ma test z jej numerem” zmienia.
• Sprzecznych zasad. Dokumentacja ostrzega, że przy dwóch sprzecznych instrukcjach Claude może wybrać dowolną. Raz na jakiś czas czytam swoje pliki i wyrzucam to, co już nie obowiązuje.
• Notatek dla ludzi. Jeśli muszą zostać, wstawiam je w komentarz HTML <!-- -->. Claude Code wycina takie komentarze przed wczytaniem pliku, więc nie kosztują kontekstu.

Od czego zacząć

Jeśli zaczynasz z Claude Code, nie pisz CLAUDE.md na zapas. Uruchom /init, zostaw to, co ma sens, i dopisuj po jednej linii za każdym razem, gdy agent popełni ten sam błąd drugi raz. Po tygodniu masz plik, który opisuje twój projekt, a nie projekt z poradnika. Instalację i pierwsze kroki opisuję w przewodniku Claude Code: instalacja, a koszty planów w tekście ile kosztuje Claude Code.

Specyfikację i CLAUDE.md piszemy krok po kroku w kursie SaaS w weekend z Claude Code: 30 lekcji, od sprawdzenia popytu na pomysł, przez bazę, logowanie i płatności, po wdrożenie na własny serwer. Kurs jest też w paczce kombAIn razem z 27 innymi kursami z PROMPTOWY LAB.

Czytasz Promptowego częściej? Dodaj go do preferowanych źródeł w Google, a nowe teksty będą wyżej w Twoich wynikach.

Źródła i data sprawdzenia

Stan na 6.11.2026.

• Pliki CLAUDE.md i AGENTS.md z moich projektów (42 pliki po odrzuceniu kopii i cudzego repozytorium), policzone 6.11.2026
• Claude Code - dokumentacja: How Claude remembers your project (CLAUDE.md, AGENTS.md, importy, limit 200 linii)
• AGENTS.md - opis formatu
• PROMPTOWY LAB - program kursu SaaS w weekend z Claude Code