AGENTS.md: Configurați instrucțiunile repository-ului
Pe această pagină
Lecție actualizată la 3 noiembrie 2026 pe baza paginii Custom instructions with AGENTS.md: Codex citește doar fișierele
AGENTS.mdsituate între rădăcina proiectului și directorul de lucru curent (plus fișierul global de la~/.codex). Un fișier dintr-un subdirector aflat în afara acestei căi nu este încărcat, contrar implicațiilor versiunii anterioare. Sursă: AGENTS.md.
Stăpânirea fișierului de configurare Codex
Ați descoperit AGENTS.md în Lecția 3. Aici, aprofundăm modelele avansate – diferența dintre un fișier decorativ (trei linii scrise la început și uitate) și unul care ghidează efectiv comportamentul agentului într-un proiect activ.
Ierarhia AGENTS.md
Codex citește aceste fișiere ierarhic, de la general la specific: mai întâi fișierul global din folderul Codex (~/.codex/AGENTS.md, sau AGENTS.override.md dacă există), apoi, începând de la rădăcina proiectului, fișierele din directoarele parcurse până la directorul de lucru curent. Pe un proiect structurat, arborele arată astfel:
mon-projet/
AGENTS.md → Reguli globale (prioritate mică)
src/
AGENTS.md → Reguli pentru tot codul sursă
api/
AGENTS.md → Reguli specifice API-urilor
routes/
AGENTS.md → Reguli pentru rute
components/
AGENTS.md → Reguli pentru componente React
tests/
AGENTS.md → Reguli pentru teste
Regulile se acumulează: Codex concatenează fișierele de la rădăcină până la directorul curent, iar cele mai apropiate de acel director, citite la final, suprascriu instrucțiunile generale. Un aspect este adesea neînțeles: sunt citite doar directoarele de pe calea dintre rădăcină și directorul curent. Dacă fișierul rădăcină interzice any, în timp ce tests/AGENTS.md permite afirmații mai relaxate în mock-uri, această toleranță se aplică doar când Codex lucrează din tests/ sau unul dintre subdirectoarele sale; dacă este lansat din rădăcină, nu va citi tests/AGENTS.md. Pentru o regulă care trebuie să se aplice peste tot, plasați-o la rădăcină, chiar dacă trebuie să numiți excepția acolo. Revizuirea codului GitHub funcționează diferit: Codex caută în întregul repository fișiere AGENTS.md și aplică regulile de revizuire (## Code Review Rules) din fișierul cel mai apropiat de codul în cauză. Concatenarea se oprește la 32 KiB implicit (project_doc_max_bytes): un fișier prea lung va fi trunchiat.
Secțiunile care definesc fișierul
Contextul vine primul, deoarece modelează fiecare decizie ulterioară. O aplicație SaaS supusă GDPR (Regulamentul General privind Protecția Datelor) nu este codată la fel ca un instrument intern pentru cinci persoane:
## Context
Aplicație SaaS de gestionare a facturilor pentru IMM-uri franceze.
Conformitate GDPR obligatorie. Date găzduite în Franța (OVH).
Stack: Astro 6, React, TypeScript Strict, Prisma, PostgreSQL.
Autentificare: Better Auth cu sesiuni pe server.
Știind că gestionează date supuse GDPR, Codex va adăuga protecțiile așteptate fără a fi nevoie să le specificați în fiecare cerere. Urmează convențiile, care răspund la o întrebare: cum arată codul corect aici?
## Conventions
- TypeScript Strict (fără any, fără implicit any)
- Doar componente React funcționale
- Denumiri: fișiere kebab-case, componente PascalCase,
variabile camelCase
- Importuri: @/ pentru aliasuri de cale
- Validare: Zod pentru toate inputurile utilizatorului
- Erori: clase de eroare personalizate în src/lib/errors.ts
- Logging: utilizați src/lib/logger.ts (fără console.log)
Secțiunea de comenzi este cea mai adesea omisă, iar absența ei este costisitoare: fără aceste comenzi, Codex nu își poate verifica propria muncă și returnează cod pe care nu l-a executat sau testat niciodată.
## Commands
- `npm run dev` — Server de dezvoltare (port 4321)
- `npm run build` — Build de producție
- `npm run test` — Teste Vitest
- `npm run test:e2e` — Teste Playwright
- `npm run lint` — ESLint + Prettier
- `npm run db:migrate` — Migrări Prisma
- `npm run db:seed` — Seed baza de date
Regulile stricte formează balustrada de siguranță. Formulate ca „NICIODATĂ“ și „ÎNTOTDEAUNA“, ele previn erorile care costă o seară întreagă de reparat: o migrare Prisma ștearsă pe care trebuie să o reconstruiți din producție, un secret comitat care necesită revocare sau un innerHTML strecurat într-o componentă care deschide o vulnerabilitate XSS.
## Strict Rules (NEVER break these)
- NICIODATĂ nu modificați schema Prisma fără a crea o migrare
- NICIODATĂ nu stocați secrete în cod (folosiți .env)
- NICIODATĂ nu folosiți innerHTML (risc XSS)
- NICIODATĂ nu ștergeți o migrare Prisma existentă
- NICIODATĂ nu expuneți ID-uri interne în URL-uri publice
- ÎNTOTDEAUNA validați inputurile utilizatorului cu Zod
- ÎNTOTDEAUNA folosiți tranzacții Prisma pentru operațiuni multi-tabel
În final, arhitectura descrie fluxul permis între straturi. Fără ea, Codex produce cod care funcționează, dar care scurtcircuitează structura dumneavoastră – o rută care interoghează Prisma direct, de exemplu, pentru că era calea cea mai scurtă.
## Architecture
Straturi:
1. Rute (src/pages/) → primesc cererile
2. Servicii (src/services/) → logica de afaceri
3. Repository-uri (src/repositories/) → acces la date
Regulă: Rutele NU TREBUIE să acceseze Prisma direct.
Totul trece printr-un serviciu, care trece printr-un repository.
La acestea se adaugă, proiect cu proiect, instrucțiuni specifice fiecărei tehnologii utilizate:
## React
- Preferați Server Components implicit
- Client Components doar când este necesar (interactivitate)
- Fără useEffect pentru preluarea datelor (folosiți Server Actions)
- Stare locală cu useState, stare globală cu Zustand
## Prisma
- Relații: includeți întotdeauna câmpurile obligatorii explicit
- Paginare: folosiți cursor-based, nu offset-based
- Ștergere soft: folosiți deletedAt în loc de DELETE
Două modele care previn surprizele
Declararea variabilelor de mediu așteptate împiedică Codex să inventeze nume de chei atunci când scrie un script sau să logheze accidental o valoare sensibilă într-o urmă de depanare:
## Required Environment Variables
- DATABASE_URL — URL de conexiune PostgreSQL
- AUTH_SECRET — Secret pentru Better Auth (min 32 caractere)
- SMTP_HOST — Server SMTP pentru emailuri
- STRIPE_SECRET_KEY — Cheie API Stripe (nu se loghează niciodată)
Denumirea bibliotecilor preferate și, în special, a celor pe care le refuzați, rezolvă o problemă recurentă: agentul instalează o dependență perfect validă în sine, dar pe care echipa dumneavoastră a respins-o acum doi ani după o experiență neplăcută.
## Dependencies
Dacă aveți nevoie de:
- Validare → Zod (NU Joi, NU Yup)
- Date → date-fns (NU moment, NU dayjs)
- Client HTTP → ofetch (NU axios)
- Teste → Vitest (NU Jest)
- E2E → Playwright (NU Cypress)
Menținerea fișierului activ
AGENTS.md evoluează odată cu codul dumneavoastră, la fel ca un test sau un README. Actualizați-l imediat ce adoptați o nouă convenție, schimbați biblioteci sau framework-uri și, în special, imediat ce identificați o eroare recurentă a Codex: acest ultim caz semnalează întotdeauna o instrucțiune lipsă, nu o defecțiune a modelului. Un al patrulea declanșator, mai subtil, merită urmărit – când un nou dezvoltator pune o întrebare la care AGENTS.md ar fi trebuit să răspundă, acel răspuns aparține fișierului.
Puncte cheie
- Ierarhia
AGENTS.mdpermite instrucțiuni din ce în ce mai specifice - Comenzile sunt critice pentru ca Codex să își verifice munca
- Regulile NICIODATĂ sunt cele mai importante pentru evitarea erorilor
- Documentați dependențele preferate pentru a preveni alegerile greșite
- Mențineți
AGENTS.mdca pe un cod viu