Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

AGENTS.md: konfiguracija navodil za vaše skladišče

Lekcija 15 od 20 Posodobljeno 3. november 2026 Razvijalec
Na tej strani
  1. Obvladovanje konfiguracijske datoteke Codex
  2. Hierarhija datoteke AGENTS.md
  3. Odseki, ki sestavljajo datoteko
  4. Dva vzorca, ki preprečujeta presenečenja
  5. Ohranjanje datoteke živo
  6. Ključne ugotovitve

Lekcija posodobljena 3. novembra 2026 na podlagi strani Custom instructions with AGENTS.md: Codex bere samo datoteke AGENTS.md, ki se nahajajo med korenom projekta in trenutnim delovnim imenikom (plus globalna datoteka na ~/.codex). Datoteka v podimeniku zunaj te poti se ne naloži, kar je v nasprotju s tem, kar je implicirala prejšnja različica. Vir: AGENTS.md.

Obvladovanje konfiguracijske datoteke Codex

Datoteko AGENTS.md si spoznal v lekciji 3. Tu se poglabljamo v napredne vzorce – razliko med okrasno datoteko (tri vrstice, napisane ob zagonu in pozabljene) in tisto, ki dejansko usmerja obnašanje agenta na živem projektu.

Hierarhija datoteke AGENTS.md

Codex te datoteke bere hierarhično, od splošnega k specifičnemu: najprej globalno datoteko v mapi Codex (~/.codex/AGENTS.md ali AGENTS.override.md, če obstaja), nato pa, začenši s korenom projekta, datoteke v imenikih, skozi katere poteka pot do trenutnega delovnega imenika. Pri strukturiranem projektu drevo izgleda takole:

mon-projet/
  AGENTS.md                    → Globalna pravila (nizka prioriteta)
  src/
    AGENTS.md                  → Pravila za vso izvorno kodo
    api/
      AGENTS.md                → Pravila, specifična za API-je
      routes/
        AGENTS.md              → Pravila za rute
    components/
      AGENTS.md                → Pravila za React komponente
  tests/
    AGENTS.md                  → Pravila za teste

Pravila se seštevajo: Codex združi datoteke od korena navzdol do trenutnega imenika, pri čemer tiste, ki so najbližje temu imeniku in se berejo zadnje, povozijo splošna navodila. Ena točka je pogosto napačno razumljena: preberejo se samo imeniki na poti med korenom in trenutnim imenikom. Če tvoja korenska datoteka prepoveduje any, medtem ko tests/AGENTS.md dovoljuje ohlapnejše trditve v mockih, ta toleranca velja le, ko Codex dela iz tests/ ali enega od njegovih podimenikov; če ga zaženeš iz korena, datoteke tests/AGENTS.md ne prebere. Pregled kode GitHub deluje drugače: Codex tam išče po celotnem skladišču za datotekami AGENTS.md in uporabi pravila za pregled (## Code Review Rules) iz datoteke, ki je najbližje zadevni kodi. Združevanje se privzeto ustavi pri 32 KiB (project_doc_max_bytes): predolga datoteka se oklesti.

Odseki, ki sestavljajo datoteko

Kontekst je na prvem mestu, saj oblikuje vsako naslednjo odločitev. SaaS aplikacija, ki mora upoštevati GDPR (Splošno uredbo o varstvu podatkov), ni kodirana enako kot interno orodje za pet ljudi:

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

Ker ve, da obravnava podatke, ki spadajo pod GDPR, bo Codex dodal pričakovane zaščite, ne da bi jih moral navajati v vsaki zahtevi. Sledijo konvencije, ki odgovarjajo na eno vprašanje: kako izgleda pravilna koda tukaj?

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

Odsek ukazov je najpogosteje izpuščen, njegova odsotnost pa je draga: brez teh ukazov Codex ne more preveriti svojega dela in vrne kodo, ki je nikoli ni izvedel ali testiral.

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

Stroga pravila tvorijo varnostno ograjo. Oblikovana kot „NIKOLI” in „VEDNO”, preprečujejo napake, ki stanejo cel večer popravkov: izbrisana migracija Prisma, ki jo moraš rekonstruirati iz produkcije, skrivnost, ki je bila commitana in jo je treba preklicati, ali innerHTML, vtihotapljen v komponento, ki odpira ranljivost 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

Nazadnje arhitektura opisuje dovoljen pretok med plastmi. Brez nje Codex ustvari kodo, ki deluje, a obide tvojo strukturo – na primer ruta, ki neposredno poizveduje v Prisma, ker je bila to najkrajša pot.

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

Temu se projekt za projektom dodajo navodila, specifična za vsako uporabljeno tehnologijo:

## 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 vzorca, ki preprečujeta presenečenja

Deklariranje pričakovanih spremenljivk okolja prepreči, da bi Codex izmislil imena ključev pri pisanju skripte ali pomotoma zapisal občutljivo vrednost v sledenje za odpravljanje napak:

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

Poimenovanje tvojih preferiranih knjižnic, še posebej tistih, ki jih zavračaš, reši ponavljajočo se nadlogo: agent namesti odvisnost, ki je sama po sebi popolnoma veljavna, a jo je tvoja ekipa pred dvema letoma zavrnila po slabi izkušnji.

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

Ohranjanje datoteke živo

AGENTS.md se razvija s tvojo kodo, tako kot test ali README. Posodobi jo takoj, ko sprejmeš novo konvencijo, zamenjaš knjižnice ali ogrodja in še posebej, ko identificiraš ponavljajočo se napako Codexa: ta zadnji primer vedno signalizira manjkajoče navodilo in ne napako modela. Vreden pozornosti je še četrti, bolj subtilen sprožilec – ko nov razvijalec postavi vprašanje, na katerega bi moral AGENTS.md odgovoriti, ta odgovor spada v datoteko.

Ključne ugotovitve

  • Hierarhija datoteke AGENTS.md omogoča vse bolj specifična navodila
  • Ukazi so ključni, da Codex preveri svoje delo
  • Pravila NIKOLI so najpomembnejša za preprečevanje napak
  • Dokumentiraj preferirane odvisnosti, da preprečiš slabe izbire
  • Vzdržuj AGENTS.md kot živo kodo