Kako napisati CLAUDE.md i AGENTS.md za AI agente

Direktan odgovor: CLAUDE.md i AGENTS.md su obični markdown fajlovi koje postavljate u korenu repozitorijuma da bi AI agent za programiranje pri pokretanju pročitao trajna uputstva o projektu: komande za instalaciju, build i test, konvencije koda, arhitekturu, šta da ne radi. Claude Code po podrazumevanom podešavanju čita CLAUDE.md kad postoji, a AGENTS.md kad CLAUDE.md nema. Ako prvi put radite sa Claude Code, korisno je prvo pogledati osnovni vodič za rad u terminalu, a ovaj tekst se bavi samo fajlom sa uputstvima koji agent čita pri pokretanju.

1. Čemu služi CLAUDE.md

Svaka sesija Claude Code počinje sa praznim kontekstom. Agent ne zna napamet da li projekat koristi npm ili pnpm, da li testovi idu preko Jest ili PHPUnit, ili da li tim ima pravilo da se nikad ne komituje direktno na main. CLAUDE.md je mesto gde se to upiše jednom, da se ne ponavlja u svakom razgovoru.

Prema zvaničnoj dokumentaciji alata, u fajl vredi dodati stavku kad agent dva puta napravi istu grešku, kad code review otkrije nešto što je agent trebalo da zna o kodu, ili kad se u razgovoru ukucava ista ispravka koja je već data prošle sesije. Isto važi i za freelancere u Srbiji koji paralelno održavaju više repozitorijuma za strane klijente, jer se uputstva ne gube kad se agent pokrene iznova u drugom projektu.

2. Gde fajl ide u projektu

Claude Code čita CLAUDE.md iz nekoliko mesta, od najšireg ka najužem obimu:

Obim	Lokacija	Za šta služi
Organizacija	npr. /etc/claude-code/CLAUDE.md	Pravila firme za sve zaposlene, podešava IT ili DevOps
Korisnik	~/.claude/CLAUDE.md	Lične navike, važi za sve projekte jednog developera
Projekat	./CLAUDE.md ili ./.claude/CLAUDE.md	Timska uputstva, ide u git, deli se preko verzionog sistema
Lokalno	./CLAUDE.local.md	Lične napomene za taj projekat, ide u .gitignore

Za većinu timova bitan je samo projektni fajl, u korenu repozitorijuma. Claude Code ga automatski učitava pri pokretanju u tom direktorijumu i u svim direktorijumima iznad njega, a CLAUDE.md u poddirektorijumu učitava kad agent otvori fajl u toj grani koda.

3. Šta upisati, sa primerom

Dobro uputstvo je konkretno i provarljivo. Umesto "formatiraj kod lepo" piše se "koristi uvlačenje od dva razmaka". Umesto "testiraj izmene" piše se "pre komita pokreni npm test". Primer kratkog projektnog fajla za Node.js projekat:

# Projekat
Internet prodavnica, Next.js 15 i Postgres preko Prisme.

## Komande
- Instalacija: npm install
- Dev server: npm run dev
- Testovi: npm test
- Build: npm run build

## Konvencije
- TypeScript strict mode, bez any.
- Komponente u src/components, po jedna po fajlu.
- API rute u src/app/api, svaka sa svojim route.ts.
- Stilovi preko Tailwinda, ne pisati custom CSS fajlove.

## Pravila
- Ne menjati migracije u prisma/migrations, uvek nova migracija.
- Ne pushovati direktno na main, samo preko pull requesta.

Ako ne želite da fajl pišete od nule, komanda /init u sesiji Claude Code analizira kod i sama predlaže početni CLAUDE.md sa komandama i konvencijama koje otkrije u projektu. Ako fajl već postoji, /init predlaže poboljšanja umesto da ga prepisuje.

Zvanična preporuka je da fajl ostane kratak, ispod 200 linija, jer duži fajl troši više konteksta i smanjuje doslednost kojom agent prati uputstva. Ako neko pravilo važi samo za jedan deo koda, bolje ga je izdvojiti u poseban fajl nego gurati u glavni CLAUDE.md.

4. CLAUDE.md ili AGENTS.md, i koja je razlika

AGENTS.md je otvoren format bez fiksne šeme, koji su zajedno postavili OpenAI Codex, Cursor, Google Jules, Factory i drugi alati za programiranje koje smo ranije poredili po ceni i nameni, a danas ga vodi Agentic AI Foundation pod Linux fondacijom. Ideja je da jedan fajl čita više alata, umesto da svaki traži svoj format.

Pravilo po kom Claude Code bira koji fajl da pročita je jednostavno: ako projekat, ili neki direktorijum iznad njega, ima CLAUDE.md, čita se on. Ako nema, a postoji AGENTS.md, čita se taj. Ta podrška je uvedena u septembru 2026, i do tada su timovi koji su radili sa više alata morali ručno da uvoze jedan fajl u drugi.

Za timove koji već imaju AGENTS.md iz rada sa Codexom ili Cursorom, najjednostavnije je da ga ne diraju, Claude Code će ga pročitati sam. Novi projekat koji koristi samo Claude Code može slobodno da piše CLAUDE.md, format je isti, samo je ime fajla drugačije.

5. Kako podesiti koji fajl se čita kad imate oba

Ako projekat ima i CLAUDE.md i AGENTS.md, Claude Code po podrazumevanom podešavanju čita samo CLAUDE.md. To se menja komandom /config u sesiji, u polju "Project instructions", gde su na izbor: čitanje samo CLAUDE.md, čitanje CLAUDE.md ili AGENTS.md (podrazumevano), čitanje oba fajla zajedno, ili čitanje samo organizacionih pravila. Za tim koji želi da održava jedan zajednički fajl za sve alate, a da Claude Code ipak doda svoja specifična uputstva, rešenje je da CLAUDE.md na vrhu uveze AGENTS.md:

@AGENTS.md

## Claude Code
Za izmene u src/billing koristi plan mode.

Uvoz radi preko znaka @ ispred putanje, a uvezeni fajl se učitava zajedno sa ostatkom CLAUDE.md. Isti mehanizam koristi se i za uvoz README-a, package.json ili bilo kog drugog fajla koji agent treba da pročita pri startu.

6. Kad projekat naraste, pravila idu u .claude/rules/

Jedan fajl brzo postane pregust kad projekat ima frontend, backend i infrastrukturu u istom repozitorijumu. Za to postoji direktorijum .claude/rules/, gde se pravila dele po temi, na primer testing.md ili security.md, i po želji ograničavaju na određene putanje preko paths polja u zaglavlju fajla:

---
paths:
  - "src/api/**/*.ts"
---

# Pravila za API
- Svaka ruta mora da ima validaciju unosa.
- Greške se vraćaju u standardnom formatu.

Pravilo bez paths polja učitava se uvek, kao i CLAUDE.md. Pravilo sa paths poljem učitava se samo kad agent radi sa fajlom koji odgovara obrascu, što čuva kontekst za projekte sa više modula. Za još dublje prilagođavanje ponašanja agenta po fazama rada, Claude Code od kraja septembra 2026 nudi i posebne modove pisane u TypeScript-u, sledeći korak kad pravila u .claude/rules/ više nisu dovoljna.

7. Najčešće greške

• Fajl koji niko ne ažurira. Uputstvo za alat koji je tim davno napustio ostaje u fajlu i agent ga i dalje prati. Komanda za proveru je /doctor prompt-audit, koja traži zastarele i kontradiktorne stavke.
• Dve kontradiktorne stavke. Ako CLAUDE.md u korenu kaže jedno, a CLAUDE.md u poddirektorijumu drugo, agent proizvoljno bira koju će pratiti.
• Fajl kao zamena za sigurnosnu kontrolu. CLAUDE.md je kontekst, ne prisilno podešavanje, agent ga uglavnom prati, ali ne garantovano. Za pravilo koje mora da važi bez izuzetka, kao zabrana brisanja tabele u bazi, koristi se hook, ne rečenica u CLAUDE.md.
• Previše opštih formulacija. "Piši čist kod" ne govori agentu ništa merljivo, dok "funkcije kraće od 40 linija" može da se proveri.