Kolega u čudu: „I ja koristim Codex, ali tvoj AGENTS.md ima 2000 redova — tretiraš ga kao Prompt ili kao Readme?“

Chenmo Wang Er2625 reči9 minuta

Codex je u poslednje vreme veoma popularan i zajedno sa Claude Code-om postao je, nakon OpenClaw-a, još jedna vrela reč u AI krugu.

Ja svakako — za tekstualne poslove koristim Claude Code, a za teže Codex.

Uz obojicu zajedno, svet je moj.

U prethodnom članku analizirali smo CLAUDE.md za Claude Code; danas da analiziramo AGENTS.md za Codex.

Iskreno, prvi put kad pišem AGENTS.md, uvek mi se čini da je to samo README.

Ali sa dubljom upotrebom i razumevanjem Codex-a, postepeno se menjala percepcija. Zaista su oba Markdown fajlovi, ali između dobro napisanog i loše napisanog, razlika u inženjerskoj sposobnosti Codex-a je ogromna.

Mnogi verovatno nemaju vremena za analizu; u ovom članku potrošio sam mnogo token-a na istraživanje i analizu, tako da ćete sigurno nakon čitanja razumeti, moći ćete da diskutujete sa intervjuerom i napišete visokokvalitetni AGENTS.md.

Zavežite pojaseve, krećemo.

01. Šta je zapravo AGENTS.md

Da prvo raščistimo osnovni koncept.

AGENTS.md je fajl sa uputstvima za programiranje u Codex-u; čistog je Markdown formata, nema obaveznih polja i dovoljno ga je staviti u koreni direktorijum projekta.

A koja je najveća razlika u odnosu na CLAUDE.md?

CLAUDE.md je privatni fajl sa uputstvima za Claude Code; prepoznaje ga samo Claude Code.

AGENTS.md je otvoreni standard kojim upravlja Agentic AI Foundation pod okriljem Linux fondacije; trenutno ga je usvojilo preko 60.000 open source projekata, podržava preko 25 alata, uključujući OpenAI Codex, Google Jules, GitHub Copilot, Cursor, Aider, Zed, JetBrains Junie itd.

Jedan fajl, univerzalan za više Agenata.

Naravno, i Claude Code može da podrži AGENTS.md. Moj uobičajeni pristup je: u CLAUDE.md dodam jedan red @AGENTS.md i time uvezem sadržaj AGENTS.md. Tako oba rade.

A koja je razlika između AGENTS.md i README.md?

README.md je pisan za ljude i govori developerima „čemu služi ovaj projekat, kako da se pokrene, kako da doprinesu kodu“.
AGENTS.md je pisan za Agenta i govori AI-ju „koje su komande za build, koji su zahtevi za stil koda, koji direktorijumi se ne smeju dirati, koje fajlove treba sinhronizovati nakon izmene koda“.

02. Mehanizam učitavanja u Codex-u

Da bismo razumeli gde treba smestiti AGENTS.md i kako da ga organizujemo, moramo da razumemo mehanizam učitavanja.

Pri svakom pokretanju, Codex gradi lanac uputstava (instruction chain); ovaj proces se izvršava samo jednom.

Redosled učitavanja je u dva sloja:

Prvi sloj: globalna konfiguracija. Codex prvo traži u direktorijumu ~/.codex/. Ako postoji AGENTS.override.md, čita njega; ako ne postoji, čita AGENTS.md. Obratite pažnju — uzima se samo jedan od njih, bez slaganja.

~/.codex/
├── AGENTS.md              # globalna podrazumevana uputstva
├── AGENTS.override.md     # globalna uputstva za override (zamenjuje AGENTS.md kada postoji)
└── config.toml            # konfiguracioni fajl Codex-a

Drugi sloj: konfiguracija projekta. Polazeći od korenog direktorijuma projekta (obično Git koren), ide se sve do vašeg trenutnog radnog direktorijuma. U svakom direktorijumu se traži ovim redosledom: AGENTS.override.md → AGENTS.md → fallback ime fajla. Pronadjeni fajlovi se nadovezuju po redosledu.

Na primer, pretpostavimo da je struktura vašeg projekta sledeća:

my-project/
├── AGENTS.md                         # pravila korenog direktorijuma projekta
├── services/
│   └── payments/
│       └── AGENTS.override.md        # pravila override za payments poddirektorijum
└── frontend/
    └── AGENTS.md                     # pravila za frontend poddirektorijum

Ako pokrenete Codex iz direktorijuma services/payments/, putanja učitavanja je:

~/.codex/AGENTS.md (globalno podrazumevano)
my-project/AGENTS.md (koreni direktorijum projekta)
my-project/services/payments/AGENTS.override.md (override trenutnog direktorijuma)

Sadržaj tri fajla se nadovezuje, pri čemu oni kasniji u nizu imaju viši prioritet.

Mudrost override-a

AGENTS.override.md je veoma elegantno rešenje. Njegova uloga je „ne želim da menjam originalni fajl, ali mi treba privremeni override određenih pravila“.

Na primer, vaša kompanija ima jedinstveni ~/.codex/AGENTS.md, ali vam danas treba eksperiment sa drugačijim skupom pravila; napravite AGENTS.override.md, nakon eksperimenta ga obrišete, a originalni fajl ostaje potpuno netaknut.

Poređenje sa Claude Code-om

Sistem učitavanja Claude Code-a je četvoroslojan: sistemski nivo → korisnički nivo (~/.claude/CLAUDE.md) → nivo projekta → lokalni override (CLAUDE.local.md).

Dizajn Codex-a je drugačiji. Pri pokretanju on odjednom nadovezuje sve AGENTS.md na trenutnoj putanji i kasnije ih ne učitava dinamički. To znači da su uputstva Codex-a „određena pri pokretanju, nepromenjena tokom rada“.

Još jedna razlika u detalju: Codex ima konfiguraciju project_doc_max_bytes, podrazumevano 32 KiB.

Ukupna veličina nakon nadovezivanja svih AGENTS.md fajlova ne sme da pređe tu vrednost; ako pređe, biće skraćena. Claude Code nema taj hard limit, ali ima mekano ograničenje u vidu budžeta uputstava (u prethodnom članku smo pomenuli: pri gustoći od 500 uputstava tačnost je samo 68%).

U ~/.codex/config.toml možete povećati tu vrednost:

project_doc_max_bytes = 65536
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

project_doc_fallback_filenames je još jedna praktična konfiguracija. Ako vaš projekat iz istorijskih razloga koristi ime fajla poput TEAM_GUIDE.md, ne morate ga preimenovati; dovoljno ga je dodati u fallback listu i Codex će ga tretirati kao AGENTS.md.

03. Zvanični AGENTS.md OpenAI-ja

Sam OpenAI-jev repozitorijum Codex (github.com/openai/codex) ima jedan AGENTS.md.

Izvadio sam jezgro sadržaja iz AGENTS.md u korenu zvaničnog repozitorijuma da vam pokažem:

Konvencije kodiranja za Rust/codex-rs

- Prefix crate names with `codex-` (e.g., `codex-core`)
- Inline variables in format strings when possible
- Never modify code related to sandbox environment variables
- Apply Clippy linting rules
- Avoid ambiguous boolean/Option parameters; prefer enums or named methods
- Use exhaustive match statements and avoid wildcards
- Run `just fmt` automatically after making changes

U ovom skupu pravila ima nekoliko vrednih naučenih stvari.

Prvo, prefiks codex-. Ako se ne napiše, Agent pri kreiranju novog crate-a verovatno će ga nazvati core ili utils, što nije u skladu sa stilom projekta.

Drugo, „Never modify code related to sandbox environment variables“. Crvena linija jasno postavljena — Agent će pri izmenama koda zaobilazi te fajlove.

Treće, „Run just fmt automatically after making changes“. Automatsko formatiranje nakon izmene koda. Ako se ovo ne napiše, kod koji Agent preda možda neće biti uniformisan u formatu.

Arhitektonska ograničenja codex-core

Resist adding to the already-bloated codex-core crate.
Consider whether existing crates provide appropriate homes
or whether creating new workspace crates would better serve the architecture.

Odstupanje od dodavanja novog sadržaja u već naduveni codex-core.

Nema dugačkih objašnjenja šta je „jedna odgovornost“, nema crtanja slojevitih dijagrama arhitekture — samo se saopštava Agentu: ovaj crate je već prevelik, nove funkcije ne gurajte unutra, razmislite o smeštanju u druge crate-ove ili kreiranju novog.

04. Kako napisati visokokvalitetni AGENTS.md

OpenAI zvanično u dokumentu o najboljim praksama kaže jednu posebno suptilnu rečenicu:

A short, accurate AGENTS.md is more useful than a long file full of vague rules.

Kratko i precizno AGENTS.md je mnogo korisnije od dugačkog fajla punog nejasnih pravila. Ista je stvar kao i sa „budžetom uputstava“ o kom smo pričali u prethodnom članku o CLAUDE.md.

Što više pišete, to je manja stopa poštovanja od strane Agenta.

Šta treba pisati

①. Komande za build i test. Ovo je najosnovnije i najčešće korišćene informacije za Agenta.

Agent pri svakoj izmeni koda mora da zna kako da gradi i kako da pokrene testove. Ako je jasno napisano, Agent može automatski da završi ceo tok „izmena koda → build → test → formatiranje“.

Ako vaš projekat ima više načina testiranja (brza regresija, puni test, pojedinačni test), nabrojite sve; Agent će prema scenariju izabrati najprikladniji. Ako vam je kod vruće-deploy, ova tačka je još važnija, inače će vas svaki build izluđivati.

②. Projektno specifične konvencije kodiranja. Pišite samo ono što se razlikuje od industrijskog podrazumevanog.

Ako se vaš tim dogovorio da objekti zahteva koriste sufiks *Params, a odgovori *Response, a to se ne napiše, Agent će možda čas koristiti *Request, čas *Req; stil imenovanja će biti potpuno izmešan.

③. Crvene linije. „Zabranjeno predati .env fajl“, „ne dodavati nove funkcije u codex-core“. To su kruta ograničenja čije kršenje izaziva ozbiljne posledice.

Crvene linije je najbolje pisati jasnim negativnim formulacijama poput „zabranjeno“, „ne“, „Never“, kako bi Agent pri radu sa tim fajlovima u prvom trenutku aktivirao pažnju.

④. Strategija lociranja koda. „search_code je RAG pomoć; prvo koristite glob → grep → read“.

Recite Agentu na koji način je najefikasnije pronaći kod. Optimalan put pretrage koda razlikuje se od projekta do projekta; podrazumevana strategija pretrage Agenta nije nužno pogodna za vaš projekat. Jasno mu saopštite prioritet i smanjićete mnogo neefikasnih operacija.

05. Sinergija AGENTS.md i CLAUDE.md

Mnogi, kao i ja, koriste i Claude Code i Codex. Kako AGENTS.md i CLAUDE.md da koegzistiraju?

Moj pristup je sledeći.

AGENTS.md kao fajl opštih uputstava. U AGENTS.md napišite „sadržaj koji se mora poštovati bez obzira na to koji Agent se koristi“: komande za build, konvencije koda, arhitekturske dogovore, crvene linije.

CLAUDE.md kao fajl za pojačanje Claude Code-a. U CLAUDE.md pomoću @AGENTS.md uvezite opšta pravila, a zatim dodajte konfiguracije specifične za Claude Code, kao što su reference na Skills, pravila vezana za memoriju, objašnjenja konfiguracije hooks itd.

Prednost ovakvog pristupa je: opšta pravila se održavaju samo na jednom mestu; izmena AGENTS.md odmah deluje na obe strane.

Codex ne zahteva nikakvu dodatnu konfiguraciju; on prirodno čita AGENTS.md.

Još jedan mali trik.

U Codex-ovom config.toml postoji konfiguracija project_doc_fallback_filenames u koju možete dodati CLAUDE.md:

project_doc_fallback_filenames = ["CLAUDE.md", "TEAM_GUIDE.md"]

Tako će, ako u projektu nema AGENTS.md ali ima CLAUDE.md, i Codex čitati njega.

06. Arhitektura Agent Loop-a u Codex-u

AGENTS.md je samo ulaz u uputstva za Codex. Ono što zaista određuje inženjersku sposobnost Codex-a jeste Agent Loop koji stoji iza njega.

OpenAI je ove godine objavio tehnički blog post „Unrolling the Codex Agent Loop“ koji je otkrio unutrašnju arhitekturu jezgrovnog motora — harness-a. Tehnička gustina ovog članka je veoma visoka; izvukao sam ključne tačke.

Izvor: https://openai.com/index/unrolling-the-codex-agent-loop/

Kompletan životni ciklus jednog Turn-a

Agent Loop Codex-a prati klasičan obrazac Agenta: korisnički ulaz → rezonovanje modela → izvršenje alata → rezonovanje modela → ... → konačni odgovor.

Proces od korisničke poruke do odgovora Codex-a naziva se jedan Turn. Unutar jednog Turn-a može biti desetine ciklusa „rezonovanje modela → poziv alata“.

Izlaz modela pri svakom rezonovanju može biti u samo dva oblika: ili je konačni odgovor korisniku, ili je zahtev za poziv alata. Dok god je izlaz poziv alata, ciklus se nastavlja; kada izbaci konačni odgovor, ciklus se završava.

Objedinjeni Harness i App Server

Još jedna važna informacija na nivou arhitekture.

CLI Codex-a, VS Code ekstenzija, Web aplikacija i macOS desktop aplikacija — sve ispod pokreće isti harness.

Ono što ih povezuje je Codex App Server — dvosmerni JSON-RPC API.

Zašto napraviti objedinjeni harness?

Zato što je logika Agent Loop-a veoma kompleksna: konstrukcija Prompt-a, rasipanje alata, upravljanje sandbox-om, kompresija Context-a, optimizacija keša — ako bi svaki klijent to implementirao sam, trošak održavanja bio bi ogroman, a i ponašanje bi moglo biti neusklađeno. Objedinjeni harness obezbeđuje da, bez obzira na to da li koristite Codex u terminalu, IDE-ju ili pretraživaču, ponašanje Agenta bude isto.

Izvor: https://openai.com/index/unlocking-the-codex-harness/

Ova arhitektura ima i jedan nusproizvod: pošto čitav Codex ide preko Open Responses API-ja, u teoriji se može povezati bilo koji model kompatibilan sa tim API-jem, uključujući lokalno deploy-ovane open source modele.

Tim Codex-a je u blogu jasno naveo tu tačku.

Slojevita konstrukcija Prompt-a

Gde se AGENTS.md nalazi u Prompt-u Codex-a?

Konstrukcija Prompt-a u Codex-u je slojevita, poređana po prioritetu od visokog ka niskom:

Tačnije, AGENTS.md se kod Codex-a pronalazi, nadovezuje i zatim kao uputstva korisnika na nivou projekta ubacuje u inicijalni kontekst.

On nije sistemsko uputstvo, niti deo definicije alata. Sistemsko/developerske sigurnosne restrikcije, sandbox politike, politike ovlašćenja i dalje imaju prioritet; AGENTS.md uglavnom nosi trajni kontekst „projektnih dogovora“ i „radnih preferenci“.

Prompt Cache i linearna složenost

Ovo je jezgro mehanizma optimizacije performansi Codex-a.

Agent Loop u svakom krugu mora da modelu preda uputstva, definicije alata, istoriju razgovora i ostali kontekst. Ako se ne optimizuje, sa duženjem razgovora, potrošnja token-a po krugu rezonovanja raste po O(n²) — prvi krug 1000 tokena, drugi 2000, deseti 10000... kumulativna potrošnja raste kvadratno.

Codex pomoću Prompt Cache-a sužava taj problem na O(n). Princip je: stabilan sadržaj prefiksa u Prompt-u može da se kešira; sve dok prefiks tačno odgovara, mogu se ponovo iskoristiti prethodni rezultati izračunavanja i potrebno je izvršiti rezonovanje samo za novi deo.

Ali postoji preduslov: prefiks mora tačno da se poklopi. Promene u listi alata, promene modela, promene konfiguracije sandbox-a, promene approval režima, promene radnog direktorijuma — sve to može izazvati neispravnost keša.

AGENTS.md, kao stabilan projektni kontekst koji se učita pri pokretanju, takođe povoljno utiče na stopu pogođenosti keša. Ali nemojte to shvatiti kao „ovako je dizajnirano radi keširanja“. Tačnije: AGENTS.md pruža stabilna pravila projekta, a Prompt Cache iskorišćava tu stabilnost radi optimizacije performansi.

Kompresija Context Window-a

Kada brojač token-a pređe prag, Codex poziva poseban endpoint /responses/compact.

Ovaj endpoint vraća kompresovanu listu poruka koja zamenjuje originalnu kompletnu istoriju razgovora. Kompresovani sadržaj uključuje jednu šifrovanu compaction stavku koja čuva „latentno razumevanje“ modela o originalnom razgovoru.

Nije u pitanju prosto skraćivanje ili sažetak; za obradu i kompresiju informacija koristi se sam model. Iako kompresovani sadržaj razgovora nestane, razumevanje modela o kontekstu projekta ostaje; zbog kompresije neće „izgubiti pamćenje“.

Za AGENTS.md postoji jedan ključan uticaj:sadržaj AGENTS.md se ne kompresuje.

On pripada inicijalnom kontekstu projekta koji Codex iznova unosi; bez obzira na to koliko razgovor dugačak i koliko puta komprimovan, jezgro pravila u AGENTS.md obično nastavljaju da postoje. To je pravo značenje naziva „trajna uputstva“.

Sistem alata u Codex-u

„Alati“ koje poziva Agent Loop se dele u tri kategorije.

Prvu kategoriju čine ugrađeni alati Codex-a: čitanje i pisanje fajlova, izvršavanje Shell-a, pretraga koda. Ovi alati rade unutar sandbox-a i podložni su politikama sandbox-a.

Drugu kategoriju čine alati koje pruža API, izloženi preko Responses API-ja.

Treću kategoriju čine eksterni alati koje korisnik priključuje preko MCP-a. Takvi alati nisu zaštićeni Codex sandbox-om i moraju sami implementirati sigurnosne granice.

Ove tri kategorije alata se zajedno registruju u sloju Tool Definitions u Prompt-u. Model pri rezonovanju ne razlikuje poreklo alata; on samo gleda naziv, opis i definiciju parametara alata da odluči koga će pozvati.

AGENTS.md ovde može da pomogne — govori modelu koje alate da koristi prvo, a koje da izbegava; to je kao dodati sloj ljudskih preferenci na raspodelu alata.

08. Kako odgovoriti na intervjuu

Nakon objašnjavanja donjih principa, vratimo se na scenario intervjua.

Ako intervjuer pita: „Kada koristiš Codex, kako pišeš AGENTS.md?“

Prva rečenica o standardu. AGENTS.md je otvoreni standard kojim upravlja Linux fondacija. Razlika u odnosu na CLAUDE.md je u tome što je CLAUDE.md privatni format Claude Code-a, dok je AGENTS.md univerzalan format.

Druga rečenica o učitavanju. Pri pokretanju, Codex gradi lanac uputstava: globalno → koreni direktorijum projekta → trenutni direktorijum, sloj po sloj se nadovezuje, sa višim prioritetom za kasnije. override fajl zamenjuje AGENTS.md na istom nivou. Hard cap od 32 KiB.

Treća rečenica o sadržaju. Pišite samo ono što Agent ne može da zaključi: komande za build, konvencije kodiranja, crvene linije, pravila povezivanja.

Ako intervjuer dalje kopa — „Gde se AGENTS.md nalazi u Prompt-u Codex-a?“

AGENTS.md će Codex agregirati u inicijalni kontekst kao uputstva korisnika na nivou projekta.

Ta pozicija znači dve stvari:

Prvo, niži je od sistemskih/developerskih sigurnosnih i ovlašćujućih ograničenja, ali kao projektni dogovor kontinuirano utiče na ponašanje Agenta;
Drugo, obično je prilično stabilan, što pogoduje tome da Prompt Cache ponovo iskoristi izračunavanje prefiksa, čime se snižavaju troškovi Agent Loop-a kod dugih razgovora.