Jeden projekt, wielu agentów — wspólny kontekst dla Claude Code i Codex · Wiki

Masz projekt, który ładnie działa w Claude Code. Otwierasz ten sam folder w Codeksie i nagle agent nie wie, gdzie cokolwiek leży — nie widzi twoich instrukcji, nie zna twoich skrótów, zachowuje się jak ktoś, kto pierwszy raz wszedł do biura. Nie jest głupszy. Po prostu szuka plików pod innymi nazwami.

Pokażę ci, jak ustawić projekt tak, żeby oba narzędzia — i każde kolejne, które dojdzie — pracowały na tej samej wiedzy. Najpierw nazwę problem, potem rozłożę go na trzy warstwy, a na końcu dam ci gotowy schemat folderów i jedną komendę, która zrobi większość konwersji za ciebie.

Problem w trzech zdaniach

Każdy agent kodujący potrzebuje trzech rzeczy: instrukcji (kim jest, co wolno, jak pracuje w tym projekcie), gotowych przepływów pracy (powtarzalnych procedur) i ustawień technicznych (uprawnienia, zmienne, serwery). To jest wspólne dla wszystkich.

Różnica jest jedna: każde narzędzie szuka tych rzeczy pod inną nazwą i w innym miejscu.

Claude Code czyta plik CLAUDE.md i folder .claude/.
Codex czyta plik AGENTS.md, folder .codex/ oraz .agents/skills/.

Jeśli całą wiedzę o projekcie wpiszesz tylko do plików Claude'a, Codex jej nie zobaczy — i odwrotnie. Stąd biuro, w którym nowy pracownik błądzi.

Rozwiązanie nie polega na wybraniu jednego narzędzia. Polega na tym, żeby prawdziwą wiedzę o projekcie trzymać w neutralnych folderach, a każdemu narzędziu dać tylko cienki plik-adapter, który mówi „twoje instrukcje są tam”.

Jak każde narzędzie układa projekt

Ta sama idea, inne nazwy. Warto je raz zobaczyć obok siebie, bo potem cała reszta jest tylko trzymaniem tego w porządku.

Claude Code

Claude trzyma wszystko w jednym folderze.

Instrukcje: CLAUDE.md w katalogu głównym projektu — ładuje się automatycznie.
Konfiguracja: folder .claude/ — mieszczą się w nim umiejętności, agenci, reguły i ustawienia.
Umiejętności (skills): .claude/skills/<nazwa>/SKILL.md — to twoje własne, nazwane przepływy pracy, które agent może wywołać.
Pod-agenci: .claude/agents/<nazwa>.md — plik Markdown z krótkim nagłówkiem na górze.
Ustawienia: .claude/settings.json — uprawnienia, zmienne środowiskowe, automatyczne akcje.
Konfiguracja globalna: ~/.claude/ — ta sama struktura, ale działa dla każdego projektu na twoim komputerze.

Codex

Codex rozdziela to na dwie części: konfiguracja i agenci żyją w .codex/, a umiejętności osobno w .agents/.

Instrukcje: AGENTS.md w katalogu głównym — też ładuje się automatycznie.
Szybkie nadpisanie: AGENTS.override.md — sposób na chwilową zmianę instrukcji bez ruszania AGENTS.md.
Konfiguracja: folder .codex/ — konfiguracja i definicje agentów.
Umiejętności: .agents/skills/<nazwa>/SKILL.md — Codex szuka ich od bieżącego folderu w górę, aż do korzenia repozytorium.
Pod-agenci: .codex/agents/<nazwa>.toml — format TOML, nie Markdown.
Ustawienia: .codex/config.toml — piaskownica (tryb bezpieczny), serwery, zmienne, profile.
Konfiguracja globalna: ~/.codex/ na konfigurację i agentów oraz ~/.agents/skills/ na umiejętności.

Zwróć uwagę na jeden szczegół, który łatwo przeoczyć: Claude w domu trzyma wszystko w ~/.claude/, a Codex rozbija to na dwa miejsca — ~/.codex/ i ~/.agents/skills/. To nie jest dowolność. To po prostu inna konwencja i wystarczy ją raz zapamiętać.

Co to znaczy w twoim folderze

Najprościej zobaczyć to na jednym drzewie. Wszystkie trzy warstwy w jednym projekcie wyglądają tak:

twoj-projekt/
  CLAUDE.md            # instrukcje dla Claude Code
  AGENTS.md            # instrukcje dla Codeksa
  README.md            # opis dla człowieka

  .claude/             # ustawienia, agenci, umiejętności Claude'a
    settings.json
    agents/moj-agent.md
    skills/moja-umiejetnosc/SKILL.md

  .codex/              # ustawienia i agenci Codeksa
    config.toml
    agents/moj-agent.toml

  .agents/             # umiejętności Codeksa
    skills/moja-umiejetnosc/SKILL.md

  references/          # wspólna wiedza — czyta ją każdy agent
    project-context.md

Trzy grupy na tym drzewie: pliki Claude'a, pliki Codeksa i — najważniejsze — folder references/, do którego sięgają oba. To w nim ma mieszkać prawdziwa wiedza o projekcie.

Abstrakcyjny schemat trzech warstw projektu: u góry jedno wspólne źródło wiedzy zasilające dwa narzędzia, w środku zsynchronizowane przepływy pracy, na dole rozdzielona konfiguracja — w grafitowo-zielono-stalowej palecie.

Pięć rzeczy, które zaskakują na starcie

To są różnice, których nie da się zamieść pod dywan. Lepiej poznać je teraz niż przy pierwszym błędzie.

Oba mają umiejętności, ale w innych folderach. Claude czyta z .claude/skills/, Codex z .agents/skills/. Sam plik SKILL.md ma podobny kształt, ale nazwy narzędzi czy automatyczne akcje specyficzne dla Claude'a mogą wymagać drobnej korekty pod Codeksa.

Agenci mają różne formaty. Agent Claude'a to plik .md z krótkim nagłówkiem. Agent Codeksa to plik .toml. Treść roli bywa ta sama — opakowanie jest inne.

Plików ustawień nie da się przekleić. Nie skopiujesz .claude/settings.json do .codex/config.toml. To inne formaty, które konfigurują inne rzeczy. Trzymaj je osobno.

Codex czyta zagnieżdżone instrukcje. Oba narzędzia rozumieją CLAUDE.md lub AGENTS.md położony w podfolderze — to lokalne instrukcje dla tej części projektu. Codex łączy je od korzenia repozytorium w dół, do bieżącego folderu. Wygrywa plik najbliższy.

Pod-agenci działają inaczej. Markdown kontra TOML to nie tylko inny zapis — to też inny model uruchamiania. Sama rola może brzmieć podobnie, ale nie zakładaj, że plik przeniesie się jeden do jednego.

I jeden bonus, który spina to wszystko: wspólny kontekst trzymaj poza folderami narzędzi. Powtarzalną wiedzę wkładaj do docs/, references/, templates/. Wtedy oba narzędzia czytają to samo źródło, zamiast rozjeżdżać się z czasem.

Reguła trzech warstw

Cała ta układanka sprowadza się do jednej zasady, którą warto sobie powiesić nad biurkiem. Rozdziel projekt na trzy warstwy, a nigdy nie napiszesz tej samej rzeczy dwa razy.

Warstwa 1 — wspólna wiedza. Mieszka w references/, docs/, templates/. Czyta ją każdy agent. Tu nie duplikujesz niczego: jedno źródło prawdy o tym, czym jest projekt, jak wygląda, jakie ma zasady.

Warstwa 2 — przepływy pracy (umiejętności). Ten sam podstawowy kształt SKILL.md w dwóch folderach: .claude/skills/ dla Claude'a i .agents/skills/ dla Codeksa. Synchronizujesz pliki, a potem — jeśli trzeba — dostrajasz szczegóły specyficzne dla narzędzia.

Warstwa 3 — konfiguracja narzędzia. Zostaje w .claude/ i .codex/. Te dwie warstwy się nie pokrywają. Nie próbuj ich łączyć.

To częsty błąd, który widzę: ludzie wpisują opis projektu wprost do CLAUDE.md, a potem do AGENTS.md i utrzymują dwie pełne kopie. Po miesiącu kopie się rozjeżdżają i żaden agent nie ma już aktualnej prawdy. Jedno źródło w references/, dwa cienkie adaptery, które tam wskazują — i problem znika.

Najszybszy sposób na konwersję projektu z Claude'a

Jeśli masz już projekt zbudowany pod Claude Code, nie przepisuj go ręcznie. Otwórz go w Codeksie i poproś, żeby sam dołożył warstwę adaptera. Wklejasz polecenie w tym duchu:

Zbudowałem ten projekt w Claude Code i chcę, żeby działał też w Codeksie. Przejrzyj projekt i utwórz warstwę adaptera dla Codeksa. Konkretnie: 1. Utwórz AGENTS.md w katalogu głównym. Użyj CLAUDE.md jako źródła wiedzy o projekcie, nie duplikuj długich fragmentów bez potrzeby, wyjaśnij, że AGENTS.md jest adapterem pod Codeksa, i dołącz czytelną mapę projektu. 2. Utwórz .codex/config.toml — zacznij od minimalnej, bezpiecznej konfiguracji, bez żadnych sekretów. 3. Utwórz .agents/skills/ i skopiuj tam ważne umiejętności z .claude/skills/. Każdy SKILL.md zostaw razem z plikami pomocniczymi. Nie wkładaj umiejętności do .codex/skills/. 4. Utwórz .codex/agents/ dla ważnych agentów. Agenci Claude'a to pliki .md; agenci Codeksa to .toml. Przełóż treść instrukcji na format Codeksa. 5. Zaktualizuj .gitignore, żeby lokalne nadpisania i sekrety nie trafiły do repozytorium. Zanim cokolwiek zmienisz, pokaż mi listę plików, które chcesz utworzyć lub edytować.

Sednem jest ostatnie zdanie i jedna zasada nad nim: nie przebudowuj projektu — dołóż warstwę Codeksa obok warstwy Claude'a. Nie ruszasz tego, co działa. Dokładasz drugi adapter do tego samego źródła wiedzy. A prośba o listę plików przed edycją to twój hamulec bezpieczeństwa: widzisz, co agent zamierza zrobić, zanim to zrobi.

Jak to utrzymać w zgodzie

Cały układ działa tylko wtedy, gdy oba narzędzia zostają zsynchronizowane. To kwestia czterech nawyków, nie ciągłej pracy.

Zmieniasz instrukcje projektu? Trzymaj CLAUDE.md i AGENTS.md w zgodzie. Nie utrzymuj dwóch pełnych kopii — wybierz jeden plik jako źródło prawdy, a drugi zrób cienkim adapterem, który do niego odsyła.
Tworzysz umiejętność dla Claude'a? Skopiuj ją do .agents/skills/, jeśli Codex też ma jej używać.
Tworzysz agenta dla Claude'a? Dorób odpowiadający mu .codex/agents/<nazwa>.toml, jeśli Codex ma go uruchamiać.
Dokładasz wspólną wiedzę? Wkładaj ją do docs/, references/ lub templates/, żeby każde narzędzie czytało to samo źródło.

Zasada, którą warto stąd wynieść, jest prostsza niż cała ta tabela nazw: wiedza o projekcie należy do projektu, nie do narzędzia. Im więcej prawdy trzymasz we wspólnych folderach, a im cieńsze są twoje pliki-adaptery, tym łatwiej dołożysz trzeci, czwarty i każdy kolejny agent — bez przepisywania niczego od nowa.

Następny krok jest mały: otwórz swój projekt i sprawdź, gdzie dziś mieszka opis tego, czym on jest. Jeśli siedzi w CLAUDE.md, przenieś go do references/ i zostaw w CLAUDE.md tylko wskazówkę, gdzie szukać. To jedno przesunięcie i połowa pracy za tobą.