Kurs/rozdział 0220 min

AGENTS.md — instrukcje projektowe

Plik, który sprawia, że agent zna reguły Twojego projektu bez tłumaczenia ich przy każdej rozmowie.

Do czego służy AGENTS.md

AGENTS.md to zwyczajowy plik instrukcji dla agentów AI (standard wspierany przez OpenCode, Codex i inne narzędzia). Wrzucasz do niego rzeczy, które agent powinien wiedzieć ZAWSZE, gdy pracuje w tym projekcie: komendy budowania i testów, architekturę, konwencje kodu, czego nie ruszać i jak weryfikować zmiany.

Plik trafia do kontekstu każdego promptu, zanim model cokolwiek odpisze. To nie jest „prompt, który sobie przypominasz” — to trwała konfiguracja projektu, którą committujesz do repozytorium, żeby cały zespół pracował z tymi samymi zasadami.

AGENTS.md — minimalistyczny przykład

# Instrukcje projektu

- Po zmianach w TypeScript uruchom `bun typecheck`.
- Zapytania do bazy trzymamy wyłącznie w `src/database`.
- Nie edytuj plików w `src/generated/` — są generowane przez codegen.
- Testy jednostkowe: `bun test`; integracyjne: `bun test:integration`.

Gdzie go położyć — zakres pliku

AGENTS.md działa globalnie i na poziomie katalogu. OpenCode wczytuje plik globalny, a potem pliki AGENTS.md od bieżącego katalogu w górę aż do domu użytkownika (dla workspace'ów poza domem — do korzenia projektu).

Lokalizacja	Kiedy stosować
~/.config/opencode/AGENTS.md	Osobiste preferacje niezależne od projektu (np. „odpowiadaj zwięźle po polsku”)
korzeń repozytorium	Reguły wspólne dla całego projektu — komendy, architektura, konwencje
podkatalog (np. packages/web)	Wskazówki specyficzne dla modułu/pakietu

Przykładowe drzewo — wszystkie cztery pliki zostaną wczytane

~/.config/opencode/AGENTS.md      ← globalne wskazówki (Twój styl pracy)
~/code/my-project/AGENTS.md        ← reguły całego repo
~/code/my-project/packages/AGENTS.md
~/code/my-project/packages/web/AGENTS.md  ← aktualny katalog

⚠

Uwaga

OpenCode V2 rozpoznaje WYŁĄCZNIE AGENTS.md. Plik CLAUDE.md nie jest wczytywany jako zamiennik — przenieś jego treść do AGENTS.md.

Kolejność i łączenie plików

Wiele plików AGENTS.md NIE nadpisuje się nawzajem — OpenCode je łączy (konkatenacja). Kolejność złożenia wygląda tak: najpierw plik globalny, potem od najgłębszego katalogu ku górze: web → packages → root.

Ponieważ OpenCode nie rozstrzyga konfliktów między plikami, pisz krótko i bez sprzeczności: to, co wspólne, trzymaj wyżej; to, co specyficzne, blisko kodu.

Pliki zagnieżdżone poniżej workspace nie są ładowane „z góry” — odkrywają je dopiero, gdy agent zacznie czytać dany obszar (read/listing katalogu doładowuje lokalny AGENTS.md).
Po kompaktowaniu kontekstu lub resecie zagnieżdżone instrukcje mogą wczytać się ponownie przy następnym odczycie danego katalogu.
OPENCODE_DISABLE_PROJECT_CONFIG=1 pomija projektowe AGENTS.md, zostawiając globalny.

Co pisać, a czego nie

Dobre treści	Złe treści
Komendy: budowanie, testy, lint, typecheck	Długie tutoriale — to jest rola skilli i docsów
Mapa architektury: gdzie co mieszka	Powtarzanie README dla ludzi
Konwencje: nazewnictwo, struktura importów	Zmienne dane (liczby, listy tasków) — szybko się dezaktualizują
Zakazy: „nie rusaj generated/”, „migracje tylko przez CLI”	Ogólniki: „pisz dobry kod”
Jak zweryfikować zmianę przed zakończeniem	Sekrety i klucze API!

✦

Wskazówka

Test jakości: przeczytaj swój AGENTS.md i zapytaj „czy agent po jego lekturze uniknie błędu, który zrobił w zeszłym tygodniu?”. Jeśli nie — dopisz regułę. Trzymaj plik w ryzach (do ~100 linii); rozrastające się procedury wynoś do skilli.

Aktualizacja w trakcie sesji

Pliki AGENTS.md (globalny i „ambientne”, tzn. znalezione podczas odkrywania projektu) można edytować bez restartu sesji. Przed następnym promptem OpenCode wykryje zmianę i dołoży aktualizację instrukcji.

Usunięcie wszystkich ambientnych AGENTS.md sygnalizuje sesji, że stare instrukcje już nie obowiązują.
Przeniesienie sesji (session_move) zachowuje stan instrukcji — wskazówki z katalogu docelowego doładują się jako aktualizacja.
Zmodyfikowanych plików zagnieżdżonych (odkrytych później) nie trzeba restartować sesji — ale gdy zmiana ma wejść natychmiast, nowa sesja jest najpewniejsza.

Dopisanie reguły w locie

printf '\n- Przed commitem uruchom pełny zestaw testów integracyjnych.\n' >> AGENTS.md
# następny prompt agenta pojedzie już z nową regułą

AGENTS.md a pole instructions

Schema konfiguracji V2 przyjmuje tablicę instructions, ale V2 aktualnie NIE wczytuje jej wpisów do modelu. Aktywnym mechanizmem instrukcji jest AGENTS.md.

To jest przyjmowane, ale NIE działa jeszcze w V2

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines/*.md"]
}

⚠

Uwaga

Nie przenoś instrukcji do pola instructions kosztem AGENTS.md — dziś pozostałyby martwe. Śledź changelog OpenCode, gdyby to się zmieniło.

Kompletny przykład dla monorepo

AGENTS.md w korzeniu monorepo — szablon do skopiowania

# Webshop — instrukcje dla agenta

## Stack
Bun + TypeScript + Astro (frontend), Fastify (API), Postgres.
Pakiety: `apps/web`, `apps/api`, `packages/db` (drizzle).

## Komendy
- `bun install` — zależności (zawsze bun, NIE npm)
- `bun run dev` / `bun run build` / `bun test`
- `bun run db:migrate` — migracje; NIE edytuj katalogu migracji ręcznie
- `bun run lint` + `bun run typecheck` — wymagane przed zakończeniem zadania

## Zasady
- Współdzielone typy tylko w `packages/db`; nie dubluj interfejsów w apps.
- Każdy endpoint API musi mieć test w `apps/api/test/`.
- Pliki `*.generated.ts` są generowane — zmień źródło schema i uruchom codegen.
- COMMIT: conventional commits (feat:, fix:, chore:...).

Podsumowanie rozdziału

AGENTS.md = trwałe instrukcje projektu doładowywane do każdego promptu.
Warstwy: globalny (~/.config/opencode) → root repo → zagnieżdżone; pliki łączą się, nie nadpisują.
Pisz komendy, architekturę, konwencje i zakazy; procedury wynoś do skilli.
Edycja w trakcie sesji działa; CLAUDE.md nie jest wspierany w V2.