Jak napisać plik AGENTS.md dla agentów programistycznych
Napisz krótki AGENTS.md z poleceniami instalacji i testów, regułami i granicami, spraw, by Claude Code i Gemini CLI go wczytywały, i sprawdź go na małym zadaniu.
Plik AGENTS.md to zwykły plik Markdown w katalogu głównym repozytorium, który mówi agentom programistycznym, jak pracować nad projektem: jakie polecenia uruchamiać, gdzie jest kod i czego nie ruszać. Nie ma obowiązkowych sekcji. Pisz go zwięźle, formułuj każdą regułę tak, żeby dało się ją sprawdzić, i upewnij się, że każdy agent go wczytuje.
Ten poradnik opisuje, co umieścić w pliku, podaje szablon, wyjaśnia, jak Claude Code i Gemini CLI znajdują plik, i pokazuje szybki test. Te same kroki obowiązują, gdy uruchamiasz agentów z telefonu przez Mono firmy Reunified.
1. Zdecyduj, co powinno trafić do pliku
Strona agents.md nazywa go README dla agentów. Umieść w nim fakty potrzebne w każdej sesji i pomiń wszystko, czego agent może się dowiedzieć z kodu.
| Umieść w AGENTS.md | Pomiń |
|---|---|
| Polecenia instalacji, testów i lintowania | Hasła, klucze API i tokeny |
| Miejsce, w którym jest główny kod | Pełne drzewo plików lub listę zależności |
| Konwencje, które różnią się od domyślnych | Długie procedury (zamiast nich podaj link do dokumentu) |
| Pliki, których nigdy nie wolno edytować, i działania, o które trzeba najpierw zapytać | Osobiste preferencje (użyj pliku agenta na poziomie użytkownika) |
W monorepo możesz dodać AGENTS.md w każdym pakiecie. Pierwszeństwo ma najbliższy plik, a bezpośrednie polecenie w czacie jest ważniejsze od niego.
2. Zacznij od krótkiego szablonu
Oto fikcyjny przykład dla „tidy-recipes”, aplikacji webowej napisanej w TypeScripcie, która korzysta z pnpm:
# AGENTS.md
## Overview
TypeScript web app for saving recipes. Components live in src/components.
## Setup
- `pnpm install`
## Test and lint
- `pnpm test` and `pnpm lint`
## Code style
- TypeScript only. One component per file.
## Boundaries
- Never edit db/migrations/.
- Ask before adding a dependency.
## Before you finish
- Run `pnpm test` and `pnpm lint`.
- List the files you changed and the test results.Wpisuj tylko polecenia, które uruchomiłeś w tym repozytorium. Agent zaufa także błędnemu.
3. Pisz reguły, które agent może sprawdzić
Dobra reguła pozwala potem sprawdzić, czy agent jej przestrzegał.
| Ogólnikowo | Konkretnie |
|---|---|
| Testuj swoje zmiany | Przed zakończeniem uruchom pnpm test i pnpm lint |
| Utrzymuj porządek w plikach | Komponenty trafiają do src/components |
| Uważaj na bazę danych | Nigdy nie edytuj db/migrations/ |
| Podsumuj swoją pracę | Wymień zmienione pliki i wyniki testów |
Granice zapisuj jako reguły „nigdy” i „najpierw zapytaj”, po jednej w wierszu.
4. Spraw, żeby Claude Code i Gemini CLI go czytały
Strona agents.md wymienia Codex, Gemini CLI, opencode i innych agentów obsługujących ten format, ale część z nich wymaga najpierw zmiany ustawień.
Domyślnie nowsze wersje Claude Code czytają AGENTS.md tylko wtedy, gdy w katalogu roboczym ani wyżej nie ma CLAUDE.md, .claude/CLAUDE.md ani CLAUDE.local.md (zobacz dokumentację pamięci). Jeśli masz jeden z tych plików albo starszą wersję, zaimportuj AGENTS.md z CLAUDE.md. Projekt tidy-recipes ma stary CLAUDE.md, więc dodaj na jego początku ten wiersz, a notatki przeznaczone tylko dla Claude zostaw poniżej:
@AGENTS.md
Prefer small commits.Uruchom nową sesję, wykonaj /context i sprawdź, czy CLAUDE.md pojawia się w sekcji Memory files. Bez CLAUDE.md polecenie /memory pokazuje zamiast tego ścieżkę do AGENTS.md.
Gemini CLI domyślnie czyta GEMINI.md. Aby dodać AGENTS.md, dodaj ten fragment do pliku .gemini/settings.json w projekcie (zobacz dokumentację GEMINI.md):
{
"context": {
"fileName": ["AGENTS.md", "GEMINI.md"]
}
}Uruchom nową sesję, a potem wykonaj /memory show, żeby zobaczyć, co zostało wczytane. W przypadku innych agentów sprawdź ich dokumentację.
5. Przetestuj plik na małym zadaniu
W nowej sesji daj agentowi takie zadanie:
Najpierw wymień reguły projektu, które wczytałeś, i plik, z którego pochodzi każda z nich. Potem zmień tekst przycisku „Save recipe” na „Save” w src/components/SaveButton.tsx. Nie zmieniaj niczego więcej.
Porównaj wynik z plikiem:
- Agent wymienił AGENTS.md (lub CLAUDE.md z importem).
- Uruchomił
pnpm testipnpm linti podał wyniki. - Nie ruszał db/migrations/ i nie dodał żadnej zależności.
- Wymienił zmienione pliki.
Sam potwierdź zmianę poleceniem git diff (zobacz przegląd zmian w kodzie od AI). Jeśli agent nie potrafi wymienić reguły, plik prawdopodobnie się nie wczytał, więc wróć do kroku 4. Jeśli wymienił regułę, ale jej nie zastosował, sformułuj ją konkretniej.
6. Dbaj, żeby plik był krótki i aktualny
Dokumentacja Claude Code radzi, żeby CLAUDE.md miał mniej niż 200 wierszy, bo dłuższe pliki zajmują więcej kontekstu i agent trzyma się ich mniej konsekwentnie. Tego samego trzymaj się przy AGENTS.md. Poradnik o oknie kontekstu opisuje, co się dzieje, gdy kontekst się zapełni.
Aktualizuj plik, gdy agent powtarza błąd, i usuwaj z niego nieaktualne polecenia oraz sprzeczne reguły. Dodaj go do repozytorium i przeglądaj jego zmiany tak jak zmiany w kodzie.
Plik wskazuje agentowi kierunek, ale niczego nie wymusza. Aby zablokować jakieś działanie, użyj ustawień uprawnień agenta albo odrzuć jego prośbę (zobacz poradnik o uprawnieniach narzędzi).
W Mono agent startuje w katalogu roboczym projektu na Twoim komputerze i tam szuka tych plików. AGENTS.md, CLAUDE.md lub .gemini/settings.json możesz otworzyć w edytorze Mono, także z telefonu, a zmiany zapisują się same. Aby utworzyć plik, poproś o to agenta albo otwórz terminal z karty projektu. Mono nie sprawdza pliku i nie zmienia tego, który plik wczytuje agent. Mono nie jest jeszcze dostępny, ale możesz dołączyć do listy oczekujących.
