George Nurijanian: dobre prakse pisanja CLAUDE.md i AGENTS.md fajlova

Kako AI agenti za kodiranje i alati za automatizaciju produktnih procesa postaju deo svakodnevnog rada, timovi počinju da shvataju da način na koji pišete uputstva za agente znači jednako koliko i izbor alata. Ovaj članak Georgea Nurijanijna, objavljen u aprilu 2026. u okviru PM OS newsletter-a, dokazuje da intuitivan poriv ka pisanju detaljnih kontekstnih fajlova za AI agente donosi suprotan efekat — i objašnjava šta zapravo funkcioniše.

Ključna tvrdnja potkrepljena je istraživanjem ETH Zurich-a: automatski generisani CLAUDE.md fajlovi koji su bili dugi i detaljni smanjili su stopu uspešnosti zadataka za 3% i povećali troškove tokena za 20% u poređenju s kraćim, ručno pisanim fajlovima. Razlog je strukturalan: AI agenti rade sa oko 100 dostupnih slotova za uputstva nakon što se uzmu u obzir sistemski promptovi. Duži kontekstni fajl ravnomerno smanjuje preciznost izvršavanja svih uputstava — svaki dodati red čini sve ostale redove nešto manje pouzdanim.

Šta uključiti

Nurijanian identifikuje mali skup elemenata koji stvarno poboljšavaju rad agenata. Jasno opisivanje projekta i ciljnih korisnika. Tačan tehnološki stack sa specifičnim verzijama. CLI komande za uobičajene zadatke, napisane precizno a ne opisno. Konvencije koje linter ne može da uhvati — kao što su obrasci imenovanja ili redosled pozivanja API-ja. I tvrda ograničenja napisana kao eksplicitne zabrane (konstrukti “NEVER”), koje agenti tretiraju kao signale višeg prioriteta.

Šta izostaviti

Stabla direktorijuma, automatski generisan sadržaj i kompletna API dokumentacija ne bi trebalo da se pojavljuju u CLAUDE.md fajlu. Ako dokumentacija postoji negde drugde, stavite link na nju. Neodređene personalne instrukcije (“ti si iskusan PM asistent”) dodaju šum bez poboljšanja rezultata. Pravila koje linter već primenjuje su redundantna — agent ne treba da zna ono čime already upravlja alat.

Strukturalne preporuke

Preporučeni koreni CLAUDE.md fajl ostaje ispod 80 linija. Za veće kodne baze ili projekte s više domena, specifična uputstva bolje je smestiti u poddirektorijume .claude/rules/ umesto da se pretrpava koreni fajl. Članak takođe preporučuje pisanje AGENTS.md kao primarnog izvora informacija i njegovo uvoženje u CLAUDE.md, kako bi uputstva za agente ostala odvojena od dokumentacije koju čitaju ljudi.

Jedna praktična navika: ažurirajte kontekstne fajlove posle svake korekcije. Ako agent ponavlja istu grešku i vi je ručno ispravite, dodavanje “NEVER” konstrukta sprečava istu grešku u narednim pokretanjima. Tretiranje kontekstnog fajla kao živog dokumenta koji odražava stvarne obrasce grešaka efikasnije je od pisanja od nule na osnovu pretpostavljenih potreba.

Za koga je ovaj materijal

PM-ovi koji koriste Claude Code, Cursor ili slične agentne alate u svom radu — za dokumentaciju, sintezu istraživanja, pisanje PRD-ova ili automatizaciju procesa — dobiće neposrednu vrednost od ovoga. Tehnički lideri koji standardizuju interakciju produktnog tima s AI agentima takođe će naći strukturalne preporuke korisnim. Principi se primenjuju na različite alate, ne samo na Anthropic ekosistem.