Fișierul CLAUDE.md este creierul de memorie persistentă al fiecărui proiect gestionat cu Claude Code. Dacă este redactat superficial, agentul va pune întrebări repetitive, va folosi comenzi greșite de testare sau va genera cod care încalcă arhitectura echipei.
O structură avansată de CLAUDE.md funcționează ca un manual tehnic de onboarding comprimat în mai puțin de 200 de linii: include comenzile esențiale de build/test (cu timpi estimați), standardele stricte de formatare și stil, convențiile de denumire a fișierelor și o hartă a modulelor critice.
În monorepositorii sau proiecte cu mai multe sub-servicii, Claude Code recunoaște fișiere CLAUDE.md imbricate în directoare secundare (de exemplu `client/CLAUDE.md` și `server/CLAUDE.md`), încărcând dinamic regulile specifice doar atunci când agentul lucrează în acele module.
Sintaxă, opțiuni și concepte cheie
| Opțiune / Concept | Descriere practică |
|---|---|
Comenzi Frecvente |
Secțiunea obligatorie cu sintaxa exactă pentru pornire dev, rulare teste unitare, lint și build. |
Standarde de Arhitectură |
Reguli categorice despre ce tehnologii sunt permise și ce biblioteci sunt strict interzise. |
Ierarhie Imbricată |
Moștenirea regulilor din fișierul rădăcină combinată cu directivele specifice din subdirectoare. |
Optimizare de Tokeni |
Scrierea instrucțiunilor în format bullet-point concis, fără paragrafe lungi explicative inutile. |
Exemple practice de terminal și cod
Exemplul 1: Model complet de fișier CLAUDE.md pentru un proiect modern full-stack
Structura recomandată pentru proiecte profesionale.
# CLAUDE.md - Ghidul de Proiect pentru Agenți AI
## Comenzi de Dezvoltare
- Instalare: `pnpm install`
- Pornire server dev: `pnpm dev` (port 3000)
- Rulare teste: `pnpm test:unit` (doar fișierele modificate: `pnpm test:unit --watch`)
- Verificare TypeScript: `pnpm typecheck`
## Reguli Stricte de Cod
- Nu folosi niciodată tipul `any` în TypeScript; folosește `unknown` cu type-guards.
- Toate componentele UI noi trebuie create în `src/components/ui/` cu Tailwind CSS.
- Nu rula comenzi de migrare de bază de date fără flagul `--dry-run` inițial.
- Răspunde întotdeauna în limba română la cerințele de explicații tehnice.
## Arhitectură & Structură
- `src/api/`: Endpoint-uri REST securizate cu middleware-ul `verifyAuth`
- `src/services/`: Logica de business pură, fără acces direct la `req/res`Rezultat & Impact
Agentul respectă din primul moment regulile de echipă fără a necesita re-instruire la fiecare sesiune.Greșeli frecvente și bune practici
- Aglomerarea fișierului CLAUDE.md cu zeci de pagini de documentație exhaustivă, ceea ce consumă o mare parte din context la fiecare rulare.
- Păstrarea comenzilor învechite în CLAUDE.md după actualizarea versiunilor de pachete (ex. npm vs. pnpm).