studenti.rs home page
AI i alati Vodič

CLAUDE.md pattern: kako da AI razume vaš ceo projekat (i zašto je ta dokumentacija korisna i vama)

· 6 min
Deo 9 od 9 · Preobrazaj platforme
← Prethodni
Sadržaj

48 markdown fajlova. Nastali tokom implementacije, ne posle.

Svaki doc je nastao tako što sam objašnjavao AI-ju šta gradimo. AI je to formatirao u dokumentaciju. Ja sam pregledao i dopunio.

Ali ta dokumentacija nije samo za AI. Postala je najvredniji resurs projekta — i za mene, i za budućeg sebe koji se vraća posle nedelju dana i ne seća se kako nešto radi.

Šta je CLAUDE.md

CLAUDE.md je fajl u root-u projekta koji objašnjava Claude Code alatu sve što treba da zna o vašem kodu. Kada Claude Code otvori projekat, prvo čita ovaj fajl. Odmah razume strukturu, komande, i gde da traži detalje.

# CLAUDE.md

## Komande
pnpm install       # Instaliraj zavisnosti
pnpm dev           # Pokreni razvoj
pnpm test          # Pokreni testove

## Arhitektura
apps/
├── studenti-theme/    # WordPress tema
├── studenti-plugin/   # WordPress plagin
├── studenti-node-api/ # Node.js API
├── studenti-emails/   # React Email šabloni
└── e2e/               # Playwright testovi

## Dokumentacija
| Tema | Fajl |
|------|------|
| Upload pipeline | docs/upload-pipeline.md |
| Članstvo | docs/membership.md |
| Infrastruktura | docs/infrastructure.md |

Šest nivoa memorije — od organizacije do mašinskog učenja

Anthropic je dizajnirao sistem u kome instrukcije dolaze iz šest izvora, organizovanih po specifičnosti. Što je specifičnije, to ima veći prioritet:

┌─ 1. Organizaciona pravila ──── IT/DevOps (svi korisnici)
│
├─ 2. Projekat CLAUDE.md ─────── Tim (deljeno kroz Git)
│
├─ 3. .claude/rules/*.md ─────── Tim (modularna pravila)
│
├─ 4. Lični ~/.claude/CLAUDE.md ─ Samo vi (svi projekti)
│
├─ 5. CLAUDE.local.md ─────────── Samo vi (ovaj projekat)
│
└─ 6. Auto-memorija ──────────── Claude uči sam

Nivo 1: Organizaciona pravila — IT tim postavi pravila za celu firmu. Svi koji koriste Claude Code u organizaciji dobijaju iste instrukcije.

Nivo 2: Projekat CLAUDE.md — Fajl u root-u repozitorijuma. Ide u Git, vidljiv celom timu. Ovo je najvažniji nivo za većinu projekata.

Nivo 3: Modularna pravila — Umesto jednog ogromnog fajla, pravila razdvojena po temama u .claude/rules/ direktorijumu. Svaki fajl može imati uslov kada se primenjuje.

Nivo 4: Lični CLAUDE.md — ~/.claude/CLAUDE.md važi za SVE vaše projekte. Idealno za lična pravila poput "nikada ne koristi git za komitovanje."

Nivo 5: CLAUDE.local.md — Privatna projektna podešavanja. Automatski dodat u .gitignore. Za stvari kao što su lokalni URL-ovi, testni podaci, lični tokovi rada.

Nivo 6: Auto-memorija — Claude sam beleži obrasce koje nauči tokom rada. Čuva ih u ~/.claude/projects/<projekat>/memory/. Indeks fajl MEMORY.md (prvih 200 linija) se učitava na startu svake sesije.

Modularna pravila: .claude/rules/

Umesto jednog dugačkog CLAUDE.md, pravila se mogu razdvojiti u fokusirane fajlove:

.claude/
├── CLAUDE.md
└── rules/
    ├── php-style.md         # PHP konvencije
    ├── testing.md           # Pravila za testove
    └── api/
        └── node-api.md      # Pravila za Node API

Ključna mogućnost: uslovna primena po putanji. Pravila se aktiviraju samo kada Claude radi sa fajlovima koji odgovaraju šablonu:

---
paths:
  - "apps/studenti-node-api/**/*.ts"
  - "apps/studenti-node-api/**/*.tsx"
---

# Node API pravila
- Koristi Hono framework konvencije
- Svaki endpoint mora imati validaciju ulaza
- Testovi uz svaki handler

Pravilo o Node API-ju se učitava samo kada Claude radi sa TypeScript fajlovima u Node API direktorijumu. PHP pravila se ne mešaju.

Granice poverenja

Najvažniji deo CLAUDE.md za solo developera: eksplicitne granice šta AI sme, a šta ne sme.

## Git pravila

Nikada ne koristi git za add/commit/push/pull/rebase.
Obavesti korisnika kada je potrebna git interakcija.
Dozvoljene su samo read-only operacije (status, log, diff).

Zašto? Jer:

  1. Kontrola. Ja odlučujem kada se nešto komituje.
  2. Pregled. Vidim sve promene pre nego što odu u repo.
  3. Sigurnost. git push --force na main u 2 ujutru nije dobra ideja.

AI može da pročita git istoriju. Ne može da je menja. To je granica poverenja.

Pomoćne funkcije: Najkorisniji deo

Bez ovog: AI piše sirove SQL upite za proveru PRO statusa.
Sa ovim: AI koristi studenti_user_has_pro().

## Pomoćne funkcije

studenti_user_has_pro($user_id)           // Proveri PRO status
studenti_can_download($user_id, $post_id) // Proveri pravo preuzimanja
studenti_consume_download($user_id, $post_id)  // Potroši kredit
studenti_get_cta_state($user_id, $post_id)    // CTA tekst za sve UI pozicije

AI ne zna da ove funkcije postoje osim ako mu ne kažete. Lista pomoćnih funkcija u CLAUDE.md sprečava ponavljanje implementacije koja već postoji.

Piši dokumentaciju prvo, implementiraj posle

Zvuči naopako. Ali radi.

Kada napišete doc pre implementacije:

  • Morate da razmislite o arhitekturi
  • Morate da razmislite o graničnim slučajevima
  • Morate da razmislite o API-ju

Doc postaje specifikacija. AI prati specifikaciju bolje nego improvizaciju.

Primer: Membership sistem

  1. Napisao doc: 6 tabela, model prava pristupa, potrošnja kvote
  2. AI pregledao: "Šta ako nastane konflikt istovremenih zahteva?"
  3. Ažuriran doc: Atomski SQL za potrošnju
  4. Implementacija: Pratili doc
  5. Finalni doc: Dodate pomoćne funkcije, primeri

48 markdown fajlova je nastalo ovim procesom. Upload pipeline (750+ linija), membership sistem (700+ linija), infrastruktura (470+ linija), institucije (730+ linija)…

Auto-memorija: Claude uči sam

Tokom rada, Claude beleži obrasce koje primeti:

  • Komande za build i testiranje
  • Rešenja za česte greške
  • Arhitekturalne napomene
  • Vaše preferencije

Ovo se čuva u ~/.claude/projects/<projekat>/memory/. Indeks fajl MEMORY.md (prvih 200 linija) se učitava na početku svake sesije. Možete i ručno dodavati beleške komandom /memory.

Za naš projekat, auto-memorija pamti: verziju baze (migracija 11), da webhook handler mora biti idempotentan, da E2E testovi zahtevaju e2e- prefiks u email adresama.

Pattern koji radi za bilo koji AI alat

CLAUDE.md je Claude Code koncept. Ali princip važi za sve AI alate:

Cursor: .cursorrules fajl sa sličnom strukturom
GitHub Copilot: Instrukcije u .github/copilot-instructions.md
Windsurf: .windsurfrules fajl

Suština je ista: dajte AI-ju strukturiran kontekst o projektu. Bez konteksta, AI generiše generički kod. Sa kontekstom, AI generiše kod koji se uklapa u VAŠ projekat.

Praktični saveti

1. Držite CLAUDE.md ažurnim. Zastareo doc je gori od nikakvog.

2. CLAUDE.md je indeks, ne enciklopedija. Linkujte na detaljne dokove umesto da sve trpate u jedan fajl.

3. Budite eksplicitni o konvencijama. "Koristi pnpm, ne npm" je korisnije nego "koristi pravi alat."

4. Kažite šta NE raditi. Ponekad je važnije zabraniti anti-pattern nego objasniti ispravan pristup.

5. Koristite .claude/rules/ za fokusirana pravila. Jedno pravilo po fajlu, opisna imena (testiranje.md, api-dizajn.md).

Dokumentacija koju pišete za AI postaje dokumentacija koja pomaže i vama.

48 markdown fajlova nisu nastali kao poseban zadatak dokumentacije. Nastali su kao kontekst za AI koji se pokazao koristan za sve — uključujući budućeg sebe koji se vraća na projekat posle pauze.

Šest nivoa memorije znači da svaki nivo radi ono što radi najbolje: organizacija postavlja široka pravila, tim deli konvencije projekta, vi dodajete lične preferencije, a Claude sam uči obrasce.