AGENTS.md: Ikkonfigura l-Istruzzjonijiet tar-Repożitorju Tiegħek
F'din il-paġna
Lezzjoni aġġornata fit-3 ta’ Novembru 2026 abbażi tal-paġna Custom instructions with AGENTS.md: Codex jaqra biss fajls
AGENTS.mdli jinsabu bejn l-għerq tal-proġett u d-direttorju tax-xogħol kurrenti (flimkien mal-fajl globali f’~/.codex). Fajl f’sottodirettorju barra minn dan il-mogħdija ma jitloadjax, kuntrarjament għal dak li kien jimplika l-verżjoni preċedenti. Sors: AGENTS.md.
Tmexxija tal-Fajl ta’ Konfigurazzjoni ta’ Codex
Skoprejt AGENTS.md fil-Lezzjoni 3. Hawnhekk, nieħdu ħarsa lejn mudelli avvanzati—id-differenza bejn fajl dekorattiv (tliet linji miktuba meta tibda u mbagħad minsija) u wieħed li verament imexxi l-imġiba tal-aġent fuq proġett ħaj.
Il-Ġerarkija ta’ AGENTS.md
Codex jaqra dawn il-fajls b’mod ġerarkiku, mill-ġenerali għall-ispeċifiku: l-ewwel il-fajl globali fil-folder ta’ Codex tiegħek (~/.codex/AGENTS.md, jew AGENTS.override.md jekk jeżisti), imbagħad, billi tibda mill-għerq tal-proġett, il-fajls fid-direttorji li tgħaddi minnhom sa tasal għad-direttorju tax-xogħol kurrenti. Fuq proġett strutturat, is-siġra tidher hekk:
mon-projet/
AGENTS.md → Regoli globali (prijorità baxxa)
src/
AGENTS.md → Regoli għall-kodiċi sors kollu
api/
AGENTS.md → Regoli speċifiċi għall-APIs
routes/
AGENTS.md → Regoli għar-rotot
components/
AGENTS.md → Regoli għall-komponenti React
tests/
AGENTS.md → Regoli għat-testijiet
Ir-regoli jakkomulaw: Codex jgħaqqad il-fajls mill-għerq ‘l isfel sad-direttorju kurrenti, u dawk l-eqreb lejn dak id-direttorju, li jinqraw l-aħħar, jissostitwixxu l-istruzzjonijiet ġenerali. Hemm punt li faċilment jinftiehem ħażin: biss id-direttorji fuq il-mogħdija bejn l-għerq u d-direttorju kurrenti jinqraw. Jekk il-fajl tal-għerq tiegħek jipprojbixxi any filwaqt li tests/AGENTS.md jippermetti asserzjonijiet iktar laxki fil-mocks, dik it-tolleranza tapplika biss meta Codex ikun qed jaħdem minn tests/ jew wieħed mis-sottodirettorji tiegħu; jekk jitnieda mill-għerq, ma jaqrahx tests/AGENTS.md. Ir-reviżjoni tal-kodiċi ta’ GitHub taħdem b’mod differenti: Codex ifittex ir-repożitorju kollu għal fajls AGENTS.md hemmhekk u japplika r-regoli ta’ reviżjoni (## Code Review Rules) mill-fajl l-eqreb lejn il-kodiċi kkonċernat. Il-konkatenazzjoni tieqaf f’32 KiB b’mod default (project_doc_max_bytes): fajl twil wisq jiġi maqtugħ.
It-Taqsamiet Li Jagħmlu l-Fajl
Il-kuntest jiġi l-ewwel, għax jifforma kull deċiżjoni li jmiss. Applikazzjoni SaaS soġġetta għall-GDPR (Regolament Ġenerali dwar il-Protezzjoni tad-Data) ma tiġix ikkodifikata bħal għodda interna għal ħames persuni:
## Context
SaaS invoice management application for French SMEs.
GDPR compliance mandatory. Data hosted in France (OVH).
Stack: Astro 6, React, Strict TypeScript, Prisma, PostgreSQL.
Authentication: Better Auth with server sessions.
Meta jkun jaf li tittratta data soġġetta għall-GDPR, Codex iżid il-protezzjonijiet mistennija mingħajr ma jkollok tispeċifikahom f’kull talba. Imbagħad jiġu l-konvenzjonijiet, li jwieġbu mistoqsija waħda: kif tidher il-kodiċi korrett hawnhekk?
## Conventions
- Strict TypeScript (no any, no implicit any)
- Functional React components only
- Naming: kebab-case files, PascalCase components,
camelCase variables
- Imports: @/ for path aliases
- Validation: Zod for all user inputs
- Errors: custom error classes in src/lib/errors.ts
- Logging: use src/lib/logger.ts (no console.log)
It-taqsima tal-kumandi hija l-aktar waħda li titħalla barra, u n-nuqqas tagħha jiswi ħafna: mingħajr dawn il-kumandi, Codex ma jistax jivverifika x-xogħol tiegħu stess u jirritorna kodiċi li qatt ma eżegwixxa jew ittestja.
## Commands
- `npm run dev` — Development server (port 4321)
- `npm run build` — Production build
- `npm run test` — Vitest tests
- `npm run test:e2e` — Playwright tests
- `npm run lint` — ESLint + Prettier
- `npm run db:migrate` — Prisma migrations
- `npm run db:seed` — Database seed
Ir-regoli stretti jiffurmaw il-guardrail. Meta jkunu fformulati bħala “QATT” u “DEJEM”, jipprevjenu żbalji li jiswulek filgħaxja sħiħa biex issolvihom: migrazzjoni ta’ Prisma mħassra li jkollok terġa’ tibni mill-produzzjoni, sigriet imcommitjat li jeħtieġ li jiġi rrevokat, jew innerHTML li jidħol f’komponent u jiftaħ vulnerabbiltà XSS.
## Strict Rules (NEVER break these)
- NEVER modify the Prisma schema without creating a migration
- NEVER store secrets in code (use .env)
- NEVER use innerHTML (XSS risk)
- NEVER delete an existing Prisma migration
- NEVER expose internal IDs in public URLs
- ALWAYS validate user inputs with Zod
- ALWAYS use Prisma transactions for multi-table operations
Fl-aħħar nett, l-arkitettura tiddeskrivi l-fluss permess bejn is-saffi. Mingħajrha, Codex jipproduċi kodiċi li jaħdem iżda jaqbeż l-istruttura tiegħek—rotta li tikkonsulta Prisma direttament, pereżempju, għax kienet l-iqsar mogħdija.
## Architecture
Layers:
1. Routes (src/pages/) → receive requests
2. Services (src/services/) → business logic
3. Repositories (src/repositories/) → data access
Rule: Routes MUST NOT access Prisma directly.
Everything goes through a service, which goes through a repository.
Ma’ dan, proġett b’proġett, jiżdiedu istruzzjonijiet speċifiċi għal kull teknoloġija użata:
## React
- Prefer Server Components by default
- Client Components only when necessary (interactivity)
- No useEffect for data fetching (use Server Actions)
- Local state with useState, global state with Zustand
## Prisma
- Relations: always include required fields explicitly
- Pagination: use cursor-based, not offset-based
- Soft delete: use deletedAt instead of DELETE
Żewġ Mudelli Li Jipprevjenu Sorpriżi
Id-dikjarazzjoni tal-varjabbli tal-ambjent mistennija tipprevjeni lil Codex milli jinventa ismijiet ta’ ċwievet meta jikteb skript, jew li bil-mod jiġi rreġistrat valur sensittiv f’traċċa ta’ debug:
## Required Environment Variables
- DATABASE_URL — PostgreSQL connection URL
- AUTH_SECRET — Secret for Better Auth (min 32 chars)
- SMTP_HOST — SMTP server for emails
- STRIPE_SECRET_KEY — Stripe API key (never log)
Li tsemmi l-libreriji preferuti tiegħek, u speċjalment dawk li tirrifjuta, issolvi fastidju rikorrenti: l-aġent jinstalla dipendenza li hija perfetta f’liha nnifisha, iżda li t-tim tiegħek irrifjuta sentejn ilu wara esperjenza ħażina.
## Dependencies
If you need:
- Validation → Zod (NOT Joi, NOT Yup)
- Dates → date-fns (NOT moment, NOT dayjs)
- HTTP client → ofetch (NOT axios)
- Tests → Vitest (NOT Jest)
- E2E → Playwright (NOT Cypress)
Li Żżomm il-Fajl Ħaj
AGENTS.md jevolvi mal-kodiċi tiegħek, eżatt bħal test jew README. Aġġornah malli tadotta konvenzjoni ġdida, tbiddel libreriji jew frameworks, u speċjalment malli tidentifika żball rikorrenti ta’ Codex: dak l-aħħar każ dejjem jindika istruzzjoni nieqsa aktar milli falliment tal-mudell. Hemm trigger irba’, iktar sottili, li jiswa li tosservah—meta żviluppatur ġdid jagħmel mistoqsija li AGENTS.md kellha twieġeb, dik it-tweġiba tappartjeni fil-fajl.
Punti Ewlenin
- Il-ġerarkija ta’
AGENTS.mdtippermetti istruzzjonijiet dejjem aktar speċifiċi - Il-kumandi huma kritiċi biex Codex jivverifika x-xogħol tiegħu
- Ir-regoli QATT (NEVER) huma l-aktar importanti biex tevita żbalji
- Iddokumenta d-dipendenzi preferuti biex tevita għażliet ħżiena
- Żomm
AGENTS.mdbħala kodiċi ħaj