Lähe põhisisu juurde
Eesti— Vali keel
Menüü

AGENTS.md: konfigureeri oma hoidla juhised

Õppetund 15 / 20 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. Codexi konfiguratsioonifaili valdamine
  2. AGENTS.md hierarhia
  3. Jaotised, mis teevad failist toimiva
  4. Kaks mustrit, mis hoiavad ära üllatusi
  5. Faili elus hoidmine
  6. Peamised punktid

Tund uuendatud 3. novembril 2026 põhineb lehel Custom instructions with AGENTS.md: Codex loeb ainult faile AGENTS.md, mis asuvad projekti juurkausta ja praeguse töökataloogi vahel (pluss globaalne fail asukohas ~/.codex). Fail alamkataloogis, mis jääb sellest teest välja, ei laadita, vastupidiselt sellele, mida eelmine versioon vihjas. Allikas: AGENTS.md.

Codexi konfiguratsioonifaili valdamine

Sa tutvusid failiga AGENTS.md 3. tunnis. Siin süveneme täiustatud mustritesse – erinevusesse dekoratiivse faili (kolm rida, mis kirjutatakse käivitamisel ja unustatakse) ning sellise faili vahel, mis tegelikult suunab agendi käitumist elavas projektis.

AGENTS.md hierarhia

Codex loeb neid faile hierarhiliselt, üldisest spetsiifiliseni: esmalt globaalne fail sinu Codexi kaustas (~/.codex/AGENTS.md või AGENTS.override.md, kui see eksisteerib), seejärel alates projekti juurkaustast failid kataloogides, mida läbitakse kuni praeguse töökataloogini. Struktureeritud projekti puhul näeb puu välja selline:

mon-projet/
  AGENTS.md                    → Globaalsed reeglid (madal prioriteet)
  src/
    AGENTS.md                  → Reeglid kogu lähtekoodile
    api/
      AGENTS.md                → Reeglid spetsiifiliselt API-dele
      routes/
        AGENTS.md              → Reeglid ruutidele (routes)
    components/
      AGENTS.md                → Reeglid Reacti komponentidele
  tests/
    AGENTS.md                  → Reeglid testidele

Reeglid kumuleeruvad: Codex liidab failid juurest kuni praeguse kataloogini ning need, mis asuvad sellele kataloogile kõige lähemal ja loetakse viimasena, kirjutavad üldised juhised üle. Üht punkti on lihtne valesti mõista: loetakse ainult katalooge, mis jäävad teele juure ja praeguse kataloogi vahele. Kui sinu juurfail keelab any kasutamise, kuid tests/AGENTS.md lubab mockides leebemaid väiteid, kehtib see tolerantsus ainult siis, kui Codex töötab kataloogist tests/ või selle alamkataloogist; juurest käivitamisel faili tests/AGENTS.md ei loeta. GitHubi koodi ülevaade toimib teisiti: Codex otsib kogu hoidlast faile AGENTS.md ja rakendab ülevaatusreegleid (## Code Review Rules) failist, mis asub vaadatavale koodile kõige lähemal. Liitmine peatub vaikimisi 32 KiB juures (project_doc_max_bytes): liiga pikk fail kärbitakse.

Jaotised, mis teevad failist toimiva

Kontekst tuleb esimesena, sest see kujundab iga järgnevat otsust. GDPRi (üldine andmekaitsemäärus) alla kuuluvat SaaS-rakendust ei kodeerita samamoodi nagu viiele inimesele mõeldud sisetööriista:

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

Teades, et tegemist on GDPRi alla kuuluvate andmetega, lisab Codex oodatud kaitsemeetmed ilma, et peaksid neid igas päringus eraldi täpsustama. Järgnevad konventsioonid, mis vastavad ühele küsimusele: kuidas näeb siin korrektne kood välja?

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

Käskude jaotis on kõige sagedamini ära jäetud ja selle puudumine on kulukas: ilma nende käskudeta ei saa Codex oma tööd kontrollida ja tagastab koodi, mida ta pole kunagi käivitanud ega testinud.

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

Ranged reeglid moodustavad kaitseraudtee. Sõnastatuna kui „MITTE KUNAGI“ ja „ALATI“, hoiavad need ära vigu, mille parandamine võtab terve õhtu: kustutatud Prisma migratsioon, mille pead tootmisest uuesti üles ehitama, kommitud saladus, mis tuleb tühistada, või komponenti libisenud innerHTML, mis avab XSS-haavatavuse.

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

Lõpuks kirjeldab arhitektuur lubatud voogu kihtide vahel. Ilma selleta toodab Codex koodi, mis töötab, kuid lühiseb sinu struktuuri – näiteks ruut (route), mis pärib Prisma otse, sest see oli lühim tee.

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

Sellele lisanduvad projekti haaval juhised, mis on spetsiifilised iga kasutatava tehnoloogia jaoks:

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

Kaks mustrit, mis hoiavad ära üllatusi

Oodatavate keskkonnamuutujate deklareerimine hoiab ära olukorra, kus Codex leiutab skripti kirjutamisel võtmenimesid või logib tahtmatult tundliku väärtuse silumisrajale:

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

Eelistatud teekide ja eriti nende nimetamine, mida keeldud kasutamast, lahendab korduva tüütuse: agent paigaldab sõltuvuse, mis iseenesest on täiesti korrektne, kuid mille sinu meeskond kahe aasta eest halva kogemuse tõttu tagasi lükkas.

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

Faili elus hoidmine

AGENTS.md areneb koos sinu koodiga, täpselt nagu test või README. Uuenda seda niipea, kui võtad kasutusele uue konventsiooni, vahetad teeke või raamistikke, ja eriti niipea, kui tuvastad korduva Codexi vea: see viimane juhtum annab alati märku puuduvast juhendist, mitte mudeli rikkest. Tasub tähele panna ka neljandat, peenemat käivitajat – kui uus arendaja esitab küsimuse, millele AGENTS.md oleks pidanud vastama, kuulub see vastus faili.

Peamised punktid

  • AGENTS.md hierarhia võimaldab järjest spetsiifilisemaid juhiseid
  • Käsud on Codexile oma töö kontrollimiseks kriitilised
  • MITTE KUNAGI reeglid on vigade vältimisel kõige olulisemad
  • Dokumenteeri eelistatud sõltuvused, et vältida halbu valikuid
  • Hoolda AGENTS.md kui elatavat koodi