AGENTS.md i HUMAN.md: wyjaśnienie

Czym jest AGENTS.md

AGENTS.md to zwykły plik Markdown znajdujący się w katalogu głównym repozytorium. Określa on, jak agent kodujący ma pracować nad danym projektem. Oficjalna witryna opisuje go jako „README dla agentów: dedykowane, przewidywalne miejsce do przekazywania kontekstu i instrukcji potrzebnych agentom kodującym AI do pracy nad projektem”. Za ten format odpowiada Agentic AI Foundation działająca przy Linux Foundation. Z pliku korzysta ponad dwudziestu agentów, w tym Codex, Cursor, Jules, Devin i GitHub Copilot (stan na July 2026).

Powód wprowadzenia tej konwencji jest praktyczny. Nowa osoba w zespole czyta README, zgaduje polecenie kompilacji i pyta kogoś, gdy zgadywanie okazuje się błędne. Agent nie może pytać. Zgaduje, uruchamia npm test w projekcie używającym pnpm test, odczytuje błąd i próbuje czegoś innego. Każdy z tych tokenów generuje koszt. Jednokrotne zapisanie właściwego polecenia eliminuje całą tę klasę błędów.

Nie ma wymaganych pól. Witryna wyraźnie to stwierdza: „AGENTS.md to po prostu standardowy Markdown. Można używać dowolnych nagłówków; agent analizuje tekst, który został mu przekazany”. To cała specyfikacja. Wartość nie wynika z formatu. Wynika z umieszczenia pliku w ścieżce, której każde narzędzie już szuka.

Gdzie umieścić plik i który plik ma pierwszeństwo

Pierwszy plik należy umieścić w katalogu głównym repozytorium. W monorepo można dodać kolejne pliki w poszczególnych podprojektach. Obowiązuje prosta zasada: „agents automatycznie odczytuje najbliższy plik w drzewie katalogów, dlatego pierwszeństwo ma plik znajdujący się najbliżej”. Konflikt między dwoma plikami jest rozstrzygany na korzyść pliku dotyczącego edytowanego elementu. Treść wpisana na czacie zastępuje oba te pliki.

my-repo/
├── AGENTS.md              # project-wide rules
├── services/
│   ├── api/
│   │   └── AGENTS.md      # wins for edits under services/api/
│   └── web/
│       └── AGENTS.md      # wins for edits under services/web/
└── README.md

Zagnieżdżanie plików jest przydatne, ponieważ tylko w ten sposób można określić regułę prawdziwą w jednym katalogu i nieprawdziwą w kolejnym. Reguła „każdy endpoint sprawdza poprawność danych wejściowych” powinna znajdować się obok endpointów. W pliku głównym byłaby wczytywana podczas każdego niezwiązanego zadania i nie przynosiłaby żadnych korzyści.

Co powinno znajdować się w pliku AGENTS.md

Należy zapisać informacje, których agent nie może ustalić na podstawie kodu. W pierwszej kolejności należy podać dokładne polecenia do kompilowania, testowania i lintowania, w formie umożliwiającej wklejenie ich do terminala. Należy również dodać polecenie uruchamiające pojedynczy test, ponieważ agent, który zna tylko sposób uruchomienia całego zestawu, uruchomi cały zestaw czterdzieści razy. Należy wskazać konwencje różniące się od ustawień domyślnych narzędzia. Agent zna już ustawienia domyślne i musi poznać tylko odstępstwa od nich. Należy dodać format komunikatów commit oraz zasady dotyczące pull requestów, jeśli obowiązują.

Instrukcje powinny być na tyle konkretne, aby można było zweryfikować ich spełnienie. „Stosuj wcięcie o szerokości 2 spacji” to użyteczna instrukcja, ponieważ można jednoznacznie sprawdzić, czy została zrealizowana. „Formatuj kod prawidłowo” nie jest użyteczne, ponieważ nie określa niczego, co można zweryfikować. To samo dotyczy lokalizacji: „Procedury obsługi API znajdują się w src/api/handlers/” jest lepsze niż „utrzymuj uporządkowaną strukturę plików”.

Reguły negatywne również uzasadniają swoje miejsce. „Nigdy nie edytuj plików w dist/, ponieważ są generowane przez npm run build” zapobiega konkretnemu błędowi. Ponieważ reguła wskazuje jego przyczynę, agent może ustalić równoważny przypadek, którego nie opisano wprost.

Czego nigdy w nim nie umieszczać

Nigdy nie umieszczać sekretu w jednym z tych plików. Plik jest zatwierdzany w git, ładowany do kontekstu na początku każdej sesji i wysyłany do dostawcy modelu przy każdym żądaniu. Klucz API w pliku AGENTS.md znajduje się w historii repozytorium oraz w logach podmiotu trzeciego. Zamiast wklejać sekret, należy wskazać jego lokalizację: „hasło do bazy danych znajduje się w .env, który jest ignorowany przez git; przed odczytaniem należy poprosić o zgodę”. Szersze zasady opisano w sekcji przechowywanie danych uwierzytelniających poza zasięgiem agenta.

Należy pomijać informacje, które agent może ustalić na podstawie dostępnych danych. Wklejona lista katalogów, kopia listy zależności oraz opis architektury powtarzający nazwy folderów — wszystkie te informacje dezaktualizują się w ciągu tygodnia od ich zapisania, a do tego czasu zużywają kontekst podczas każdej sesji. Należy zachować informacje o pułapkach i przyczynach. Spis informacji należy usunąć.

CLAUDE.md to odpowiednik AGENTS.md w Claude Code

Claude Code odczytuje CLAUDE.md i samodzielnie nie odczytuje AGENTS.md. Plik projektu znajduje się w ./CLAUDE.md lub ./.claude/CLAUDE.md, preferencje osobiste dla każdego projektu należy umieścić w ~/.claude/CLAUDE.md, a organizacja może wdrożyć plik obowiązujący na całej maszynie w /etc/claude-code/CLAUDE.md w systemie Linux. Wykryte pliki są łączone od głównego katalogu systemu plików do bieżącego katalogu roboczego, dlatego plik znajdujący się najbliżej miejsca uruchomienia sesji jest odczytywany jako ostatni.

Jeśli repozytorium zawiera już plik AGENTS.md, nie należy utrzymywać drugiej kopii. Należy go zaimportować, a następnie dodać tylko informacje specyficzne dla Claude:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Dowiązanie symboliczne sprawdza się, gdy nie ma nic dodatkowego do dodania:

ln -s AGENTS.md CLAUDE.md

Po pomyślnym wykonaniu polecenie niczego nie wyświetla. W następnej sesji należy uruchomić /context i sprawdzić, czy CLAUDE.md pojawia się w sekcji Memory files. Jeśli brakuje go na tej liście, plik nie został załadowany, więc jego zawartość nie została zastosowana. Aby wygenerować pierwszy szkic zamiast tworzyć plik ręcznie, należy uruchomić /init: polecenie odczytuje bazę kodu i tworzy plik początkowy, a jeśli CLAUDE.md już istnieje, proponuje ulepszenia zamiast go zastępować.

Każdy plik powinien mieć mniej więcej 200 wierszy. Dłuższe pliki zajmują większą część okna kontekstu, a stopień stosowania zawartych w nich instrukcji spada. Jeśli trzeba sprawdzić, co jeszcze konkuruje o tę przestrzeń, wyjaśnia to co faktycznie wypełnia okno kontekstu agenta.

Należy podkreślić jedną kwestię. AGENTS.md zawiera wytyczne, a nie mechanizm uprawnień. Zawartość jest przekazywana jako zwykły kontekst, dlatego model ją odczytuje i zwykle stosuje się do instrukcji, ale nic nie blokuje działania sprzecznego z tymi wytycznymi. W przypadku reguły, która musi obowiązywać za każdym razem, takiej jak „nigdy nie wykonuj push do main”, należy użyć hooka lub ustawienia uprawnień, ponieważ są one wykonywane jako kod i nie zależą od tego, czy model zdecyduje się zastosować do instrukcji.

Narzędzia, które zapisują te pliki automatycznie

Dwa projekty z listy GitHub Trending z 30 July 2026 pokazują kierunek rozwoju tej konwencji.

agent0ai/dox (1,368 gwiazdek w July 2026) to framework służący do utrzymywania aktualności drzewa plików AGENTS.md. Nie zawiera pakietu ani środowiska uruchomieniowego. Należy skopiować zawartość jego pliku AGENTS.md do własnego głównego pliku AGENTS.md. To stanowi instalację. W przypadku istniejącego projektu należy przekazać agentowi następujące polecenie:

Initialize DOX tree for this project now.

Agent tworzy następnie podrzędne pliki AGENTS.md i ich indeksy, przegląda to drzewo przed wprowadzeniem zmian oraz aktualizuje odpowiednią dokumentację po zatwierdzeniu zmiany. Założenie jest takie, że dokumentacja utrzymywana przez agenta jako efekt uboczny jego pracy pozostaje aktualna, natomiast dokumentacja aktualizowana ręcznie przez człowieka — nie.

HUMAN.md, ta sama metoda zastosowana do użytkownika

Intuition-Lab/personal-model (1,260 gwiazd na dzień July 2026) stosuje ten wzorzec do osoby zamiast do repozytorium. Projekt przedstawia plik HUMAN.md jako wynik działania systemu, a nie plik wpisywany ręcznie: „dynamiczny model tego, co jest obecnie ważne, sposobu podejmowania decyzji oraz kierunku, w którym przenosi się uwaga”. Działa lokalnie w systemie macOS 13 lub nowszym, rejestruje aktywność po udzieleniu uprawnień systemowi macOS i udostępnia wynik agentom za pośrednictwem MCP (model context protocol). Skrócona ścieżka instalacji:

uv tool install personal-model
persome onboard
persome model open --after 30

Do uzyskania większości korzyści nie jest potrzebne żadne z tych narzędzi. Ręcznie utworzony plik HUMAN.md ma około dwudziestu wierszy: rola użytkownika, strefa czasowa, rzeczywiście używany stos technologiczny, podjęte już decyzje, do których nie należy wracać, oraz oczekiwany poziom szczegółowości odpowiedzi. Ogranicza to konieczność wielokrotnego przekazywania tych samych informacji, podobnie jak plik projektu, ale na wyższym poziomie.

Należy zachować ostrożność. Plik HUMAN.md jest profilem osoby, dlatego z definicji zawiera dane wrażliwe. Nie należy umieszczać go w publicznym repozytorium. Należy przechowywać go w ~/.claude/CLAUDE.md albo w objętym wpisem CLAUDE.local.md pliku w katalogu głównym projektu. Taki plik jest ładowany razem ze śledzonym plikiem i traktowany w ten sam sposób.

Szablon początkowy do skopiowania

Jest celowo krótki. Usuń sekcje, które nie mają zastosowania, i nie dodawaj tych, których nie można na bieżąco aktualizować.

# AGENTS.md

## Project
A Django API serving the mobile app. Python 3.12, PostgreSQL 16.

## Setup
uv sync
docker compose up -d db
./manage.py migrate

## Commands
Run one test: pytest tests/test_orders.py::test_refund
Run everything: pytest
Lint: ruff check . && ruff format --check .

## Conventions
Type hints on every public function. Line length 100, not 88.
Migrations are generated, never hand-edited.
Never edit files under static/dist/, they come from npm run build.

## Secrets
Local credentials live in .env, which is gitignored. Ask before reading it.

## Pull requests
Title format: [area] short description. Run the linter before opening one.

Zapisz go, a następnie poprawiaj w miejscu. Sygnałem do dodania wiersza jest dwukrotne wpisanie tej samej poprawki na czacie. Ta jedna zasada sprawia, że plik pozostaje użyteczny i nie pozwala mu rozrosnąć się do dokumentu, którego nikt nie czyta, włącznie z maszynami. Po ustabilizowaniu zawartość pliku jest przechowywana razem z repozytorium. Ma to największe znaczenie, gdy agent działa w innym miejscu niż laptop: uruchamianie agenta programistycznego na własnym serwerze opisuje tę konfigurację.

FAQ

Czy AGENTS.md to ten sam plik co CLAUDE.md?

To ta sama koncepcja pod dwiema nazwami plików. Claude Code odczytuje CLAUDE.md i ignoruje AGENTS.md, chyba że zostaną połączone. Należy zachować jeden plik jako źródło prawdy i utworzyć dowiązanie do niego z drugiego pliku, używając wiersza @AGENTS.md na początku pliku CLAUDE.md albo polecenia ln -s AGENTS.md CLAUDE.md. Dwie pełne kopie utrzymywane oddzielnie zaczną się różnić w ciągu miesiąca.

Czy utworzenie AGENTS.md gwarantuje, że agent będzie go przestrzegać?

Nie. Zawartość jest przekazywana jako kontekst, więc model ją odczytuje i zazwyczaj stosuje się do zawartych w niej zasad, ale nic nie blokuje działania sprzecznego z tymi zasadami. Nieprecyzyjne instrukcje są przestrzegane najmniej niezawodnie, a dwa pliki zawierające sprzeczne wskazówki pozostawiają agentowi arbitralny wybór jednej z nich. W przypadku reguły, która musi obowiązywać za każdym razem, należy użyć hooka lub reguły uprawnień. Są one egzekwowane przez klienta niezależnie od decyzji modelu.

Czy plik AGENTS.md należy zatwierdzać w git?

Tak, jeśli zawiera informacje dotyczące projektu, takie jak polecenia kompilacji, układ plików i przyjęte konwencje. Taki jest cel tego pliku, ponieważ agenci członków zespołu rozpoczynają pracę z takim samym kontekstem jak agent użytkownika. Informacje osobiste lub dotyczące jednej maszyny należy umieścić w osobnym pliku ignorowanym przez git, a danych uwierzytelniających nie należy umieszczać w żadnym z tych plików.

Czym jest HUMAN.md i czy jest potrzebny?

HUMAN.md to odczytywany maszynowo profil osoby, a nie projektu. Zawiera informacje o roli użytkownika, jego ograniczeniach oraz decyzjach, które zostały już podjęte, aby nie trzeba było ponownie ich rozpatrywać w każdej sesji. Do rozpoczęcia pracy nie są potrzebne żadne dodatkowe narzędzia: dwadzieścia ręcznie napisanych wierszy w pliku instrukcji na poziomie użytkownika zapewnia większość korzyści. Należy traktować ten plik jako dane osobowe i nie umieszczać go w żadnym wypychanym repozytorium.