Wspólny kontekst dla agentów kodujących — przewodnik konfiguracji

To jest wersja do trzymania pod ręką. Otwierasz ją w trakcie konfiguracji, sprawdzasz nazwy plików i odhaczasz kroki. Cała wiedza o projekcie zostaje w katalogach współdzielonych; każde narzędzie dostaje tylko swoje pliki-adaptery, które wskazują na to samo źródło.

Zasada przewodnia jednym zdaniem: nie duplikuj wiedzy o projekcie — daj każdemu narzędziu plik, którego oczekuje, a treść trzymaj w jednym miejscu.

Problem w jednym akapicie

Każdy agent kodujący potrzebuje trzech rzeczy: instrukcji, powtarzalnych przepływów pracy i ustawień narzędzia. Problem w tym, że każde narzędzie nazywa te pliki inaczej.

• Claude Code szuka CLAUDE.md i katalogu .claude/.
• Codex szuka AGENTS.md, katalogu .codex/ oraz .agents/skills/.

Rozwiązanie: dajesz każdemu narzędziu pliki, których oczekuje, ale prawdziwą wiedzę o projekcie trzymasz w katalogach współdzielonych — docs/, references/, templates/. Oba narzędzia czytają to samo źródło. Różnią się tylko plikami-adapterami.

Mapa plików — co gdzie mieszka

Claude Code (agent kodujący Anthropic)

Wszystko w jednym katalogu: ustawienia, agenci, umiejętności.

• Instrukcje — CLAUDE.md. Leży w katalogu głównym projektu. Ładuje się automatycznie.
• Katalog konfiguracji — .claude/. Mieści umiejętności, agentów, reguły i ustawienia.
• Umiejętności (skills) — .claude/skills/<nazwa>/SKILL.md. Komendy ukośnikowe, które budujesz samodzielnie.
• Subagenci — .claude/agents/<nazwa>.md. Markdown z krótkim nagłówkiem YAML na górze.
• Ustawienia — .claude/settings.json. Hooki, uprawnienia, zmienne środowiskowe.
• Konfiguracja globalna — ~/.claude/. Ta sama struktura, ale obowiązuje w każdym projekcie na twojej maszynie.

Codex (agent kodujący OpenAI)

Konfiguracja i agenci żyją w .codex. Umiejętności żyją osobno, w .agents.

• Instrukcje — AGENTS.md. Leży w katalogu głównym projektu. Ładuje się automatycznie.
• Tymczasowy override — AGENTS.override.md. Szybki sposób na nadpisanie AGENTS.md bez edytowania go.
• Katalog konfiguracji — .codex/. Mieści konfigurację i definicje agentów.
• Katalog umiejętności — .agents/skills/<nazwa>/SKILL.md. Codex skanuje od bieżącego katalogu w górę, aż do korzenia repozytorium.
• Subagenci — .codex/agents/<nazwa>.toml. Format TOML, nie markdown.
• Ustawienia — .codex/config.toml. Sandbox, serwery MCP, zmienne środowiskowe, profile.
• Konfiguracja globalna — ~/.codex/ oraz ~/.agents/skills/. Globalna konfiguracja i agenci żyją w ~/.codex; globalne umiejętności żyją w ~/.agents/skills.

Globalne vs projektowe

Oba narzędzia obsługują oba poziomy. Pliki globalne leżą w katalogu domowym i obowiązują wszędzie; pliki projektowe leżą wewnątrz jednego repozytorium.

• ~/.claude/ jest lustrem .claude/.
• Codex rozdziela pliki globalne: ~/.codex/ na konfigurację i agentów, ~/.agents/skills/ na umiejętności.

Jak to wygląda w katalogu

Claude Code

your-project/
  CLAUDE.md
  .claude/
    settings.json
    agents/
      researcher.md
    skills/
      youtube-video/
        SKILL.md

Codex

your-project/
  AGENTS.md
  .codex/
    config.toml
    agents/
      researcher.toml
  .agents/
    skills/
      youtube-video/
        SKILL.md

Jeden projekt obsługujący oba narzędzia

your-project/
  CLAUDE.md            # instrukcje dla Claude
  AGENTS.md            # instrukcje dla Codex
  README.md            # przegląd dla człowieka

  .claude/             # ustawienia, agenci, umiejętności Claude
    settings.json
    agents/my-agent.md
    skills/my-skill/SKILL.md

  .codex/              # ustawienia i agenci Codex
    config.toml
    agents/my-agent.toml

  .agents/             # umiejętności Codex
    skills/my-skill/SKILL.md

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

Trzy kolory plików, o których warto myśleć: pliki Claude Code, pliki Codex, pliki współdzielone (dowolne narzędzie).

Ściąga — gdzie co leży

Kiedy zapomnisz, gdzie coś mieszka, ta tabela ma odpowiedź.

Pięć rzeczy, na których potykają się początkujący

Przeczytaj to, zanim zaczniesz. To różnice, których nie da się obejść.

1. Oba narzędzia mają umiejętności, ale w różnych katalogach. Claude czyta z .claude/skills/, Codex czyta z .agents/skills/. Ten sam podstawowy kształt SKILL.md, ale nazwy narzędzi specyficzne dla Claude albo hooki mogą wymagać drobnych poprawek dla Codeksa.

2. Różne formaty agentów. Agent Claude to plik .md z krótkim nagłówkiem YAML. Agent Codeksa to plik .toml. Instrukcje w środku to ta sama idea, tylko inaczej opakowana.

3. Pliki ustawień nie są wymienne. Nie skopiujesz .claude/settings.json do .codex/config.toml. To różne formaty i konfigurują różne rzeczy. Trzymaj je osobno.

4. Codex czyta instrukcje zagnieżdżone. Oba narzędzia obsługują CLAUDE.md lub AGENTS.md wewnątrz podkatalogu — instrukcje zawężone do tego miejsca. Codex łączy je w łańcuch od korzenia repozytorium w dół, aż do twojego bieżącego katalogu. Wygrywa plik bliższy.

5. Subagenci działają inaczej. Agenci Claude to pliki markdown, agenci Codeksa to pliki TOML. Prompt roli może być podobny, ale opakowanie i model wykonania są różne.

Bonus: trzymaj wspólny kontekst poza katalogami narzędzi. Wkładaj wiedzę wielokrotnego użytku do docs/, references/ i templates/. Wtedy oba narzędzia czytają to samo źródło zamiast się rozjeżdżać.

Zasada trzech warstw

Podziel projekt na trzy warstwy. Rozdziel treść w ten sposób, a nigdy nie napiszesz tego samego dwa razy.

1. Wiedza współdzielona. Żyje w references/, docs/, templates/. Czyta ją każdy agent. Nie duplikuj.
2. Przepływy pracy (umiejętności). Ten sam podstawowy kształt SKILL.md w dwóch katalogach: .claude/skills/ dla Claude, .agents/skills/ dla Codeksa. Zsynchronizuj pliki, potem dostrój szczegóły specyficzne dla narzędzia, jeśli trzeba.
3. Konfiguracja specyficzna dla narzędzia. Zostaje w .claude/ i .codex/. Te się nie pokrywają. Nie próbuj ich łączyć.

Najszybsza droga: konwersja projektu Claude na Codex

Otwierasz projekt zbudowany w Claude w Codeksie i wklejasz poniższy prompt. Codex utworzy pliki-adaptery za ciebie.

Zbudowałem ten projekt w Claude Code i chcę, żeby działał także dobrze w Codeksie. Przejrzyj projekt i utwórz konfigurację adaptera dla Codeksa. Zrób następujące rzeczy: 1. Utwórz AGENTS.md w katalogu głównym projektu. - Użyj CLAUDE.md jako źródła wiedzy o projekcie. - Nie powielaj niepotrzebnie długich sekcji. - Wyjaśnij, że AGENTS.md jest adapterem od strony Codeksa. - Dołącz czytelną mapę projektu. 2. Utwórz .codex/config.toml. - Zacznij od minimalnej, bezpiecznej konfiguracji. - Nie dodawaj sekretów. 3. Utwórz .agents/skills/. - Skopiuj ważne umiejętności Claude z .claude/skills/ do .agents/skills/. - Trzymaj razem każdy SKILL.md i pliki towarzyszące. - Nie wkładaj umiejętności do .codex/skills/. 4. Utwórz .codex/agents/ dla ważnych agentów Claude. - Agenci Claude to pliki .md w .claude/agents/. - Agenci Codeksa to pliki .toml w .codex/agents/. - Przełóż instrukcje agenta na developer_instructions. 5. Zaktualizuj .gitignore, jeśli trzeba. - Trzymaj lokalne overrides i sekrety poza gitem. Zanim zaczniesz edytować, pokaż mi pliki, które planujesz utworzyć lub zmienić.

Cała idea konwersji: nie przebudowuj projektu — dodaj warstwę Codeksa obok warstwy Claude.

Jak to utrzymać w czasie

Konfiguracja działa tylko wtedy, gdy oba narzędzia pozostają zsynchronizowane. To nawyki, które się liczą.

• Gdy aktualizujesz instrukcje projektu — trzymaj CLAUDE.md i AGENTS.md zgodne. Nie utrzymuj dwóch pełnych kopii. Wybierz jeden plik jako źródło prawdy, a drugi zrób adapterem.
• Gdy tworzysz umiejętność Claude — skopiuj ją też do .agents/skills/, jeśli Codex ma jej używać.
• Gdy tworzysz agenta Claude — utwórz też odpowiadający mu .codex/agents/<nazwa>.toml, jeśli Codex ma go uruchamiać.
• Gdy dodajesz wspólną wiedzę — wkładaj ją do docs/, references/ lub templates/, żeby każde narzędzie czytało to samo źródło.

---

Wzór jest jeden: pliki-adaptery cienkie, wiedza gruba i w jednym miejscu. Jeśli kiedyś dojdzie trzeci agent kodujący, dokładasz mu kolejny zestaw plików-adapterów wskazujących na te same docs/, references/ i templates/ — i nic poza tym nie ruszasz.