AGENTS.md: Konfiguriraj upute za svoj repozitorij
Na ovoj stranici
Lekcija ažurirana 3. studenog 2026. na temelju stranice Custom instructions with AGENTS.md: Codex čita samo datoteke
AGENTS.mdkoje se nalaze između korijena projekta i trenutnog radnog direktorija (plus globalnu datoteku na~/.codex). Datoteka u poddirektoriju izvan ovog puta se ne učitava, suprotno onome što je prethodna verzija implicirala. Izvor: AGENTS.md.
Savladavanje konfiguracijske datoteke Codexa
Upoznao/la si AGENTS.md u Lekciji 3. Ovdje ulazimo u napredne obrasce – razliku između dekorativne datoteke (tri retka napisana pri pokretanju i zaboravljena) i one koja zapravo pokreće ponašanje agenta na živom projektu.
Hijerarhija datoteke AGENTS.md
Codex čita ove datoteke hijerarhijski, od općeg prema specifičnom: prvo globalnu datoteku u tvojoj Codex mapi (~/.codex/AGENTS.md, ili AGENTS.override.md ako postoji), zatim, počevši od korijena projekta, datoteke u direktorijima kroz koje se prolazi sve do trenutnog radnog direktorija. Na strukturiranom projektu stablo izgleda ovako:
mon-projet/
AGENTS.md → Globalna pravila (nizak prioritet)
src/
AGENTS.md → Pravila za sav izvorni kod
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 testove
Pravila se akumuliraju: Codex spaja datoteke od korijena prema dolje do trenutnog direktorija, a one najbliže tom direktoriju, pročitane zadnje, nadjačavaju opće upute. Jedna se točka lako pogrešno shvati: čitaju se samo direktoriji na putu između korijena i trenutnog direktorija. Ako tvoja korijenska datoteka zabranjuje any, dok tests/AGENTS.md dopušta labavije tvrdnje u mockovima, ta tolerancija vrijedi samo kada Codex radi iz tests/ ili jednog od njegovih poddirektorija; ako se pokrene iz korijena, ne čita tests/AGENTS.md. Za pravilo koje se mora primjenjivati svugdje, stavi ga u korijen, čak i ako tamo moraš imenovati iznimku. GitHub pregled koda radi drugačije: Codex pretražuje cijeli repozitorij tražeći datoteke AGENTS.md i primjenjuje pravila pregleda (## Code Review Rules) iz datoteke najbliže dotičnom kodu. Spajanje se prema zadanim postavkama zaustavlja na 32 KiB (project_doc_max_bytes): preduga datoteka se skraćuje.
Odjeljci koji čine datoteku
Kontekst dolazi prvi jer oblikuje svaku odluku koja slijedi. SaaS aplikacija podložna GDPR-u (Opća uredba o zaštiti podataka) ne kodira se kao interni alat 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.
Znajući da obrađuje podatke podložne GDPR-u, Codex će dodati očekivane zaštite bez da ih moraš navoditi u svakom zahtjevu. Zatim slijede konvencije, koje odgovaraju na jedno pitanje: kako ovdje izgleda ispravan kod?
## 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)
Odjeljak naredbi najčešće se izostavlja, a njegov izostanak je skup: bez ovih naredbi, Codex ne može verificirati svoj vlastiti rad i vraća kod koji nikada nije izvršen niti testiran.
## 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 čine zaštitnu ogradu. Formulirana kao „NIKADA“ i „UVIJEK“, sprječavaju greške koje koštaju cijelu večer popravka: izbrisana Prisma migracija koju moraš rekonstruirati iz produkcije, tajna ključeva commitana u kod koju treba opozvati ili innerHTML provučen u komponentu koji otvara XSS ranjivost.
## 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
Konačno, arhitektura opisuje dopušteni tok između slojeva. Bez nje, Codex proizvodi kod koji radi, ali zaobilazi tvoju strukturu – ruta koja izravno upituje Prisma, na primjer, jer je to bio najkraći put.
## 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.
Ovome se, projekt po projekt, dodaju upute specifične za svaku korištenu tehnologiju:
## 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 obrasca koja sprječavaju iznenađenja
Deklariranje očekivanih varijabli okruženja sprječava Codex da izmišlja nazive ključeva pri pisanju skripte ili slučajno bilježi osjetljivu vrijednost u debug trag:
## 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)
Imenovanje tvojih preferiranih knjižnica, a posebno onih koje odbijaš, rješava ponavljajuću smetnju: agent instalira ovisnost koja je sama po sebi savršeno valjana, ali koju je tvoj tim odbacio prije dvije godine nakon lošeg iskustva.
## 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)
Održavanje datoteke živom
AGENTS.md evoluira s tvojim kodom, baš kao test ili README. Ažuriraj je čim usvojiš novu konvenciju, promijeniš knjižnice ili framework, a posebno čim identificiraš ponavljajuću Codex grešku: taj posljednji slučaj uvijek signalizira nedostajuću uputu, a ne kvar modela. Četvrti, suptilniji okidač vrijedi pratiti – kada novi programer postavi pitanje na koje je AGENTS.md trebao odgovoriti, taj odgovor pripada u datoteku.
Ključne točke
- Hijerarhija datoteke
AGENTS.mdomogućuje sve specifičnije upute - Naredbe su ključne da Codex verificira svoj rad
- Pravila NIKADA najvažnija su za izbjegavanje grešaka
- Dokumentiraj preferirane ovisnosti kako bi spriječio loše odabire
- Održavaj
AGENTS.mdkao živi kod