Opanowanie AGENTS.md i umiejętności

Twoje sesje Codex ciągle zbaczają z kursu. Agent używa console.log zamiast twojego ustrukturyzowanego loggera. Pisze testy z Jest, podczas gdy twój projekt używa Vitest. Ignoruje twoje wzorce obsługi błędów. Przy każdym prompcie od nowa wyjaśniasz te same ograniczenia. Dokładnie ten problem rozwiązują AGENTS.md i umiejętności — ale tylko wtedy, gdy mają odpowiednią strukturę. Źle napisany AGENTS.md marnuje tokeny kontekstu na wskazówki, które agent ignoruje, podczas gdy dobrze ustrukturyzowany sprawia, że każda sesja zaczyna się z właściwymi ograniczeniami.

Co wyniesiesz z tego artykułu

• Hierarchię AGENTS.md, która skaluje się od osobistych preferencji do konwencji całego zespołu
• Wzorzec nadpisywania dla tymczasowych faz projektu
• Wzorce tworzenia i organizacji umiejętności
• Zarządzanie budżetem kontekstu, aby twoje wskazówki nie wypierały przestrzeni konwersacji
• Techniki debugowania, gdy instrukcje wydają się być ignorowane

Jak działa wykrywanie AGENTS.md

Codex buduje swój łańcuch instrukcji na początku sesji, skanując pliki w następującej kolejności:

1. Zakres globalny: ~/.codex/AGENTS.override.md (jeśli istnieje), w przeciwnym razie ~/.codex/AGENTS.md
2. Zakres projektu: Zaczynając od korzenia projektu (korzeń Git), przechodząc w dół do twojego bieżącego katalogu roboczego. Na każdym poziomie Codex sprawdza AGENTS.override.md, potem AGENTS.md, a następnie nazwy zapasowe
3. Kolejność łączenia: Pliki są konkatenowane od korzenia do liścia. Późniejsze pliki nadpisują wcześniejsze, ponieważ pojawiają się jako ostatnie w połączonym prompcie

Codex dołącza co najwyżej jeden plik na katalog i zatrzymuje się, gdy łączny rozmiar przekroczy project_doc_max_bytes (domyślnie 32 KB).

Wzorzec trzech warstw

Warstwa 1: Preferencje globalne

~/.codex/AGENTS.md

## Umowy robocze
- Zawsze uruchamiaj testy po modyfikacji plików źródłowych
- Preferuj pnpm przy instalacji zależności
- Pytaj przed dodaniem nowych zależności produkcyjnych
- Używaj trybu strict TypeScript dla wszystkich nowych plików

Utrzymuj to poniżej 20 linii. To uniwersalne preferencje, które dotyczą każdego repozytorium, w którym pracujesz.

Warstwa 2: Konwencje projektu

repo-root/AGENTS.md

## Reguły repozytorium
- Używaj Vitest do wszystkich testów (nie Jest)
- Stosuj wzorce obsługi błędów z src/lib/errors.ts
- Uruchamiaj pnpm lint && pnpm test przed commitem
- Nowe endpointy API potrzebują adnotacji OpenAPI
- Zmiany w bazie danych wymagają pliku migracji w migrations/

Utrzymuj to poniżej 50 linii. Skup się na konwencjach specyficznych dla projektu, które różnią się od twoich globalnych domyślnych ustawień.

Warstwa 3: Reguły specyficzne dla modułu

services/payments/AGENTS.md

## Reguły serwisu płatności
- Używaj scentralizowanego handlera błędów, nigdy nie rzucaj surowych błędów
- Rate limiting musi być dodany do wszystkich publicznych endpointów
- Middleware uwierzytelniania znajduje się w src/middleware/auth.ts
- Narzędzia testowe znajdują się w tests/utils/api-helpers.ts
- Nigdy nie rotuj kluczy API bez powiadomienia kanału bezpieczeństwa

Utrzymuj to poniżej 30 linii. Umieszczaj tylko reguły, które dotyczą konkretnie tego modułu.

Prompt: Wygeneruj AGENTS.md z twojej bazy kodu

“Analyze this repository’s structure, coding patterns, and existing documentation. Generate an AGENTS.md that captures: the testing framework and how to run tests, the linting setup, error handling patterns, naming conventions, and any project-specific rules I should enforce. Keep it under 40 lines.”

Wzorzec nadpisywania

Użyj AGENTS.override.md dla tymczasowych wskazówek, które nie powinny na stałe rezydować w twoim repozytorium:

services/api/AGENTS.override.md

# TYMCZASOWE: Usuń po zakończeniu migracji v3 (cel: marzec 2026)

- Wszystkie nowe endpointy muszą używać routera v3 w src/routes/v3/
- NIE modyfikuj żadnych tras v1 ani v2
- Dokument śledzenia migracji: docs/v3-migration.md
- Używaj nowego AuthContext z src/lib/auth-v3.ts dla całego nowego middleware

Gdy plik nadpisania istnieje, Codex używa go zamiast zwykłego AGENTS.md na danym poziomie katalogowym. Usuń plik nadpisania, aby przywrócić stałe wskazówki.

Ten wzorzec jest nieoceniony podczas:

• Dużych migracji, gdzie obowiązują tymczasowe reguły
• Wdrażania flag funkcji zmieniających wzorce kodowania
• Obszarów skupienia specyficznych dla sprintu

Zarządzanie budżetem kontekstu

Monitoruj swój budżet

Każdy token wydany na AGENTS.md to token niedostępny dla konwersacji. Sprawdź swoją alokację:

/status

To pokazuje pozostały kontekst, załadowane pliki AGENTS.md i aktywne serwery MCP.

Zmniejsz narzut tokenów AGENTS.md

Technika	Wpływ
Usuń zbędne wskazówki (rzeczy, które model już wie)	Wysoki
Podziel na zagnieżdżone pliki, aby ładowały się tylko odpowiednie warstwy	Średni
Usuń przykłady i zostaw tylko reguły	Średni
Ogranicz nazwy zapasowe, aby uniknąć ładowania dodatkowych plików	Niski

Wyłącz nieużywane serwery MCP

Każdy serwer MCP dodaje schematy narzędzi do kontekstu. Wyłącz te, których nie używasz:

[mcp_servers.unused-server]
enabled = false

Zwiększ limit bajtów

Jeśli twoje wskazówki są rzeczywiście potrzebne i ciągle są obcinane:

project_doc_max_bytes = 65536  # 64 KB (domyślnie: 32 KB)

Ale to ostateczność. Najpierw spróbuj podzielić na zagnieżdżone pliki.

Prompt: Audyt budżetu kontekstu

“Run /status and tell me: how much context window is remaining, what AGENTS.md files are loaded, and how many MCP servers are active. Suggest which MCP servers I should disable for the current task, and whether my AGENTS.md files could be more concise.”

Pisanie skutecznych umiejętności

Struktura umiejętności

Umiejętność to katalog z plikiem SKILL.md:

my-skill/
  SKILL.md          # Wymagany: instrukcje + metadane
  scripts/          # Opcjonalny: kod wykonywalny
  references/       # Opcjonalny: dokumentacja
  assets/           # Opcjonalny: szablony, zasoby
  agents/
    openai.yaml     # Opcjonalny: wygląd UI, zależności MCP

Format SKILL.md

---
name: pr-ready
description: Prepare the current changes for a pull request by running
  all checks, fixing issues, and generating a PR description.
---

# PR Readiness Check

1. Run pnpm lint and fix any issues automatically
2. Run pnpm test and fix any failures
3. Run pnpm type-check and fix any type errors
4. Generate a PR description with:
   - Summary of changes (what and why)
   - Testing approach
   - Breaking changes (if any)
5. Report the results with a pass/fail summary

Wywoływanie umiejętności

Umiejętności można uruchamiać na dwa sposoby:

• Jawne: Wpisz $pr-ready lub użyj /skills w CLI/App
• Niejawne: Codex automatycznie dopasowuje twój prompt do opisu umiejętności

Pisz opisy z wyraźnymi granicami zakresu, aby niejawne dopasowywanie działało niezawodnie.

Gdzie zapisywać umiejętności

Zakres	Lokalizacja	Zastosowanie
Repozytorium	.agents/skills/ (dowolny katalog do korzenia repo)	Umiejętności współdzielone z zespołem
Użytkownik	~/.agents/skills/	Osobiste umiejętności dla wszystkich repozytoriów
Administrator	/etc/codex/skills/	Umiejętności organizacyjne
System	Dołączone z Codex	Wbudowane umiejętności jak $skill-creator

Szybkie tworzenie umiejętności

Użyj wbudowanego kreatora umiejętności:

$skill-creator

Opisz, co umiejętność powinna robić, a Codex wygeneruje SKILL.md z odpowiednimi metadanymi i instrukcjami.

Instalacja umiejętności społeczności

$skill-installer install the linear skill from the .experimental folder

Lub zainstaluj z marketplace umiejętności za pomocą uniwersalnego CLI:

npx skills add openai/skills

Włączanie/wyłączanie umiejętności

~/.codex/config.toml

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

Nazwy zapasowe

Jeśli twój zespół już używa innej nazwy pliku dla instrukcji projektu:

~/.codex/config.toml

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md", "CODEX.md"]

Codex sprawdza każdy katalog w tej kolejności: AGENTS.override.md, AGENTS.md, a następnie każdą nazwę zapasową. Pozwala to wdrożyć Codex bez zmiany nazw istniejącej dokumentacji.

Debugowanie problemów ze wskazówkami

Zweryfikuj, co się załadowało

codex --ask-for-approval never "Summarize the current instructions and list all instruction files you loaded."

Codex wypisze wskazówki w kolejności priorytetów.

Sprawdź pliki nadpisania

AGENTS.override.md wyżej w drzewie katalogów może cicho zastąpić zwykły AGENTS.md. Wyszukaj nadpisania:

find . -name "AGENTS.override.md" -type f

Zweryfikuj wykrywanie korzenia projektu

Codex domyślnie używa .git jako znacznika korzenia projektu. Jeśli twoja przestrzeń robocza ma nietypową strukturę:

project_root_markers = [".git", ".hg", ".sl"]

Lub wyłącz skanowanie katalogów nadrzędnych całkowicie:

project_root_markers = []

Prompt: Walidacja konfiguracji AGENTS.md

“Check my AGENTS.md configuration: list all AGENTS.md and AGENTS.override.md files in this repository, show their sizes, verify they are within the project_doc_max_bytes limit, and identify any redundant or contradictory instructions between layers.”

Gdy coś się psuje

• Agent ignoruje instrukcje: Wskazówki mogły zostać skompaktowane podczas długiej sesji. Powtórz krytyczne ograniczenia w swoim bieżącym prompcie lub rozpocznij nowy wątek.
• AGENTS.md się nie ładuje: Sprawdź, czy plik nie jest pusty. Upewnij się, że project_doc_max_bytes nie został przekroczony. Uruchom powyższy prompt weryfikacyjny.
• Plik nadpisania powoduje zamieszanie: Poszukaj plików AGENTS.override.md, o których mogłeś zapomnieć. Usuń tymczasowe nadpisania, gdy ich cel zostanie zrealizowany.
• Umiejętności się nie pojawiają: Umiejętności muszą znajdować się w katalogach .agents/skills/. Codex skanuje od bieżącego katalogu w górę do korzenia repozytorium. Uruchom ponownie Codex, jeśli nowo dodana umiejętność się nie pojawia.
• Zadania w chmurze ignorują konwencje: Środowiska chmurowe używają AGENTS.md zacommitowanego do repozytorium, a nie twoich lokalnych plików. Upewnij się, że krytyczne wskazówki są zacommitowane.

Co dalej

• Zaawansowane techniki — Połącz AGENTS.md z profilami i automatyzacjami
• Współpraca zespołowa — Skaluj AGENTS.md w swoim zespole inżynieryjnym
• Instalacja i konfiguracja — Ustawienia konfiguracji uzupełniające AGENTS.md