AGENTS.md vs CLAUDE.md: jeden plik instrukcji dla agentów AI

18 września 2026 Claude Code 2.1.277 zaczął czytać AGENTS.md. Wątek na Hacker News dobił do 740 punktów, a w komentarzach co chwilę wracał ten sam motyw: wreszcie można skasować symlink.

Nie kasowałbym niczego w ciemno. Claude Code czyta AGENTS.md tylko wtedy, gdy w projekcie nie ma CLAUDE.md. Przez pierwsze pięć dni nie czytał go wcale, jeśli ktoś miał wyłączoną telemetrię albo pracował przez Bedrocka czy Microsoft Foundry. A dokumentacja Copilota w Visual Studio, w którym siedzi spora część zespołów .NET, o AGENTS.md nie wspomina ani słowem.

Jeden plik instrukcji dla Copilota, Claude Code i Codeksa jest dziś realny. Trzeba tylko wiedzieć, gdzie każde narzędzie odchodzi od standardu i jak sprawdzić, co faktycznie trafiło do kontekstu.

Krótka odpowiedź: wspólne instrukcje trzymaj w AGENTS.md w rootcie repo. CLAUDE.md usuń albo zostaw w nim jedną linię @AGENTS.md. W .github/copilot-instructions.md zostaw tylko to, co dotyczy wyłącznie Copilota. Po każdej zmianie sprawdź w każdym narzędziu, co się wczytało - ściągawka jest niżej.

Wszystko poniżej to stan dokumentacji na 29 września 2026. Te zachowania zmieniają się co kilka tygodni, dlatego przy każdej tezie podaję źródło.

Co to jest AGENTS.md

AGENTS.md to zwykły plik Markdown w repozytorium z instrukcjami dla agentów kodujących: jak zbudować projekt, jak uruchomić testy, jakich konwencji pilnować i czego nie ruszać. Autorzy standardu nazywają go “README dla agentów”. Nie ma wymaganych pól ani frontmattera - agent czyta tekst, który napiszesz.

Format wyszedł ze współpracy OpenAI Codex, Amp, Jules od Google, Cursora i Factory. Dziś opiekuje się nim Agentic AI Foundation pod Linux Foundation, więc to już nie jest “plik Codeksa”.

Dwie zasady z agents.md mają znaczenie w praktyce:

• W monorepo możesz mieć wiele plików. Kolejny AGENTS.md w podkatalogu opisuje ten pakiet. Według strony standardu główne repo OpenAI ma ich 88.
• Przy konflikcie wygrywa plik najbliżej edytowanego kodu, a jawne polecenie w czacie wygrywa ze wszystkim.

“Wygrywa” to jednak skrót myślowy. Claude Code i Codex sklejają pliki od roota w dół, a bliższy plik po prostu trafia do kontekstu później. Dokumentacja Copilota w VS Code i Copilot CLI mówi wprost, że instrukcje się sumują i nie ma kolejności pierwszeństwa. Model dostaje obie wersje reguły i sam wybiera, której posłucha. Sprzeczności trzeba więc usuwać u źródła, a nie liczyć na “najbliższy wygrywa”.

Jeśli pracujesz głównie z Copilotem i nie znasz jeszcze poziomów instrukcji (copilot-instructions.md, applyTo, instrukcje użytkownika), zacznij od instrukcji w GitHub Copilot. Ten tekst zakłada tamtą wiedzę i dokłada do niej pozostałe narzędzia.

Kto czyta AGENTS.md: tabela wsparcia

Z tej tabeli wynikają trzy rzeczy, których nie widać w zapowiedziach.

Visual Studio to najważniejszy wiersz dla zespołów .NET. Strona Microsoft Learn o instrukcjach dla Copilota, aktualizowana 4 września 2026, wymienia .github/copilot-instructions.md, pliki .github/instructions/*.instructions.md, instrukcje użytkownika w %USERPROFILE%/copilot-instructions.md i instrukcje organizacji. O AGENTS.md nie ma tam nic. Nowy agent w Visual Studio stoi na tym samym Copilot SDK co Copilot CLI, więc możliwe, że czyta AGENTS.md - ale nie znalazłem tego w żadnej dokumentacji ani w release notes. Dopóki tak jest, traktuj Visual Studio jak narzędzie, które nie widzi AGENTS.md, i sprawdzaj listę References.

Codex nie schodzi niżej niż katalog startowy. Buduje łańcuch instrukcji raz na sesję: od roota repo do katalogu, w którym go uruchomiłeś. Plik src/web/AGENTS.md wczyta tylko wtedy, gdy wystartujesz w src/web albo niżej. Uruchomiony z roota zobaczy wyłącznie główny AGENTS.md.

CLAUDE.md przestał być plikiem tylko dla Claude. Copilot w VS Code czyta go domyślnie (chat.useClaudeMdFile jest włączone), Copilot CLI, cloud agent i JetBrains też. To, co wpiszesz tam jako “instrukcje dla Claude”, dostanie także Copilot.

W VS Code dochodzi jeszcze wybór harnessu. Ustawienia chat.* dotyczą Local agenta. Sesja z harnessem Claude albo Codex korzysta z reguł wykrywania tamtego narzędzia, więc zachowuje się jak odpowiedni wiersz tabeli.

Pozostałe narzędzia w skrócie. Windsurf (Devin Desktop) traktuje AGENTS.md z roota jako regułę zawsze aktywną, a z podkatalogu jako regułę dla <katalog>/**. Zed bierze pierwszy pasujący plik z listy, w której .github/copilot-instructions.md stoi przed AGENTS.md - jeśli masz oba, Zed wczyta tylko instrukcje Copilota. Strona agents.md wymienia jeszcze m.in. Jules, Aider, Junie, Kilo Code i RooCode, ale ich zachowania nie weryfikowałem w dokumentacji.

Claude Code: co dokładnie zmieniło się 18 września

Changelog 2.1.277 mówi krótko: w projekcie bez CLAUDE.md Claude Code czyta AGENTS.md. Dokumentacja pamięci doprecyzowuje szczegóły, które decydują o tym, czy Twój plik w ogóle trafi do kontekstu.

Co wyłącza AGENTS.md: CLAUDE.md, .claude/CLAUDE.md albo CLAUDE.local.md w katalogu roboczym lub dowolnym katalogu wyżej. Wtedy Claude czyta tylko pliki CLAUDE.md, łącznie z podkatalogami.

Co nie wyłącza: Twój ~/.claude/CLAUDE.md, firmowy managed CLAUDE.md i pliki w .claude/rules/. One ładują się obok AGENTS.md.

Co Claude czyta, gdy nic nie blokuje: każdy AGENTS.md i .claude/AGENTS.md od katalogu roboczego w górę na starcie sesji, a AGENTS.md z podkatalogu w momencie, gdy Claude otworzy plik w tym podkatalogu. Wewnątrz AGENTS.md działają importy @ścieżka.

Czego nie czyta nigdy: AGENTS.override.md (to mechanizm Codeksa), AGENTS.local.md ani plików z katalogu .agents/.

Zachowanie zmienisz w /config, opcja Project instructions:

• claude-md-or-agents-md - domyślne, jedno albo drugie;
• claude-md-and-agents-md - oba, najpierw CLAUDE.md, potem AGENTS.md z tego samego katalogu; plik już zaimportowany nie wczyta się drugi raz;
• claude-md - tylko CLAUDE.md, jak przed 2.1.277;
• managed-only - na starcie tylko firmowy managed CLAUDE.md i auto memory; CLAUDE.md z podkatalogów i reguły ze ścieżkami nadal doładowują się w trakcie pracy, AGENTS.md nie wczytuje się wcale.

Jest haczyk dla zespołów: tej opcji nie ustawisz w repo. Claude Code ignoruje ją w .claude/settings.json projektu. Działa tylko w ustawieniach użytkownika, w pliku przekazanym przez --settings albo w managed settings:

{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

Druga pułapka jest mniej oczywista. CLAUDE.local.md też się liczy. Ktoś w zespole dodaje sobie prywatny plik z adresem swojego sandboxa i od tego momentu jego Claude Code przestaje czytać wspólny AGENTS.md. Nikt tego nie zauważy, dopóki agent nie zacznie ignorować konwencji tylko u jednej osoby. Rozwiązanie: claude-md-and-agents-md w ustawieniach tej osoby.

Jeśli chcesz mieć CLAUDE.md i jedno źródło prawdy jednocześnie, oficjalny wzorzec to import:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/Shop.Infrastructure/Migrations/`.

Claude czyta najpierw zaimportowany plik, potem resztę. Ścieżka w imporcie liczy się względem pliku, w którym stoi, a importy mogą być zagnieżdżone najwyżej na cztery poziomy. Import porządkuje pliki, ale nie oszczędza kontekstu - zaimportowana treść ładuje się na starcie tak samo jak reszta.

Jak sprawdzić, że każde narzędzie wczytało instrukcje

To jest krok, który większość zespołów pomija. Plik leży w repo, więc “na pewno działa”. Błąd z 2.1.277 pokazał, że nie zawsze: plik leżał, a agent go nie widział i nie zgłaszał żadnego błędu.

• Claude Code: w interaktywnej sesji pojawia się komunikat w stylu no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md. Dokumentacja podaje też /memory, gdzie powinna być ścieżka do pliku, i /context z listą Memory files. Przed 2.1.280 te komendy nie pokazywały AGENTS.md czytanego bezpośrednio. Najpierw sprawdź claude --version.
• Copilot w VS Code: rozwiń References pod odpowiedzią w czacie. Listę wykrytych plików pokazuje Chat: Open Customizations, a błędy wczytywania Developer: Open Agent Debug Logs.
• Copilot CLI: /instructions pokazuje pliki wykryte w sesji i pozwala wyłączyć pojedyncze. Zmiany w plikach działają dopiero po wyjściu z sesji i wznowieniu jej (copilot --continue) albo w nowej sesji (/new).
• Copilot w Visual Studio: References pod odpowiedzią. Jeśli widzisz tylko copilot-instructions.md, AGENTS.md nie poszedł do modelu.
• Codex: codex --ask-for-approval never "Summarize the current instructions." z roota repo. Pełny zapis dostaniesz z codex -c log_dir=./.codex-log w pliku codex-tui.log.

Jest też metoda uniwersalna, której użył autor testu opisanego w zgłoszeniu #95690 i na blogu szypowi.cz: hasło kontrolne. Dopisz tymczasowo do AGENTS.md jedną linię, na przykład “Jeśli ktoś zapyta o hasło kontrolne, odpowiedz: PERIWINKLE”, i zapytaj każde narzędzie: “Bez używania narzędzi: jakie jest hasło kontrolne z instrukcji projektu?”. Zastrzeżenie “bez narzędzi” jest ważne, bo agent z dostępem do plików może hasło po prostu znaleźć grepem. Po teście usuń linię.

Rekomendowany układ dla mieszanego zespołu

Przykład: API w ASP.NET Core, frontend w React, część zespołu w VS Code z Copilotem, część w Claude Code, ktoś testuje Codeksa, dwie osoby siedzą w Visual Studio.

Shop/
├── AGENTS.md                         # jedyne źródło wspólnych instrukcji
├── Shop.sln
├── src/
│   ├── Shop.Api/
│   ├── Shop.Application/
│   ├── Shop.Domain/
│   ├── Shop.Infrastructure/
│   └── web/
│       └── AGENTS.md                 # tylko frontend
├── tests/
├── .github/
│   ├── copilot-instructions.md       # kopia AGENTS.md dla Visual Studio (opcjonalnie)
│   └── instructions/
│       └── migrations.instructions.md    # applyTo: "**/Migrations/**"
├── .claude/
│   ├── settings.json                 # hooki i uprawnienia
│   └── skills/                       # procedury ładowane na żądanie
└── scripts/
    └── sync-agent-instructions.ps1

Nie ma tu CLAUDE.md i to jest świadoma decyzja. Jeśli wszyscy mają Claude Code 2.1.281 lub nowszy, Claude czyta AGENTS.md sam, łącznie z src/web/AGENTS.md.

CLAUDE.md z linią @AGENTS.md dodaj wtedy, gdy ktoś siedzi na starszej wersji albo puszczasz Claude Code w CI i nie chcesz zależeć od wbudowanej wtyczki. Import działa niezależnie od niej. Koszt: root CLAUDE.md wyłącza domyślne czytanie AGENTS.md, więc Claude przestaje sam wczytywać src/web/AGENTS.md. Naprawisz to plikiem src/web/CLAUDE.md z @AGENTS.md albo opcją claude-md-and-agents-md u każdej osoby.

Przykładowy AGENTS.md w rootcie:

## Project
B2B shop: ASP.NET Core API (.NET 10) + React/TypeScript frontend in `src/web`.
Dependencies point inward: `Shop.Api` -> `Shop.Application` -> `Shop.Domain`.
EF Core lives only in `Shop.Infrastructure`.
Frontend rules: `src/web/AGENTS.md`.

## Commands (run from repo root)
- Build: `dotnet build Shop.sln`
- Test: `dotnet test Shop.sln`
- Format check: `dotnet format Shop.sln --verify-no-changes`
- New migration: `dotnet ef migrations add <Name> --project src/Shop.Infrastructure --startup-project src/Shop.Api`

## Definition of done
- Build and tests pass. If you changed `src/web`, also run `npm run lint` and `npm test` there.
- Say which checks you ran. If you could not run one, say which and why.

## Conventions
- Business errors return `Result<T>`; do not throw for validation.
- Validation with FluentValidation, one validator per request type.
- Tests: xUnit, names `Method_Scenario_Expected`.

## Boundaries
- Never edit existing migrations; add a new one.
- Do not add NuGet or npm packages without asking.
- No secrets in `appsettings*.json`; use `dotnet user-secrets`.

I zagnieżdżony src/web/AGENTS.md:

# Frontend (src/web)
- Install with `npm ci`, never `npm install` in CI.
- Before done: `npm run lint`, `npm test`, `npm run build`.
- Do not edit files in `src/api/generated`; they are generated from the API contract.

Kilka decyzji w tym pliku jest celowych.

Komendy są pełne i uruchamialne. dotnet test Shop.sln, a nie “uruchom testy”. Agent nie musi zgadywać, który projekt jest startowy przy migracji, i nie traci na to trzech kroków.

Linia “Frontend rules: src/web/AGENTS.md” to wskaźnik dla narzędzi, które zagnieżdżonych plików same nie wczytają: Codeksa uruchomionego z roota, Copilota w VS Code bez eksperymentalnego ustawienia, code review na github.com. Wskaźnik niczego nie gwarantuje, bo agent musi sam zdecydować, że plik otworzy. Ale zwykle to robi, gdy pracuje w tym katalogu.

Zwykła ścieżka zamiast @src/web/AGENTS.md. Import @ rozwijają Claude Code i Copilot CLI. Dokumentacja Codeksa i Copilota w VS Code nic o nim nie mówi, więc tam zostanie literalnym tekstem. W pliku, który ma czytać każde narzędzie, trzymaj się zwykłego Markdownu.

Nie ma tu struktury katalogów, listy zależności ani opisu architektury na dwa ekrany. Agent sam to odczyta z repo, a każda linia w AGENTS.md jedzie z każdym zapytaniem. Nawet /doctor w Claude Code proponuje wycinać z CLAUDE.md dokładnie te rzeczy: układ katalogów, listy zależności i przeglądy architektury. Więcej o tym, dlaczego to się mści w długich sesjach, w tekście o higienie context window i w lekcji o context engineeringu.

Heurystyka na każdą linię: jeśli regułę zrozumiałby nowy człowiek w zespole pierwszego dnia, idzie do AGENTS.md. Jeśli opisuje mechanikę konkretnego narzędzia, idzie do pliku tego narzędzia.

Co zostaje w plikach konkretnych narzędzi

AGENTS.md nie ma frontmattera, globów ani hooków. Wszystko, co wymaga tych mechanizmów, zostaje przy narzędziu.

Copilot:

• .github/instructions/*.instructions.md z applyTo - reguły dla typów plików, np. migracji albo testów. AGENTS.md potrafi zawęzić instrukcje tylko do katalogu, nie do wzorca pliku. Jak to ustawić, opisałem w instrukcjach w GitHub Copilot i w lekcji o scoped instructions.
• .github/copilot-instructions.md tylko z regułami specyficznymi dla Copilota. Tak zresztą dzieli to sam GitHub w dokumentacji code review: copilot-instructions.md na reguły dla Copilota, AGENTS.md na reguły wspólne dla wszystkich agentów.
• Własne agenty w .github/agents/, opisane w tekście o custom agents w Copilocie.

Claude Code:

• Hooki w .claude/settings.json. To jest miejsce na rzeczy, które mają się wydarzyć zawsze, np. dotnet format po edycji pliku .cs. Dokumentacja Anthropic mówi jasno, że CLAUDE.md i AGENTS.md to kontekst, a nie wymuszenie - jeśli coś ma być zablokowane niezależnie od decyzji modelu, potrzebujesz hooka PreToolUse.
• Skille na procedury wieloetapowe, które nie muszą siedzieć w kontekście non stop. Jak je pisać, żeby agent faktycznie je odpalał: czym są skille.
• .claude/rules/ z polem paths. Uwaga: Copilot w VS Code też czyta .claude/rules, więc to nie jest schowek na rzeczy tylko dla Claude.
• Szerszy przykład konfiguracji Claude Code z plików .md znajdziesz w tekście o asystencie w Claude Code.

Codex:

• AGENTS.override.md na tymczasowe albo serwisowe nadpisania. Claude Code go nie czyta, więc wszystko, co tam wpiszesz, zobaczy tylko Codex.
• Sekcja ## Code Review Rules w najbliższym AGENTS.md, jeśli używasz Codex code review na GitHubie. Żyje w AGENTS.md, więc przeczytają ją też inne narzędzia. Przy regułach review to zwykle nie przeszkadza.

Preferencje osobiste nigdy nie idą do repo: ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.copilot/copilot-instructions.md dla Copilot CLI albo profil VS Code. Podział na poziom użytkownika i projektu rozkłada lekcja User-level vs Project-level.

Migracja z trzech plików do jednego

Typowy stan wyjściowy: CLAUDE.md pisany przez jedną osobę, .github/copilot-instructions.md przez drugą, oba częściowo o tym samym i częściowo sprzeczne.

1. Zrób inwentaryzację. W PowerShellu:

git ls-files | Select-String -Pattern 'AGENTS\.md|CLAUDE(\.local)?\.md|GEMINI\.md|copilot-instructions\.md|\.instructions\.md|\.cursorrules|\.cursor/rules'

Zwróć uwagę na zagnieżdżone CLAUDE.md w podkatalogach. Katalog z własnym CLAUDE.md odbiera Claude’owi AGENTS.md z tego katalogu.

2. Wyciągnij część wspólną do AGENTS.md. Komendy, definicja gotowości, konwencje, granice. Sprzeczności rozstrzygnij teraz, w tym PR. “Ujednolicimy potem” oznacza, że przez następne miesiące dwa narzędzia będą dostawały dwie różne reguły.

3. Nie używaj /import z Claude Code jako ścieżki migracji. Ta komenda dopisuje jednorazową kopię AGENTS.md do CLAUDE.md. Dostajesz dwa pliki, które zaczną się rozjeżdżać przy pierwszej zmianie.

4. Zdecyduj o CLAUDE.md. Usuń go, jeśli cały zespół ma Claude Code 2.1.281+. Zostaw z @AGENTS.md, jeśli potrzebujesz zgodności wstecz albo CI. Nie zostawiaj CLAUDE.md z tekstem “przeczytaj AGENTS.md” - według dokumentacji Claude zobaczy wtedy AGENTS.md tylko, jeśli sam zdecyduje się go otworzyć.

5. Odchudź .github/copilot-instructions.md. Zostaje w nim to, co dotyczy tylko Copilota. Jeśli ktoś w zespole używa Copilota w Visual Studio, zrób z tego pliku generowaną kopię AGENTS.md, a reguły tylko dla Copilota przenieś do .github/instructions/ z applyTo: "**". Skrypt jest jednolinijkowy:

Copy-Item -Path AGENTS.md -Destination .github/copilot-instructions.md -Force

A w CI krok, który nie przepuści rozjazdu:

- name: copilot-instructions.md must match AGENTS.md
  run: git diff --no-index --exit-code AGENTS.md .github/copilot-instructions.md

Copilot w VS Code dostanie wtedy tę samą treść dwa razy. Copilot CLI według dokumentacji usuwa identyczne duplikaty, VS Code o tym nic nie mówi. Identyczny duplikat kosztuje tokeny, ale nie tworzy konfliktu. Konflikt robią dwie różne wersje tej samej reguły.

6. Usuń stare obejścia. Hook SessionStart, który wypisywał AGENTS.md do kontekstu, teraz dokłada drugą kopię. Symlinki możesz zostawić albo skasować - Claude przeczyta treść raz.

7. Sprawdź każde narzędzie metodą z sekcji wyżej. Dopiero wtedy zamknij PR.

Pułapki

Wyłączona telemetria i błąd w wersjach 2.1.277-2.1.280

Przez pierwsze pięć dni AGENTS.md w Claude Code nie działał w sesjach z wyłączoną telemetrią ani na Bedrocku, Vertexie i Foundry. Te trzy platformy pierwotny wpis 2.1.277 wykluczał wprost dopiskiem “not yet on Bedrock, Vertex or Foundry” (później usuniętym z changelogu), ale o wyłączonej telemetrii nie wspominał. Tam plik po prostu się nie wczytywał, bez żadnego błędu. Changelog 2.1.281 z 23 września rozszerza obsługę na Amazon Bedrock, Google Vertex AI, Microsoft Foundry, bramki LLM i sesje z wyłączoną telemetrią.

Mechanizm opisali użytkownicy w zgłoszeniu #95690 i na blogu autora testu: obsługa AGENTS.md to wbudowana wtyczka, którą włączała zdalna flaga. Z ustawionym DISABLE_TELEMETRY albo CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC flagi się nie pobierały. Ustawienie wartości 0 nic nie zmieniało, bo dla tych zmiennych liczy się sama obecność. W wątku na Hacker News autor zmiany z Anthropic (tak się przedstawił) tłumaczył, że chodziło o możliwość zdalnego wyłączenia funkcji, gdyby coś się zepsuło, i nazwał to błędem przy wdrożeniu.

Dla zespołów .NET to nie jest egzotyka. W firmowych konfiguracjach wyłączona telemetria nie jest niczym niezwykłym, a Claude w Azure idzie przez Microsoft Foundry. Co zrobić dziś:

• claude --version u każdego, minimum 2.1.281;
• dokumentacja nadal wymienia wyjątek: w niektórych przypadkach pierwsza sesja po aktualizacji z 2.1.276 lub starszej nie wczyta AGENTS.md, kolejna już tak;
• w CI, gdzie każda instalacja jest świeża, nie zakładaj - sprawdź log albo użyj CLAUDE.md z @AGENTS.md, który nie zależy od wtyczki.

Zgłoszenie #95690 jest nadal otwarte, choć changelog i dokumentacja traktują sprawę jako naprawioną.

Sprzeczne instrukcje w dwóch plikach

Typowy scenariusz po niedokończonej migracji: AGENTS.md mówi “testy w xUnit”, a stary copilot-instructions.md nadal ma “używaj NUnit”. Copilot w VS Code dostaje oba pliki. Dokumentacja VS Code pisze wprost: źródła instrukcji się sumują i nie należy liczyć na żadną kolejność. Wynik zależy od tego, którą regułę model uzna za ważniejszą w danym zapytaniu.

To samo dzieje się w Claude Code między ~/.claude/CLAUDE.md a projektem. W Claude Code 2.1.283+ /doctor prompt-audit przegląda CLAUDE.md, CLAUDE.local.md i AGENTS.md, szuka sprzeczności, odwołań do nieistniejących plików i komend, i proponuje poprawki. Niczego nie zmienia bez Twojej zgody.

Limity rozmiaru

Codex domyślnie czyta do 32 KiB instrukcji (project_doc_max_bytes), resztę ucina. Limit podniesiesz w ~/.codex/config.toml, ale zwykle lepiej skrócić plik. Anthropic zaleca poniżej 200 linii na plik i ostrzega, że dłuższe pliki pogarszają przestrzeganie reguł. Dla Copilota nie znalazłem aktualnego twardego limitu, ale zasada jest ta sama: instrukcje jadą z każdym zapytaniem. AGENTS.md na 600 linii to nie dokumentacja projektu, tylko stały podatek od każdej odpowiedzi.

Symlinki na Windowsie

ln -s AGENTS.md CLAUDE.md to najpopularniejsze obejście z Hacker News i na Windowsie najgorsze.

• Utworzenie symlinku wymaga uprawnień administratora albo włączonego trybu dewelopera.
• Git for Windows domyślnie wyłącza obsługę symlinków, chyba że wykryje tryb dewelopera. Bez core.symlinks=true symlink trafia na dysk jako zwykły plik tekstowy zawierający ścieżkę. Twój CLAUDE.md ma wtedy jedną linię: AGENTS.md.
• ln -s w Git Bash domyślnie nie tworzy symlinku, tylko kopię. Kopia wygląda na działającą do pierwszej zmiany w AGENTS.md.

Anthropic w dokumentacji odradza symlink wprost, jeśli ktokolwiek w zespole pracuje na Windowsie. Import @AGENTS.md albo skrypt kopiujący z kontrolą w CI działa wszędzie tak samo.

Nieaktualne instrukcje

Najdroższa pułapka, bo cicha. Zespół przechodzi z npm na pnpm, a AGENTS.md dalej każe uruchamiać npm ci. Agent wykonuje komendę, dostaje błąd, próbuje ją naprawić i spala kilka kroków na problem, którego nie ma. Po trzech miesiącach takich drobiazgów instrukcje szkodzą bardziej, niż pomagają.

Dwie praktyczne zasady. Zmiana w pipeline albo w komendzie builda idzie w tym samym PR co zmiana w AGENTS.md. I dopisz AGENTS.md do CODEOWNERS, żeby zmiany w nim przechodziły przez review jak kod, bo w praktyce są kodem - tylko uruchamianym przez model.

FAQ

Co to jest AGENTS.md?

To plik Markdown w repozytorium z instrukcjami dla agentów AI: komendy do budowania i testów, konwencje i granice. Nie ma wymaganych pól. Czytają go m.in. Codex, Cursor, GitHub Copilot w VS Code, Copilot CLI, cloud agent i code review, a od wersji 2.1.277 także Claude Code. Standardem opiekuje się Agentic AI Foundation w ramach Linux Foundation.

AGENTS.md czy CLAUDE.md - co czyta Claude Code?

Domyślnie jedno albo drugie. Jeśli w katalogu roboczym lub wyżej jest CLAUDE.md, .claude/CLAUDE.md albo CLAUDE.local.md, Claude Code czyta tylko pliki CLAUDE.md. AGENTS.md czyta, gdy ich nie ma. Żeby czytał oba, ustaw w /config opcję Project instructions na claude-md-and-agents-md albo dodaj do CLAUDE.md linię @AGENTS.md.

Czy GitHub Copilot czyta AGENTS.md?

Tak w VS Code (ustawienie chat.useAgentsMdFile, domyślnie włączone), w Copilot CLI, w cloud agencie i w code review na github.com, gdzie liczy się tylko plik z roota. Zagnieżdżone pliki w VS Code wymagają eksperymentalnego chat.useNestedAgentsMdFiles. Dokumentacja Copilota w Visual Studio z 4 września 2026 wymienia .github/copilot-instructions.md, pliki *.instructions.md, instrukcje użytkownika i organizacji, ale nie AGENTS.md.

Jak sprawdzić, czy agent wczytał AGENTS.md?

W Claude Code szukaj komunikatu o wczytaniu AGENTS.md na starcie sesji i sprawdź /memory albo /context. W Copilocie rozwiń listę References pod odpowiedzią, w Copilot CLI użyj /instructions. W Codeksie uruchom codex --ask-for-approval never "Summarize the current instructions.". Uniwersalny test to tymczasowe hasło kontrolne w pliku i pytanie o nie bez użycia narzędzi.

Czy symlink CLAUDE.md do AGENTS.md działa na Windowsie?

Da się go zrobić, ale jest kruchy. Wymaga uprawnień administratora albo trybu dewelopera, a Git for Windows bez core.symlinks=true zapisze go jako jednolinijkowy plik tekstowy. ln -s w Git Bash domyślnie tworzy kopię. Bezpieczniej użyć w CLAUDE.md importu @AGENTS.md.

Czy usuwać .github/copilot-instructions.md po przejściu na AGENTS.md?

Nie trzeba. Copilot łączy go z AGENTS.md, więc zostaw w nim tylko reguły specyficzne dla Copilota, a wspólne przenieś do AGENTS.md. Wyjątek to zespoły z Copilotem w Visual Studio: tam niech copilot-instructions.md będzie generowaną kopią AGENTS.md z kontrolą zgodności w CI.

Źródła: AGENTS.md (format, zagnieżdżanie, opieka Linux Foundation), Claude Code - memory i AGENTS.md (reguły wczytywania, Project instructions, import, Windows), Claude Code - changelog (2.1.277, 2.1.281, 2.1.283), Claude Code - wtyczka agents-md, zgłoszenie #95690, szypowi.cz - AGENTS.md tylko z włączoną telemetrią, Hacker News - dyskusja o wydaniu i o błędzie, VS Code - custom instructions, VS Code - ustawienia Copilota, GitHub Docs - instrukcje repozytorium, GitHub Docs - wsparcie typów instrukcji, GitHub Docs - Copilot CLI, GitHub Docs - Copilot code review, GitHub Changelog - JetBrains, marzec 2026, Microsoft Learn - instrukcje w Visual Studio, Visual Studio Blog - agent na Copilot SDK, OpenAI - Codex i AGENTS.md, Cursor - rules, Gemini CLI - GEMINI.md, Zed - instructions, Windsurf - AGENTS.md, Git for Windows - symbolic links.

EfektywnyDev pisze o AI w praktyce - o tym, co agent faktycznie dostaje w kontekście, a nie o tym, co obiecuje zapowiedź.