Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

AGENTS.md: Ikkonfigura l-Istruzzjonijiet tar-Repożitorju Tiegħek

Lezzjoni 15 / 20 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Tmexxija tal-Fajl ta’ Konfigurazzjoni ta’ Codex
  2. Il-Ġerarkija ta’ AGENTS.md
  3. It-Taqsamiet Li Jagħmlu l-Fajl
  4. Żewġ Mudelli Li Jipprevjenu Sorpriżi
  5. Li Żżomm il-Fajl Ħaj
  6. Punti Ewlenin

Lezzjoni aġġornata fit-3 ta’ Novembru 2026 abbażi tal-paġna Custom instructions with AGENTS.md: Codex jaqra biss fajls AGENTS.md li 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.md tippermetti 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.md bħala kodiċi ħaj