Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

AGENTS.md: Konfigurácia pokynov pre vaše úložisko

Lekcia 15 z 20 Aktualizované 3. novembra 2026 Vývojár
Na tejto strane
  1. Ovládnite konfiguračný súbor Codex
  2. Hierarchia súboru AGENTS.md
  3. Sekcie, ktoré tvoria súbor
  4. Dva vzorce, ktoré predchádzajú prekvapeniam
  5. Udržiavanie súboru v živote
  6. Kľúčové poznatky

Lekcia aktualizovaná 3. novembra 2026 na základe stránky Vlastné pokyny s AGENTS.md: Codex číta iba súbory AGENTS.md umiestnené 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.md umožň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.md ako živý kód