Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

AGENTS.md: Konfiguriraj upute za svoj repozitorij

Lekcija 15 od 20 Ažurirano 3. studenoga 2026. Programer
Na ovoj stranici
  1. Savladavanje konfiguracijske datoteke Codexa
  2. Hijerarhija datoteke AGENTS.md
  3. Odjeljci koji čine datoteku
  4. Dva obrasca koja sprječavaju iznenađenja
  5. Održavanje datoteke živom
  6. Ključne točke

Lekcija ažurirana 3. studenog 2026. na temelju stranice Custom instructions with AGENTS.md: Codex čita samo datoteke AGENTS.md koje 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.md omoguć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.md kao živi kod