Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

AGENTS.md: Configurezd a tároló utasításait

15. lecke 20 közül Frissítve 2026. november 3. Fejlesztő
Ezen az oldalon
  1. A Codex konfigurációs fájljának elsajátítása
  2. Az AGENTS.md hierarchia
  3. A fájlt alkotó szakaszok
  4. Két minta, amely megelőzi a meglepetéseket
  5. A fájl életben tartása
  6. Főbb megállapítások

Lecke frissítve: 2026. november 3. a Egyéni utasítások az AGENTS.md fájllal oldal alapján: A Codex csak azokat az AGENTS.md fájlokat olvassa be, amelyek a projekt gyökérkönyvtára és az aktuális munkakönyvtár között helyezkednek el (plusz a globális fájlt a ~/.codex útvonalon). Egy alkönyvtárban lévő fájl, amely ezen az útvonalon kívül esik, nem töltődik be, ellentétben azzal, amit a korábbi verzió sugallt. Forrás: AGENTS.md.

A Codex konfigurációs fájljának elsajátítása

A 3. leckében már találkoztál az AGENTS.md fájllal. Itt most mélyebbre ásunk a haladó mintákban: mi a különbség egy dekoratív fájl (három sor, amit induláskor írsz, majd elfelejtesz) és egy olyan között, amely ténylegesen irányítja az ügynök viselkedését egy éles projekten.

Az AGENTS.md hierarchia

A Codex hierarchikusan olvassa ezeket a fájlokat, az általánostól a specifikus felé haladva: először a globális fájlt a Codex mappádban (~/.codex/AGENTS.md, vagy AGENTS.override.md, ha létezik), majd a projekt gyökérkönyvtárától indulva azokat a fájlokat, amelyek az aktuális munkakönyvtárig vezető útvonalon lévő könyvtárakban találhatók. Egy jól strukturált projektnél a fa így néz ki:

mon-projet/
  AGENTS.md                    → Globális szabályok (alacsony prioritás)
  src/
    AGENTS.md                  → Szabályok minden forráskódhoz
    api/
      AGENTS.md                → Szabályok kifejezetten az API-khoz
      routes/
        AGENTS.md              → Szabályok az útvonalakhoz
    components/
      AGENTS.md                → Szabályok a React komponensekhez
  tests/
    AGENTS.md                  → Szabályok a tesztekhez

A szabályok felhalmozódnak: a Codex összefűzi a fájlokat a gyökérkönyvtártól az aktuális könyvtárig, és a legközelebbiek, amelyeket utoljára olvas be, felülírják az általános utasításokat. Egy pontot könnyű félreérteni: csak a gyökér és az aktuális könyvtár közötti útvonalon lévő könyvtárakat olvassa be. Ha a gyökérfájlod tiltja az any használatát, míg a tests/AGENTS.md lazább állításokat enged meg a mock-okban, ez a tolerancia csak akkor érvényes, ha a Codex a tests/ könyvtárból vagy annak valamelyik alkönyvtárából dolgozik; ha a gyökérből indítod, nem olvassa be a tests/AGENTS.md fájlt. Azoknak a szabályoknak, amelyeknek mindenhol érvényesülniük kell, a gyökérkönyvtárban kell lenniük, még akkor is, ha ott kell megnevezned a kivételt. A GitHub kódreview másképp működik: a Codex itt az egész tárolót átkutatja AGENTS.md fájlok után, és a kérdéses kódhoz legközelebb lévő fájlból alkalmazza a review szabályokat (## Code Review Rules). Az összefűzés alapértelmezetten 32 KiB-nál (project_doc_max_bytes) megáll: egy túl hosszú fájl csonkolásra kerül.

A fájlt alkotó szakaszok

Először a kontextus jön, mert ez formálja meg minden ezt követő döntést. Egy GDPR-nek (általános adatvédelmi rendelet) alávetett SaaS alkalmazást nem ugyanúgy kódolsz, mint egy öt fős belső eszközt:

## 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.

Mivel tudja, hogy GDPR hatálya alá eső adatokat kezel, a Codex hozzáadja a várt védelmi intézkedéseket anélkül, hogy minden egyes kérésedben külön meg kellene adnod őket. Ezután jönnek a konvenciók, amelyek egyetlen kérdésre válaszolnak: hogyan néz ki itt a helyes 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)

A parancsok szakaszt hagyják ki leggyakrabban, és ennek hiánya costly: ezek nélkül a parancsok nélkül a Codex nem tudja ellenőrizni a saját munkáját, és olyan kódot ad vissza, amelyet sosem futtatott le vagy tesztelt.

## 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

A szigorú szabályok alkotják a védőkorlátot. „SOHA“ és „MINDIG“ megfogalmazással megelőzik azokat a hibákat, amelyek egy egész estét emésztenek fel: egy törölt Prisma migrációt, amit productionből kell újraépítened, egy commitolt titkot, amit vissza kell vonnod, vagy egy innerHTML elemet, amely beszivárog egy komponensbe és XSS sebezhetőséget nyit.

## 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

Végül az architektúra írja le a rétegek közötti megengedett adatforgalmat. Enélkül a Codex olyan kódot gyárt, amely működik, de rövidre zárja a struktúrádat – például egy útvonal, amely közvetlenül kérdezi le a Prismát, mert ez volt a legrövidebb út.

## 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.

Ehhez jönnek hozzá projektről projektre a használt technológiákra vonatkozó specifikus utasítások:

## 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

Két minta, amely megelőzi a meglepetéseket

A várt környezeti változók deklarálása megakadályozza, hogy a Codex kulcsneveket találjon ki egy szkript írása közben, vagy véletlenül naplózzon egy érzékeny értéket egy hibakeresési nyomkövetésben:

## 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)

A preferált könyvtárak, és különösen az elutasítottak megnevezése megold egy visszatérő bosszúságot: az ügynök telepít egy függőséget, amely önmagában teljesen érvényes, de amelyet a csapatod két éve elvetett egy rossz tapasztalat után.

## 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)

A fájl életben tartása

Az AGENTS.md a kódoddal együtt fejlődik, akárcsak egy teszt vagy egy README. Frissítsd, amint új konvenciót fogadsz el, könyvtárat vagy keretrendszert váltasz, és különösen akkor, amikor egy ismétlődő Codex-hibát azonosítasz: ez utóbbi eset mindig hiányzó utasítást jelez, nem pedig modellhibát. Érdemes figyelni egy negyedik, finomabb triggerre is – amikor egy új fejlesztő olyan kérdést tesz fel, amelyre az AGENTS.md-nek választ kellett volna adnia, akkor annak a válasznak a fájlban a helye.

Főbb megállapítások

  • Az AGENTS.md hierarchiája lehetővé teszi az egyre specifikusabb utasításokat
  • A parancsok kritikus fontosságúak ahhoz, hogy a Codex ellenőrizhesse a munkáját
  • A SOHA szabályok a legfontosabbak a hibák elkerülése érdekében
  • Dokumentáld a preferált függőségeket a rossz választások megelőzése érdekében
  • Kezeld az AGENTS.md fájlt élő kódként