Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

AGENTS.md: Nakonfigurujte pokyny pro svůj repozitář

Lekce 15 z 20 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Ovládnutí konfiguračního souboru Codex
  2. Hierarchie souboru AGENTS.md
  3. Sekce, které tvoří soubor
  4. Dva vzory, které předcházejí překvapením
  5. Udržování souboru v kondici
  6. Klíčové poznatky

Lekce aktualizována 3. listopadu 2026 na základě stránky Custom instructions with AGENTS.md: Codex čte pouze soubory AGENTS.md umí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.md umožň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.md jako živý kód