Preskoči na glavni sadržaj

Kako zaista napisati CLAUDE.md da bude koristan?

Put ka boljoj Javi945 reči3 minuta

Kako zaista napisati CLAUDE.md da bude koristan?

Prošli put smo govorili o dugoročnoj memoriji u Claude Code-u, a CLAUDE.md je najznačajniji deo. Znate li zaista da napišete CLAUDE.md?

Razlika u rezultatu projekta između onoga ko ume i onoga ko ne ume da ga napiše je ogromna.

Prečitao sam zvanični blog Anthropic-a, arXiv radove i kroz veliku inženjersku praksu, pa vam danas mogu pomoći da razumete tri stvari:

  • Kakva pravila zaista mogu da deluju?
  • Kako Anthropic sam piše CLAUDE.md?
  • Šta raditi kada pravila postanu previše?

Danas ću vam za 3 minuta razjasniti kako zaista napisati CLAUDE.md da bude koristan.

Zavežite pojaseve, kreeeećemo~

Prvo, kakva pravila zaista mogu da deluju.

Mnogi u CLAUDE.md-u napišu samo ovo: „koristi Javu 17", „poštuj slojevitu arhitekturu", „održavaj kod čistim".

Onda vam moram jasno reći — ovako pisati jednako je kao da niste napisali.

Zašto?

Zato što Claude kada pročita java.version u pom.xml-u već zna da se koristi Java 17, a kada vidi strukturu direktorijuma, već zna kako su slojevi organizovani. „Održavaj kod čistim" je još uzaludnija fraza — šta znači čisto? Bez standarda, Claude to ne može da izvrši, ne zna kako.

Na arXiv-u postoji rad koji je baš to ispitivao: kada se modelu istovremeno da 500 instrukcija, najjači model postiže tačnost od samo 68%. I model daje prednost ranijim instrukcijama, dok se kasnije lakše ignorišu.

Zato CLAUDE.md nije što obimniji to bolji.

Dobar način pisanja ima tri osobine.

Prvo, jedna rečenica je dovoljna. Ako pravilo zahteva tri reda da bi se objasnilo, ili ga razdvojite u tri reda, ili je to znak da je suviše složeno.

Drugo, unesite samo ono što Claude ne može sam da zaključi. Ono što se može zaključiti iz pom.xml-a, strukture koda i konfiguracionih fajlova — nemojte pisati, čist gubitak tokena.

Treće, sadrži jasno akciono uputstvo. „Pazite na sigurnost" je prazna reč, „zabranjeno commit-ovati .env i prave API ključeve" je pravilo.

Evo jednog stvarnog primera. U mom PaiCLI projektu, CLAUDE.md sadrži sledeće:

  • Build: mvn clean package, podrazumevano se preskaču testovi
  • Brza regresija: mvn test -Pquick
  • search_code je RAG pomoć, a ne glavni način lociranja koda — prioritet je grep
  • Promena ulaza komande → sinhronizovati Main.java + CliCommandParser + testove + dokumentaciju
  • Zabranjeno commit-ovati .env, prave API ključeve i target/ produkte

Svaka od njih — ako se jasno ne napiše, Claude Code će sigurno pogrešiti. Claude Code ne može da pogodi da treba mvn clean package, neće podrazumevano preskakati testove, niti može znati da izmena jedne slash komande zahteva sinhronizaciju na četiri mesta.

A pametni među vama će pomisliti: šta onda zaista treba napisati?

Prečitao sam Anthropic-ov sopstveni repozitorijum claude-code-action — njihov CLAUDE.md ima šest sekcija.

Prvo, konkretne komande za build i testove, ne terati Claude da pogađa, već mu jasno saopštiti.

Drugo, jedna rečenica koja objašnjava šta je projekat.

Treće, mehanizam rada, ne opis u stilu dokumentacije, već „ono što morate znati pre nego što promenite kod".

Četvrto, ključni pojmovi, 3 do 5 je dovoljno.

Peto, lista poznatih zamki. Na primer „search_code je RAG pomoć, prioritet je grep". Bez ovoga Claude Code lako greši.

Šesto, konvencije koda — pisati samo ono što odstupa od podrazumevanog.

Jednorečenijski rezime: pišite CLAUDE.md kao uputstvo za novog zaposlenog.

A pametni među vama će opet pitati: ako pratim ovaj šablon, šta kad pravila postanu brojna?

Preporuka Anthropic-a je da CLAUDE.md održavate ispod 80 linija, sa samo najvažnijim pravilima. Ostalo razdvojite po temama u direktorijum .claude/rules/, gde je svaki fajl nezavisan skup pravila.

Još važnije, rules fajlovi mogu imati paths polje koje određuje da se učitavaju samo pri radu u određenim direktorijumima. Na primer, pravila za frontend se aktiviraju samo kad se dodirne tsx fajl, dok se prilikom pisanja Java koda za backend uopšte ne učitavaju — kontekst ne troši ni jedan token.

Zvanično postoji još jedna napomena: održavajte CLAUDE.md kao što održavate kod. Redovno pregledajte, obrišite nepotrebno, naglasite ono što se ne poštuje.

Da li ste savladali ovo znanje? Želite još teških AI saznanja, md

Sledeći šablon se oslanja na strukturu Anthropic-ovog repozitorijuma claude-code-action, u kombinaciji sa inženjerskom praksom, i možete ga direktno kopirati u svoj projekat i prilagoditi:

# CLAUDE.md

## Commands
- Build: mvn clean package -DskipTests
- Testovi: mvn test
- Jedan test: mvn test -Dtest=XxxTest
- Statčka analiza: mvn spotbugs:check
- Formatiranje: mvn spotless:apply

## What This Is
Jedna rečenica koja objašnjava šta je projekat.
Na primer: PaiCLI je terminalski agent u čistoj Javi, ne zavisi od Spring AI/LangGraph4J.

## How It Runs
- Ulaz: Main.java → CliCommandParser raspoređuje komande
- Agent petlja: AgentLoop.java, alati su registrovani u ToolRegistry
- Ne dirajte definicije interfejsa u agent/core/, svi alati zavise od njih

## Key Concepts
- Agent petlja: korisnički unos → odluka LLM-a → izvršavanje alata → povratni rezultat → sledeći krug
- Registracija alata: svi alati implementiraju Tool interfejs, jedinstveno registrovani u ToolRegistry
- Memorija: MemoryManager baziran na perzistenciji u fajlovima

## Things That Will Bite You
- search_code je RAG pomoć, ne i glavni način lociranja koda, prioritet je grep
- Promena ulaza komande → obavezno sinhronizovati Main.java + CliCommandParser + testove + dokumentaciju
- FileUtils obrada putanja ima sandbox ograničenje, ne zaobilazite ga složenjem sopstvenih putanja
- API ključevi u testovima moraju biti mock, zabranjeno commit-ovati prave ključeve

## Code Conventions
- Logovanje preko SLF4J, ne preko System.out
- Izuzeci se ne smeju gutati, bar log.warn
- Sve javne API metode vraćaju jedinstvenu Result omotačku klasu
- Novi alat mora implementirati Tool interfejs i registrovati se u ToolRegistry

## Don't
- Ne pravite direktno new Thread u poslovnom kodu, koristite ExecutorService
- Ne menjajte format .env.example, CI zavisi od njega