AGENTS.md: Nakonfigurujte pokyny pro svůj repozitář
Na této stránce
Lekce aktualizována 3. listopadu 2026 na základě stránky Custom instructions with AGENTS.md: Codex čte pouze soubory
AGENTS.mdumístěné mezi kořenem projektu a aktuálním pracovním adresářem (plus globální soubor v~/.codex). Soubor v podadresáři mimo tuto cestu se nenačte, což je v rozporu s tím, co naznačovala předchozí verze. Zdroj: AGENTS.md.
Ovládnutí konfiguračního souboru Codex
Soubor AGENTS.md jsi objevil v lekci 3. Zde se ponoříme do pokročilých vzorů – do rozdílu mezi ozdobným souborem (tři řádky napsané při startu a zapomenuté) a takovým, který skutečně řídí chování agenta na živém projektu.
Hierarchie souboru AGENTS.md
Codex čte tyto soubory hierarchicky, od obecného ke konkrétnímu: nejprve globální soubor ve složce Codex (~/.codex/AGENTS.md, nebo AGENTS.override.md, pokud existuje), poté od kořene projektu soubory v adresářích, kterými prochází až k aktuálnímu pracovnímu adresáři. Na strukturovaném projektu vypadá strom takto:
mon-projet/
AGENTS.md → Globální pravidla (nízká priorita)
src/
AGENTS.md → Pravidla pro celý zdrojový kód
api/
AGENTS.md → Pravidla specifická pro API
routes/
AGENTS.md → Pravidla pro routy
components/
AGENTS.md → Pravidla pro komponenty React
tests/
AGENTS.md → Pravidla pro testy
Pravidla se akumulují: Codex zřetězí soubory od kořene dolů k aktuálnímu adresáři a ty, které jsou tomuto adresáři nejblíže a jsou čteny jako poslední, přepisují obecné pokyny. Jeden bod se snadno špatně chápe: čtou se pouze adresáře na cestě mezi kořenem a aktuálním adresářem. Pokud tvůj kořenový soubor zakazuje any, zatímco tests/AGENTS.md povoluje volnější утверzení v mockech, tato tolerance platí pouze tehdy, když Codex pracuje z tests/ nebo některého z jeho podadresářů; pokud je spuštěn z kořene, soubor tests/AGENTS.md nečte. Kontrola kódu na GitHubu funguje jinak: Codex zde prohledává celý repozitář na výskyt souborů AGENTS.md a aplikuje pravidla kontroly (## Code Review Rules) ze souboru, který je nejblíže danému kódu. Zřetězování se ve výchozím nastavení zastaví na 32 KiB (project_doc_max_bytes): příliš dlouhý soubor bude zkrácen.
Sekce, které tvoří soubor
Kontext přichází jako první, protože tvaruje každé následující rozhodnutí. SaaS aplikace podléhající GDPR (Obecné nařízení o ochraně osobních údajů) se nekóduje stejně jako interní nástroj pro pět lidí:
## Context
SaaS invoice management application for French SMEs.
GDPR compliance mandatory. Data hosted in France (OVH).
Stack: Astro 6, React, Strict TypeScript, Prisma, PostgreSQL.
Authentication: Better Auth with server sessions.
Díky vědomí, že zpracovává data podléhající GDPR, přidá Codex očekávané ochrany, aniž bys je musel specifikovat v každém požadavku. Dále přicházejí konvence, které odpovídají na jednu otázku: jak zde vypadá správný kód?
## Conventions
- Strict TypeScript (no any, no implicit any)
- Functional React components only
- Naming: kebab-case files, PascalCase components,
camelCase variables
- Imports: @/ for path aliases
- Validation: Zod for all user inputs
- Errors: custom error classes in src/lib/errors.ts
- Logging: use src/lib/logger.ts (no console.log)
Sekce příkazů je nejčastěji vynechávána a její absence stojí hodně: bez těchto příkazů nemůže Codex ověřit svou vlastní práci a vrací kód, který nikdy nespustil ani netestoval.
## Commands
- `npm run dev` — Development server (port 4321)
- `npm run build` — Production build
- `npm run test` — Vitest tests
- `npm run test:e2e` — Playwright tests
- `npm run lint` — ESLint + Prettier
- `npm run db:migrate` — Prisma migrations
- `npm run db:seed` — Database seed
Přísná pravidla tvoří ochrannou bariéru. Formulována jako „NIKDY“ a „VŽDY“ zabraňují chybám, jejichž oprava stojí celý večer: smazaná migrace Prisma, kterou musíš重建ovat z produkce, commitnuté tajemství, které je třeba zneplatnit, nebo innerHTML proklouznutý do komponenty, který otevírá zranitelnost XSS.
## Strict Rules (NEVER break these)
- NEVER modify the Prisma schema without creating a migration
- NEVER store secrets in code (use .env)
- NEVER use innerHTML (XSS risk)
- NEVER delete an existing Prisma migration
- NEVER expose internal IDs in public URLs
- ALWAYS validate user inputs with Zod
- ALWAYS use Prisma transactions for multi-table operations
Architektura nakonec popisuje povolený tok mezi vrstvami. Bez ní Codex produkuje kód, který funguje, ale obchází tvou strukturu – například routa, která queryuje Prisma přímo, protože to byla nejkratší cesta.
## Architecture
Layers:
1. Routes (src/pages/) → receive requests
2. Services (src/services/) → business logic
3. Repositories (src/repositories/) → data access
Rule: Routes MUST NOT access Prisma directly.
Everything goes through a service, which goes through a repository.
K tomu se projekt od projektu přidávají pokyny specifické pro každou použitou technologii:
## React
- Prefer Server Components by default
- Client Components only when necessary (interactivity)
- No useEffect for data fetching (use Server Actions)
- Local state with useState, global state with Zustand
## Prisma
- Relations: always include required fields explicitly
- Pagination: use cursor-based, not offset-based
- Soft delete: use deletedAt instead of DELETE
Dva vzory, které předcházejí překvapením
Deklarace očekávaných proměnných prostředí zabraňuje tomu, aby Codex při psaní skriptu vymýšlel názvy klíčů nebo omylem logoval citlivou hodnotu v ladícím trace:
## Required Environment Variables
- DATABASE_URL — PostgreSQL connection URL
- AUTH_SECRET — Secret for Better Auth (min 32 chars)
- SMTP_HOST — SMTP server for emails
- STRIPE_SECRET_KEY — Stripe API key (never log)
Pojmenování preferovaných knihoven, a zejména těch, které odmítáš, řeší opakující se nepříjemnost: agent nainstaluje závislost, která je sama o sobě zcela platná, ale kterou tvůj tým před dvěma lety po špatné zkušenosti zavrtl.
## Dependencies
If you need:
- Validation → Zod (NOT Joi, NOT Yup)
- Dates → date-fns (NOT moment, NOT dayjs)
- HTTP client → ofetch (NOT axios)
- Tests → Vitest (NOT Jest)
- E2E → Playwright (NOT Cypress)
Udržování souboru v kondici
AGENTS.md se vyvíjí spolu s tvým kódem, stejně jako test nebo README. Aktualizuj jej, jakmile přijmeš novou konvenci, přepneš knihovny nebo frameworky, a zejména jakmile identifikuješ opakující se chybu Codexu: tento poslední případ vždy signalizuje chybějící pokyn, nikoli selhání modelu. Stojí za to sledovat čtvrtý, jemnější spouštěč – když se nový vývojář zeptá na něco, na co měl AGENTS.md odpovědět, tato odpověď patří do souboru.
Klíčové poznatky
- Hierarchie souboru
AGENTS.mdumožňuje stále specifičtější pokyny - Příkazy jsou kritické pro to, aby Codex ověřil svou práci
- Pravidla NIKDY jsou nejdůležitější pro vyhnutí se chybám
- Zdokumentuj preferované závislosti, abys předešel špatným volbám
- Udržuj
AGENTS.mdjako živý kód