Blog

Czym jest AGENTS.md i jak napisać własny plik w 30 minut

Markdown

Format AGENTS.md, obsługa w narzędziach AI, gotowy szablon, zasady i typowe błędy. Jak koordynować AGENTS.md z CLAUDE.md i innymi plikami z instrukcjami.

Przeczytaj cały artykuł

Praktyczne materiały o vibe codingu i pracy z agentami: dokumentacja Ailoot.

Czym jest AGENTS.md?

Najważniejsze

AGENTS.md to zwykły plik Markdown w katalogu głównym projektu, który zawiera instrukcje dla agenta AI: jak instalować zależności, uruchamiać testy, jakiego stylu kodu przestrzegać i czego nie ruszać. Jest to otwarty format stworzony przez OpenAI w sierpniu 2025 roku, który w grudniu tego samego roku dołączył do Linux Foundation. Wiele narzędzi do programowania może korzystać z tego pliku, ale sposób jego odnajdywania zależy od klienta i wersji: część ładuje AGENTS.md automatycznie, a część wymaga jawnego ustawienia nazwy pliku lub konfiguracji jego odczytu. Od wersji 2.1.277 (wrzesień 2026) Claude Code również odczytuje AGENTS.md, jeśli projekt nie ma pliku CLAUDE.md. Jeśli CLAUDE.md istnieje, Claude Code domyślnie czyta tylko ten plik, a AGENTS.md jest dołączany za pomocą wiersza @AGENTS.md lub dowiązania symbolicznego.

Poniżej format omówiono na podstawie agents.md, dokumentacji OpenAI Codex, JetBrains Junie, Cursor Rules Docs, dziennika zmian GitHub Copilot Coding Agent oraz komunikatu prasowego Linux Foundation o Agentic AI Foundation. Wszystkie liczby i funkcje są aktualne na 30 maja 2026 roku, a obsługa AGENTS.md w Claude Code została opisana zgodnie z dokumentacją Anthropic, z aktualizacją z 24 września 2026 roku.

Jeśli nie wiesz, czym jest to całe zoo narzędzi dostępnych na rynku ani dlaczego potrzebują wspólnego pliku, najpierw przeczytaj poradnik „W czym programować w 2026 roku: 8 narzędzi AI — od Claude Code do Antigravity”. Ten artykuł skupia się konkretnie na formacie AGENTS.md i tym, jak napisać własny plik w 30 minut.

Czym jest AGENTS.md i skąd się wziął?

Najważniejsze

AGENTS.md to otwarty format pliku Markdown, w którym samodzielnie zapisujesz instrukcje dla agentów AI. OpenAI opublikowało go w sierpniu 2025 roku wraz z Codex CLI i od razu zaprosiło do współtworzenia Cursor, Sourcegraph Amp, Google Jules i Factory. Pomysł jest prosty: „nie twórzmy zastrzeżonego pliku dla każdego narzędzia; uzgodnijmy jeden wspólny format”. 9 grudnia 2025 roku AGENTS.md, wraz z MCP od Anthropic i goose od Block, dołączył do Linux Foundation jako jeden z trzech projektów założycielskich nowej Agentic AI Foundation. Do grudnia tego samego roku AGENTS.md znajdował się już w katalogu głównym ponad 60 000 repozytoriów GitHub.

Wcześniej każde narzędzie AI miało własny plik z regułami: Anthropic miało CLAUDE.md, Cursor — .cursorrules, GitHub — .github/copilot-instructions.md, Aider — .aider.conf.yml, a JetBrains — .junie/guidelines.md. Jeśli zespół korzystał z trzech różnych agentów, oznaczało to trzy równoległe pliki o tej samej treści, które w ciągu tygodnia zaczynały się różnić.

OpenAI jako pierwsze miało dość tej sytuacji. W sierpniu 2025 roku opublikowało Codex CLI i jednocześnie uruchomiło agents.md jako otwarty format. Na stronie czytamy:

„Pomyśl o AGENTS.md jak o pliku README dla agentów.”

(agents.md, tłumaczenie z angielskiego)

Najważniejsze jest to, że AGENTS.md uzupełnia README. README pisze się dla ludzi: „czym jest projekt, jak uruchomić go lokalnie, jak wnosić wkład”. AGENTS.md jest przeznaczony dla agenta: zawiera dokładne polecenia powłoki, weryfikowalne kryteria „gotowe” oraz ograniczenia w rodzaju „nigdy tego nie ruszaj”.

Na stronie czytamy:

„AGENTS.md uzupełnia README: zawiera dodatkowy, czasem szczegółowy kontekst potrzebny agentowi — kroki kompilacji, testy i konwencje, które zaśmiecałyby README albo po prostu nie są potrzebne ludzkim współtwórcom.”

(agents.md, tłumaczenie z angielskiego)

We wrześniu 2025 roku GitHub Copilot Coding Agent obsługiwał już ten format (dziennik zmian, 28.08.2025). Do grudnia dołączyły Cursor, Junie, Gemini CLI, Aider i kilkanaście innych narzędzi. 9 grudnia 2025 roku Linux Foundation utworzyła Agentic AI Foundation (AAIF): jej trzema projektami założycielskimi były AGENTS.md od OpenAI, MCP od Anthropic i goose od Block. Członkami założycielskimi były AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft i OpenAI. Do 24 lutego 2026 roku fundacja obejmowała już 146 organizacji, w tym Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, UiPath i Hitachi.

Od tego momentu AGENTS.md przestał być „kolejną nowinką od OpenAI” i stał się de facto standardem.

Którzy agenci AI czytają AGENTS.md, a którzy nie?

Najważniejsze

AGENTS.md jest używany przez wiele narzędzi do programowania, w tym klientów wymienionych poniżej. Tabelę traktuj jako mapę sposobów ładowania, a nie obietnicę identycznej obsługi natywnej: automatyczne wykrywanie, jawna konfiguracja, pierwszeństwo nazw plików i obsługa plików zagnieżdżonych mogą się różnić. Claude Code od Anthropic przez długi czas był wyjątkiem: issue #6235 z prośbą o obsługę pozostawał otwarty od sierpnia 2025 do sierpnia 2026 roku. Od wersji 2.1.277 (18 września 2026) Claude Code samodzielnie czyta AGENTS.md, jeśli projekt nie ma CLAUDE.md. Jeśli CLAUDE.md istnieje, domyślnie odczytywany jest tylko ten plik, a AGENTS.md można dołączyć wierszem @AGENTS.md w CLAUDE.md albo za pomocą dowiązania symbolicznego.

Tabela obsługi według stanu na 30 maja 2026 roku; wiersz dotyczący Claude Code zaktualizowano 24 września 2026 roku:

NarzędzieCzyta AGENTS.mdData / źródło
OpenAI Codex CLITak (format natywny)Sierpień 2025, agents.md
GitHub Copilot Coding AgentTak28.08.2025, GitHub Changelog
CursorTak, katalog główny i katalogi zagnieżdżoneCursor Rules Docs
JetBrains JunieTak, projekt i globalny ~/.junie/AGENTS.mdJunie Docs
Gemini CLI (Google)Tak, przez .gemini/settings.json z fileName: AGENTS.mdagents.md
Jules (Google)Tak, współautor standarduSierpień 2025
Sourcegraph AmpTak, współautor standarduSierpień 2025
AiderTak, przez read: AGENTS.md w .aider.conf.ymlagents.md
FactoryTak, współautor standarduSierpień 2025
OpenCodeTak—
ZedTakagents.md
WarpTakagents.md
VS CodeTakagents.md
WindsurfTak—
Devin (Cognition)Tak, przez Spec Kit SkillsKwiecień 2026
RooCode, Kilo Code, Augment CodeTakagents.md
Claude Code (Anthropic)Tak, jeśli projekt nie ma CLAUDE.mdOd wersji 2.1.277 (18.09.2026), dokumentacja Claude Code

Anthropic dołączyło jako ostatni z głównych graczy. W sierpniu 2025 roku w oficjalnym repozytorium anthropics/claude-code otwarto issue #6235 z prośbą o obsługę AGENTS.md.

Issue pozostawało otwarte przez niemal rok i zamknięto je 17 sierpnia 2026 roku; wersja 2.1.277 z obsługą AGENTS.md ukazała się 18 września. Logika Anthropic jest następująca: CLAUDE.md ma pierwszeństwo, a AGENTS.md jest odczytywany, gdy w bieżącym katalogu roboczym ani w żadnym katalogu nadrzędnym nie ma CLAUDE.md. Według dokumentacji wygląda to tak:

Co znajduje się w projekcieCo czyta Claude Code
Tylko AGENTS.mdAGENTS.md
AGENTS.md i CLAUDE.md (lub CLAUDE.local.md)Tylko CLAUDE.md
CLAUDE.md z wierszem @AGENTS.mdCLAUDE.md, który włącza AGENTS.md

Haczyk polega na tym, że osobisty plik CLAUDE.local.md również się liczy, a gdy istnieje, Claude Code przestaje czytać AGENTS.md. Można zmienić to zachowanie w /config, w sekcji Project instructions — na przykład tak, by Claude Code czytał oba pliki jednocześnie. W wersjach starszych niż 2.1.277 AGENTS.md nie zostanie automatycznie wczytany; obejściem pozostaje wiersz @AGENTS.md w CLAUDE.md.

Czym AGENTS.md różni się od CLAUDE.md i .cursorrules?

Najważniejsze

Technicznie nie ma w nich nic szczególnego: wszystkie cztery formaty (AGENTS.md, CLAUDE.md, .cursorrules, .github/copilot-instructions.md) to zwykłe pliki Markdown z instrukcjami dla agenta. Różnią się tym, kto je odczytuje i gdzie się znajdują. AGENTS.md może zawierać wspólne instrukcje dla kilku klientów, a sposób ich wykrywania lub konfigurację właściwą dla klienta przechowuje się osobno. CLAUDE.md jest przeznaczony tylko dla Claude Code, ale udostępnia zaawansowane funkcje: reguły przypisane do ścieżek, CLAUDE.local.md do osobistych nadpisań, @import do dołączania innych plików oraz hierarchię projektu, użytkownika i pliku lokalnego. .cursorrules jest przestarzały w Cursor — nowy system korzysta z .cursor/rules/*.mdc i automatycznego dołączania reguł według typu pliku. .github/copilot-instructions.md jest potrzebny tylko dla internetowej wersji Copilota.

Porównanie czterech formatów według stanu na 30 maja 2026 roku:

FormatKto go czytaGdzie się znajdujeZaletaWada
AGENTS.mdZgodni klienci z udokumentowanym sposobem ładowaniaKatalog główny lub pliki zagnieżdżone według obsługi klientaWspólne reguły w neutralnym pliku; skonfiguruj i sprawdź każdego klientaWykrywanie, hierarchia i obsługa prywatnych instrukcji zależą od klienta
CLAUDE.mdTylko Claude CodeKatalog główny + ~/.claude/CLAUDE.md + CLAUDE.local.mdHierarchia, reguły przypisane do ścieżek, @import, skills, hooksTylko Claude. Nie działa w Cursor / Codex / Copilot
.cursor/rules/*.mdcTylko Cursor.cursor/rules/<rule>.mdcAutomatyczne dołączanie według typu pliku (TS, Python, konkretne ścieżki)Tylko Cursor, niestandardowa składnia .mdc
.github/copilot-instructions.mdGitHub Copilot (wersja internetowa i klasyczna).github/Działa bezpośrednio w przeglądarce na GitHub.comTylko Copilot, duplikuje AGENTS.md

Najważniejsza myśl: AGENTS.md rozwiązuje problem „jeden plik dla wszystkich agentów”, ale nie problem „osobiste ustawienia, których nie commituję”. Claude Code ma do tego CLAUDE.local.md, a Cursor — lokalne pliki .mdc w katalogu użytkownika. Sam AGENTS.md tego nie zapewnia, więc trzeba połączyć go z innymi plikami albo uzgodnić w zespole, że osobiste reguły będą zapisywane w sekcjach ignorowanych przez git.

Kolejny ważny szczegół to monorepo. Codex i Cursor stosują zasadę „wygrywa najbliższy AGENTS.md”:

„W monorepo umieść osobny AGENTS.md w każdym pakiecie. Agenci automatycznie odczytują plik położony najbliżej w drzewie katalogów i to on ma pierwszeństwo.”

(agents.md, tłumaczenie z angielskiego)

agents.md wspomina, że główne monorepo OpenAI zawiera 88 plików AGENTS.md dla różnych podpakietów. Jeśli pracujesz w monorepo, rozdziel reguły na poziomy: ogólne umieść w katalogu głównym, a szczegółowe — w podkatalogach.

Co powinien zawierać dobry AGENTS.md?

Najważniejsze

Dobry AGENTS.md zawiera 8 sekcji, które można znaleźć w większości popularnych plików: przegląd projektu, polecenia konfiguracji, styl kodu, wskazówki dotyczące środowiska deweloperskiego, instrukcje testowania, wytyczne PR, kwestie bezpieczeństwa oraz granice (czego nie robić). Wszystko inne jest opcjonalne. Główna zasada: każdy punkt ma zawierać dokładne polecenie albo konkretny przykład, a nie ogólną myśl w rodzaju „pisz czysty kod”.

Strona agents.md oferuje elastyczny format — „dowolny Markdown”. Jednak 80% dobrych plików używanych w praktyce zawiera te same osiem sekcji. Główna zasada: każdy punkt powinien być dokładnym poleceniem albo konkretnym przykładem. Agent zignoruje abstrakcyjne zalecenie, takie jak „pisz czysty kod”.

  1. Przegląd projektu — 2–3 wiersze. Czym jest projekt, dla kogo jest przeznaczony i jaki jest jego główny cel. Bez marketingu. Przykład: „Bot Telegram do wdrażania uczestników w płatne warsztaty. Stos: Next.js 14, Prisma, PostgreSQL. Uruchamia się po dodaniu nowego rekordu w purchases.”
  2. Polecenia konfiguracji — dokładne polecenia powłoki do uruchomienia lokalnie. npm install, npm run dev, npm run build. Bez „zwykle robimy to tak”.
  3. Styl kodu / konwencje — konkretne reguły z przykładem, a nie „pisz czysto”. Na przykład: „TypeScript strict, pojedyncze cudzysłowy, bez default exports, nazwy komponentów w PascalCase, nazwy hooks zaczynają się od use.”
  4. Wskazówki dotyczące środowiska deweloperskiego — gdzie znajdują się ważne rzeczy. Jakie zmienne są potrzebne w .env, gdzie przechowywane są sekrety, które porty są używane i jak pracować z lokalną bazą danych.
  5. Instrukcje testowania — jak uruchomić konkretny test i co oznacza wynik „zielony”. Na przykład: npm test -- --testPathPattern=user-auth; oczekuje się 100% zaliczonych testów.
  6. Wytyczne dotyczące PR / commitów — format komunikatów commitów, lista kontrolna przed PR (testy, linter, dokumentacja) i osoba zatwierdzająca.
  7. Kwestie bezpieczeństwa — czego nigdy nie wolno robić. „Nigdy nie commituj .env. Sekrety należą wyłącznie do Vault. Nie pokazuj danych osobowych użytkowników w logach.”
  8. Granice / nigdy tego nie rób — zakazy wraz z alternatywą. „Nie używaj git push --force na main. Jeśli musisz wycofać zmiany, użyj git revert albo git reset na gałęzi funkcjonalnej.”

W każdej sekcji stosuj zasadę „polecenie zamiast pomysłu”. Agent zignoruje „uważaj przy migracjach”. Zastosuje się do „przed alembic upgrade head uruchom alembic check. Jeśli pojawi się błąd, nie stosuj migracji; zapytaj mnie”.

Gotowy szablon AGENTS.md (skopiuj i dostosuj)

Najważniejsze

Poniżej znajduje się początkowy szablon AGENTS.md dla typowego projektu internetowego. Skopiuj go do katalogu głównego repozytorium, zastąp <project-name>, <stack> i dokładne polecenia, a niepotrzebne sekcje usuń. Dostosowanie zajmuje 20–30 minut — lub dłużej, jeśli robisz to po raz pierwszy.

# AGENTS.md

## Project overview

<project-name> - <one phrase describing its purpose>.
Stack: <Next.js / Python / Go / ...>.
Main entities: <users, orders, posts ...>.
Details for people are in README.md.

## Setup commands

```bash
# pierwsza instalacja
npm install
cp .env.example .env  # następnie uzupełnij ręcznie; zobacz listę poniżej

# uruchom
npm run dev           # serwer deweloperski na :3000
npm run build         # kompilacja produkcyjna
npm run start         # uruchom kompilację produkcyjną
```

## Dev environment

- Node 20+ (via nvm: `nvm use 20`)
- PostgreSQL 16 locally on :5432 (`docker-compose up postgres`)
- Redis is optional, needed only for queues (`docker-compose up redis`)
- `.env`: `DATABASE_URL`, `STRIPE_KEY`, `RESEND_API_KEY`, `JWT_SECRET`
- Never read the entire `.env` file. If you need one variable: `grep "^VAR=" .env`

## Code style

- TypeScript strict mode
- Single quotes, no semicolons (unless ESLint requires them)
- Imports: external first, then internal via `@/`, then relative
- Components in PascalCase; hooks start with `use`
- No `any` without an explicit comment explaining “dlaczego nie da się tego otypować”

Example of a good module:

```ts
import { z } from 'zod'

const UserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2),
})

export function parseUser(raw: unknown) {
  return UserSchema.parse(raw)
}
```

## Testing

```bash
npm test                                # wszystkie testy
npm test -- --testPathPattern=auth      # tylko kolejki
npm test -- --watch                     # tryb obserwowania zmian
```

All tests must pass (be green) before committing. If a test is red, don’t commit; ask me what to do.

## Pull request guidelines

- Commit format: `<type>(<scope>): <description>` (`feat(auth): add magic-link`)
- Before PR: `npm run build && npm test && npm run lint`
- PR description = what changes, why, and how to test
- Don’t approve your own PR—always wait for human review

## Security

- Secrets only in `.env` and Vault, never in code
- Don’t log personal data (email, phone, name)
- When working with the production DB, use read-only queries only unless explicitly authorized
- Don’t hardcode external service API keys (Stripe, OpenAI) in tests

## Never do this

- Don’t `git push --force` to main. If you need to roll back, use `git revert` or open a new PR
- Don’t run DB migrations without `alembic check` (or the equivalent in your ORM)
- Don’t use `npm install -g` or `sudo` for project dependencies
- Don’t add dependencies without approval (especially heavy ones: webpack plugins, ORM)

Średnio szablon ma 80–120 wierszy. Jeśli plik przekracza 150 wierszy, to sygnał, że należy go uporządkować: przenieść część do docs/, dodać odsyłacz albo skrócić coś do jednego wiersza. W praktyce najlepiej sprawdzają się pliki o długości 100–150 wierszy; powyżej tego progu korzyści jakościowe zaczynają się odwracać.

5 zasad, dzięki którym AGENTS.md naprawdę się przyda

Najważniejsze

Dobry AGENTS.md przestrzega pięciu zasad: polecenia zamiast pomysłów, zakazy z alternatywami, dokładnie jedno źródło prawdy, weryfikowalne kryteria ukończenia oraz plik krótszy niż 150 wierszy.

  1. Polecenia zamiast pomysłów. Agent nie rozumie „uważaj przy migracjach”. Wykona alembic check przed alembic upgrade head. Agenci działają na podstawie poleceń i warunków, a nie nastrojów. Wszystkie kluczowe reguły formułuj jako „zrób X, w przeciwnym razie Y”.

  2. Zakazy z alternatywą. Samo „nie wymuszaj pushowania” agent po cichu zignoruje po dwóch lub trzech promptach. Działa zestawienie „nie rób X; zamiast tego zrób Y”. Przykład: „nie używaj git push --force na main; jeśli musisz wycofać zmiany, użyj git revert albo otwórz nowe PR”.

  3. Dokładnie jedno źródło prawdy. Główny AGENTS.md jest źródłem prawdy dla całego projektu. W monorepo używaj zagnieżdżonych plików AGENTS.md w podkatalogach, zgodnie z zasadą „wygrywa najbliższy”. Nie twórz równoległych plików ze sprzecznymi instrukcjami.

  4. Weryfikowalne kryteria „gotowe”. „Testy muszą przejść” to bezużyteczne kryterium. Dokładne kryterium brzmi: npm test zwraca kod wyjścia 0 i nie wypisuje FAIL na standardowe wyjście. „Kod powinien być czysty” również nic nie znaczy. Dokładne kryterium to: npm run lint kończy się powodzeniem bez ostrzeżeń. Agent rozumie, co znaczy „gotowe”, tylko wtedy, gdy wyraźnie opiszesz warunek.

  5. Plik krótszy niż 150 wierszy. Powyżej 150 wierszy wskaźniki zaczynają się pogarszać: agent poświęca więcej kontekstu na czytanie i pomija ważne reguły. Jeśli wszystko się nie mieści, przenieś szczegóły do docs/architecture.md i umieść do niego odsyłacz w AGENTS.md, pozostawiając w pliku tylko polecenia i ograniczenia.

10 błędów, które zamieniają AGENTS.md w śmietnik

Najważniejsze

Główną przyczyną nieskuteczności AGENTS.md są niejasne sformułowania. W badaniu ponad 2,500 repozytoriów GitHub Blog wykazał, że większość plików zawodzi, bo są napisane zbyt ogólnie. Na przykład „Jesteś pomocnym asystentem programistycznym” nie daje agentowi absolutnie żadnych użytecznych informacji. Poniżej przedstawiono 10 typowych błędów i ich przykłady w złych plikach: powielanie README, nieuporządkowana proza, ponad 30 zakazów bez alternatyw, sprzeczne priorytety, sekrety wpisane na sztywno, nieaktualna dokumentacja oraz przesadnie rozbudowana architektura dla prostych zadań.

  1. Niejasne reguły bez poleceń. Agent zignoruje „uważaj przy migracjach” — to zdanie nic dla niego nie znaczy. Działa tylko konkretne polecenie z warunkiem: „Uruchom alembic check przed alembic upgrade head. Jeśli wystąpi błąd, nie stosuj migracji; zapytaj mnie”.

  2. „Czysty kod”. Bezużyteczne sformułowanie. Zastąp je konkretnym wzorcem: „Używaj komponentów funkcyjnych z hooks. Przykład: function LoginForm() { const [email, setEmail] = useState(''); ... }”

  3. Nieuporządkowana proza. Jeśli AGENTS.md ma 300 wierszy prozy bez nagłówków, agent zużyje 80K tokenów kontekstu na nieistotne fragmenty i pominie ważne informacje. Używaj nagłówków H2/H3, krótkich sekcji i list punktowanych.

  4. Plik dłuższy niż 150 wierszy. Po przekroczeniu tego progu wskaźniki jakości spadają. Podziel go na plik główny oraz odsyłacze do szczegółów w docs/.

  5. Ponad 30 zakazów bez alternatyw. Jeśli plik zawiera długą listę „nie rób X, nie rób Y” bez wyjaśnienia „zamiast tego zrób Z”, agent będzie błądził po omacku.

  6. Powielanie README.md. Jeśli w README masz już opis „jak zainstalować i uruchomić”, nie kopiuj go do AGENTS.md. Zamiast tego odwołaj się do README w jednym wierszu, a w AGENTS.md opisz to, czego potrzebuje agent, lecz nie ludzcy współtwórcy.

  7. Sekrety wpisane na sztywno. AGENTS.md może być publiczny (znajduje się w Git). Nie umieszczaj w nim prawdziwych kluczy API, tokenów ani haseł. Wskazuj wyłącznie magazyny sekretów: „Sprawdź Vault: secret/staging/db”.

  8. Sprzeczne priorytety bez hierarchii. „Działaj szybko” i „utrzymuj 90% pokrycia testami” pozostawia agenta bez wskazówki, co wybrać. Ustal priorytety wprost: „Najpierw pokrycie testami ≥80%, potem szybkość. Jeśli są sprzeczne, pierwszeństwo mają testy”.

  9. Nieaktualna dokumentacja. Opis architektury mówi o REST i odpytywaniu, choć w rzeczywistości projekt korzysta już z WebSockets. Agent stosuje się do nieaktualnego opisu i psuje architekturę. Zasada: aktualizuj AGENTS.md w tym samym PR co zmianę architektury.

  10. Przesadnie rozbudowana architektura dla prostego zadania. Jeśli ktoś prosi o zmianę dwóch wierszy w konfiguracji, agent nie powinien czytać pełnego opisu 14 mikrousług. Przenieś „głębokie” informacje o architekturze do docs/architecture.md; w AGENTS.md zostaw tylko „jeśli zadanie dotyczy architektury, przeczytaj docs/architecture.md”.

Badanie GitHub Blog obejmujące ponad 2,500 repozytoriów AGENTS.md podaje główny wniosek:

„Większość plików dla agentów zawodzi, bo są zbyt ogólne. ‘Jesteś pomocnym asystentem programistycznym’ nie działa.”

(GitHub Blog, tłumaczenie z angielskiego)

Jak przechowywać AGENTS.md i CLAUDE.md w jednym repozytorium?

Najważniejsze

Są trzy scenariusze: (1) tylko Claude Code — zachowaj CLAUDE.md; AGENTS.md nie jest potrzebny. (2) tylko narzędzia inne niż Claude (Codex, Cursor, Copilot, Junie) — używaj AGENTS.md jako jedynego źródła prawdy. (3) zespół mieszany, korzystający z Claude Code i innych narzędzi — ustaw AGENTS.md jako główny plik. Jeśli nie masz osobnych reguł dla Claude, możesz pominąć CLAUDE.md: od wersji 2.1.277 Claude Code samodzielnie czyta AGENTS.md. Jeśli masz oddzielne reguły, połącz AGENTS.md z CLAUDE.md przez dowiązanie symboliczne lub import @AGENTS.md. W macOS i Linux zmieniaj nazwę tylko przy nieistniejącym AGENTS.md. Gdy oba pliki istnieją, najpierw zachowaj i scal reguły, a następnie użyj krótkiego CLAUDE.md z @AGENTS.md; nigdy nie nadpisuj istniejącego AGENTS.md. W Windows dowiązania symboliczne wymagają trybu deweloperskiego, dlatego łatwiej użyć importu.

Główne praktyczne pytanie brzmi, jak korzystać z obu plików bez powielania treści. Są trzy scenariusze:

Scenariusz 1: tylko Claude Code. Zachowaj CLAUDE.md i korzystaj ze wszystkich funkcji Claude Code: ~/.claude/CLAUDE.md dla instrukcji użytkownika, CLAUDE.md dla projektu, CLAUDE.local.md dla osobistych nadpisań, @import do dołączania innych plików oraz .claude/skills/ dla wyspecjalizowanych skills. AGENTS.md nie jest potrzebny.

Scenariusz 2: kilka klientów do programowania. Zachowaj wspólne reguły w AGENTS.md, a następnie podłącz i sprawdź każdego klienta oddzielnie. Gemini CLI obsługuje skonfigurowaną nazwę pliku kontekstu; Aider może ładować plik przez konfigurację odczytu. To jawne ścieżki ładowania, a nie identyczne automatyczne wykrywanie.

Sposób ładowaniaCo sprawdzić
Automatyczne wykrywanie AGENTS.mdUdokumentowane reguły zainstalowanego klienta dotyczące katalogu głównego, plików zagnieżdżonych i pierwszeństwa
Jawna konfiguracja, np. Gemini CLI lub AiderUstawioną nazwę pliku lub ścieżkę odczytu oraz widok załadowanego kontekstu klienta
Warunkowe ładowanie lub import w Claude CodeZainstalowaną wersję i pierwszeństwo plików; zobacz osobny poradnik AGENTS.md w Claude Code

Rozpocznij nową sesję w nieszkodliwym repozytorium testowym, dodaj unikalną nieszkodliwą instrukcję, np. „umieść znacznik instructions-loaded w odpowiedzi testowej”, i obejrzyj udokumentowany widok załadowanych plików lub logi klienta oraz jego odpowiedź. Powtórz to dla każdego używanego klienta i wersji. Wygenerowane stwierdzenie, że plik odczytano, nie jest niezależnym dowodem jego załadowania; jeden udany test nie potwierdza obsługi we wszystkich pozostałych narzędziach.

Scenariusz 3: zespół mieszany (Claude Code + inne narzędzia). To najczęstsza konfiguracja w 2026 roku. Rozwiązaniem jest ustawienie AGENTS.md jako głównego pliku. Jeśli nie masz reguł wyłącznie dla Claude Code, w ogóle nie twórz CLAUDE.md: od wersji 2.1.277 Claude Code czyta AGENTS.md, gdy w projekcie nie ma CLAUDE.md. Jeśli masz takie reguły, utwórz CLAUDE.md jako dowiązanie symboliczne albo krótki plik pośredniczący z importem @AGENTS.md.

Przed zmianą obejrzyj i skopiuj oba pliki. Jeśli oba istnieją, scal zgodne reguły wspólne w AGENTS.md, a instrukcje Claude pozostaw w CLAUDE.md z importem @AGENTS.md. Zachowuj istniejące dowiązania zamiast je zastępować.

Dla zwykłego CLAUDE.md tylko przy braku AGENTS.md ta kontrola macOS/Linux odmawia nadpisania istniejącego celu lub dowiązania:

if [ -e AGENTS.md ] || [ -L AGENTS.md ]; then
  printf '%s\n' 'STOP: AGENTS.md exists; merge both files first.' >&2
elif [ -f CLAUDE.md ] && [ ! -L CLAUDE.md ]; then
  mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md
else
  printf '%s\n' 'STOP: inspect the existing CLAUDE.md path first.' >&2
fi

Po udanej zmianie nazwy CLAUDE.md jest dowiązaniem do AGENTS.md. Wszystkie agenty odczytujące AGENTS.md widzą tę samą treść. Claude Code, który czyta CLAUDE.md, również widzi ją przez dowiązanie symboliczne.

W Windows utworzenie dowiązania symbolicznego wymaga trybu deweloperskiego (lub uprawnień administratora), co może być niewygodne dla całego zespołu. Alternatywą jest krótki CLAUDE.md importujący AGENTS.md:

# CLAUDE.md

@AGENTS.md

## Claude Code specific

- Use .claude/skills/ for specialized prompts
- When working with Skills, consult .claude/skills/INDEX.md
- Use Plan Mode before major changes (Shift+Tab)

W Claude Code ta składnia jednym wierszem wczytuje AGENTS.md, a poniżej dodaje specyficzne dodatki dla Claude Code. Jeśli później zechcesz usunąć AGENTS.md, po prostu usuń import. Ten wiersz nie powoduje podwójnego odczytu: według dokumentacji Claude Code ten sam plik AGENTS.md nie jest wczytywany dwa razy, nawet jeśli Claude Code potrafi odczytać go samodzielnie.

Typowy układ dla zespołu korzystającego z wielu narzędzi w 2026 roku:

repo-root/
├── AGENTS.md                              # źródło prawdy, ≤150 wierszy
├── CLAUDE.md                              # tylko przy regułach specyficznych dla Claude: dowiązanie → AGENTS.md LUB @AGENTS.md + dodatki
├── .cursor/rules/                         # ukierunkowane nadpisania tylko dla Cursor
├── .github/copilot-instructions.md        # „Zobacz AGENTS.md”, jeśli używany
└── docs/architecture.md                   # szczegółowa architektura wskazana w AGENTS.md

Więcej o CLAUDE.md znajdziesz w poradniku „Jak prawidłowo skonfigurować CLAUDE.md”. Aby dowiedzieć się więcej o tym, dlaczego agent potrzebuje obszernego pliku z instrukcjami, przeczytaj „Czym jest inżynieria kontekstu”.

Co zmieniło się w 2026 roku: dlaczego AAIF włączyła AGENTS.md do Linux Foundation?

Najważniejsze

9 grudnia 2025 roku Linux Foundation utworzyła Agentic AI Foundation (AAIF) z trzema projektami założycielskimi: AGENTS.md od OpenAI, MCP od Anthropic i goose od Block. Członkami założycielskimi były AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft i OpenAI. Do 24 lutego 2026 roku fundacja obejmowała 146 organizacji. Oznacza to, że AGENTS.md przestał być „projektem OpenAI” i stał się standardem branżowym obok MCP. W praktyce, jeśli tworzysz produkt, który ma działać z agentami różnych dostawców, umieszczenie AGENTS.md w katalogu głównym to podstawowa higiena. Bez niego będziesz utrzymywać trzy lub cztery równoległe pliki, które zaczną się różnić w ciągu miesiąca.

Głównym politycznym wydarzeniem maja 2026 roku w dziedzinie programowania z AI nie była premiera kolejnego modelu, lecz konsolidacja formatów. Wcześniej każdy dostawca miał własny plik z regułami — wygodne dla dostawców, ale uciążliwe dla zespołów korzystających z kilku narzędzi.

W komunikacie prasowym z 9 grudnia 2025 roku Linux Foundation ogłosiła Agentic AI Foundation jako organizację skupiającą trzy formaty:

  • AGENTS.md od OpenAI — format pliku z instrukcjami dla agentów
  • Model Context Protocol (MCP) od Anthropic — protokół łączący zewnętrzne narzędzia z agentami
  • goose od Block — otwartoźródłowa platforma agentowa

Z komunikatu prasowego Linux Foundation:

„Połączenie tych projektów pod szyldem AAIF zapewnia im warunki rozwoju oparte na przejrzystości i stabilności, które może zapewnić tylko otwarty model zarządzania.”

(komunikat prasowy Linux Foundation, 9 grudnia 2025, tłumaczenie z angielskiego)

Do 24 lutego 2026 roku do AAIF należało 146 organizacji (97 nowych członków w ciągu dwóch miesięcy). Wśród nowych członków Gold znalazły się Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, Hitachi, UiPath, American Express i Autodesk. Anthropic jest członkiem Platinum promującym MCP. OpenAI jest członkiem Platinum promującym AGENTS.md. Block jest członkiem Platinum wspierającym goose.

Zmienia to pozycję AGENTS.md: z „formatu OpenAI” stał się standardem branżowym. Wiosną 2026 roku Claude Code pozostawał na uboczu, ale we wrześniu, wraz z wersją 2.1.277, nauczył się samodzielnie odczytywać AGENTS.md. CLAUDE.md nie zniknął i domyślnie nadal ma pierwszeństwo, jeśli znajduje się w projekcie.

Praktycznym punktem wyjścia są wspólne reguły projektu w AGENTS.md oraz import, plik pośredniczący lub jawna konfiguracja odczytu wymagane przez każdego używanego klienta. W Claude Code sprawdź zainstalowaną wersję i pierwszeństwo plików instrukcji, zanim wybierzesz import w CLAUDE.md lub dowiązanie symboliczne. Zweryfikuj ładowanie w każdym kliencie; ten poradnik nie ustala procentu objętych scenariuszy.

Co dalej?

AGENTS.md to pierwszy element w „uzgadnianiu się z agentem, żeby działał przewidywalnie”. Następny jest drugi element — folder wiedzy o projekcie, który zawiera kontekst biznesowy, odbiorców, produkty i ceny. Trzeci element to inżynieria kontekstu, która łączy wszystko: jakie pliki agent widzi na każdym etapie, jak zachowywany jest stan między sesjami i jak przełączać się między różnymi modelami.

Praktyczne materiały: dokumentacja Ailoot.

Więcej materiałów i narzędzi: Ailoot.

Więcej szczegółów

Pytania i odpowiedzi

Co zrobić, gdy AGENTS.md i CLAUDE.md już istnieją?

Zrób kopię i porównaj oba przed zmianą. Scal wspólne zasady w AGENTS.md, zachowaj reguły Claude w CLAUDE.md i dodaj @AGENTS.md; nie przemianowuj jednego na drugi.

Jak uczynić instrukcje sprawdzalnymi?

Podaj dokładne polecenia konfiguracji i testów, oczekiwany wynik oraz zakazane zmiany. Szczegóły architektury przenieś do podlinkowanych dokumentów, aby główne instrukcje łatwo się czytało.

Wszystkie artykuły