AGENTS.md: Konfigurácia pokynov pre vaše úložisko
Na tejto strane
Lekcia aktualizovaná 3. novembra 2026 na základe stránky Vlastné pokyny s AGENTS.md: Codex číta iba súbory
AGENTS.mdumiestnené medzi koreňom projektu a aktuálnym pracovným adresárom (plus globálny súbor v~/.codex). Súbor v podadresári mimo tejto cesty sa nenačíta, čo je v rozpore s tým, čo naznačovala predchádzajúca verzia. Zdroj: AGENTS.md.
Ovládnite konfiguračný súbor Codex
Súbor AGENTS.md si objavil v lekcii 3. Tu sa ponoríme do pokročilých vzorcov – rozdielu medzi dekoratívnym súborom (tri riadky napísané pri štarte a zabudnuté) a takým, ktorý skutočne riadi správanie agenta na živom projekte.
Hierarchia súboru AGENTS.md
Codex číta tieto súbory hierarchicky, od všeobecných po špecifické: najprv globálny súbor v priečinku Codex (~/.codex/AGENTS.md, alebo AGENTS.override.md, ak existuje), potom, počnúc koreňom projektu, súbory v adresároch, ktorými prechádza až do aktuálneho pracovného adresára. Na štruktúrovanom projekte strom vyzerá takto:
mon-projet/
AGENTS.md → Globálne pravidlá (nízka priorita)
src/
AGENTS.md → Pravidlá pre celý zdrojový kód
api/
AGENTS.md → Pravidlá špecifické pre API
routes/
AGENTS.md → Pravidlá pre routy
components/
AGENTS.md → Pravidlá pre React komponenty
tests/
AGENTS.md → Pravidlá pre testy
Pravidlá sa akumulujú: Codex zreťazí súbory od koreňa nadol do aktuálneho adresára, pričom tie najbližšie k tomuto adresáru, čítané ako posledné, prepíšu všeobecné pokyny. Jeden bod sa ľahko nepochopí: čítajú sa iba adresáre na ceste medzi koreňom a aktuálnym adresárom. Ak váš koreňový súbor zakazuje any, zatiaľ čo tests/AGENTS.md povoľuje voľnejšie tvrdenia v mockoch, táto tolerancia platí len vtedy, keď Codex pracuje z tests/ alebo niektorého z jeho podadresárov; ak je spustený z koreňa, tests/AGENTS.md nečíta. Kontrola kódu na GitHubu funguje inak: Codex tam prehľadáva celé úložisko pre súbory AGENTS.md a aplikuje pravidlá kontroly (## Code Review Rules) zo súboru najbližšieho k danému kódu. Zreťazenie sa štandardne zastaví na 32 KiB (project_doc_max_bytes): príliš dlhý súbor sa oreže.
Sekcie, ktoré tvoria súbor
Kontext je na prvom mieste, pretože formuje každé nasledujúce rozhodnutie. SaaS aplikácia podliehajúca GDPR (Všeobecné nariadenie o ochrane údajov) sa nekóduje rovnako ako interný nástroj pre päť ľudí:
## 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.
Keďže vie, že pracuje s údajmi podliehajúcimi GDPR, Codex pridá očakávané ochrany bez toho, aby ste ich museli špecifikovať v každej požiadavke. Ďalej prichádzajú konvencie, ktoré odpovedajú na jednu otázku: ako tu vyzerá správny 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)
Sekcia príkazov sa najčastejšie vynecháva a jej absencia stojí veľa: bez týchto príkazov nemôže Codex overiť svoju vlastnú prácu a vráti kód, ktorý 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
Prísne pravidlá tvoria ochrannú bariéru. Formulované ako „NIKDY“ a „VŽDY“ zabraňujú chybám, ktorých oprava stojí celý večer: vymazaná migrácia Prisma, ktorú budete musieť obnoviť z produkcie, commitnuté tajomstvo, ktoré treba zrušiť, alebo innerHTML prepašovaný do komponentu, ktorý otvára zraniteľnosť 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
Nakoniec, architektúra opisuje povolený tok medzi vrstvami. Bez nej Codex produkuje kód, ktorý funguje, ale obchádza vašu štruktúru – napríklad routa, ktorá sa pýta priamo na Prisma, pretože to bola najkratšia 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 sa projekt od projektu pridávajú pokyny špecifické pre každú použitú technológiu:
## 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 vzorce, ktoré predchádzajú prekvapeniam
Deklarácia očakávaných premenných prostredia zabraňuje tomu, aby Codex vymýšľal názvy kľúčov pri písaní skriptu alebo omylom zapísal citlivú hodnotu do ladiaceho záznamu:
## 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)
Pomenovanie vašich preferovaných knižníc, a najmä tých, ktoré odmietate, rieši opakujúci sa problém: agent nainštaluje závislosť, ktorá je sama o sebe úplne platná, ale ktorú váš tím pred dvoma rokmi zamietol po zlej skúsenosti.
## 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žiavanie súboru v živote
AGENTS.md sa vyvíja spolu s vaším kódom, rovnako ako test alebo README. Aktualizujte ho hneď, ako prijmete novú konvenciu, zmeníte knižnice alebo frameworky, a najmä hneď, ako identifikujete opakujúcu sa chybu Codexu: tento posledný prípad vždy signalizuje chýbajúci pokyn, nie zlyhanie modelu. Stojí za to sledovať aj štvrtý, jemnejší spúšťač – keď sa nový vývojár opýta na otázku, na ktorú mal AGENTS.md odpovedať, táto odpoveď patrí do súboru.
Kľúčové poznatky
- Hierarchia súboru
AGENTS.mdumožňuje čoraz špecifickejšie pokyny - Príkazy sú kritické pre to, aby si Codex overil svoju prácu
- Pravidlá NIKDY sú najdôležitejšie pre vyhnutie sa chybám
- Zdokumentujte preferované závislosti, aby ste predišli zlým voľbám
- Udržiavajte
AGENTS.mdako živý kód