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

Ipprepara l-ambjent tiegħek u AGENTS.md

Lezzjoni 3 / 20 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Ipprepara l-proġett tiegħek għal Codex
  2. Pass 1: L-aċċess tiegħek għal Codex
  3. Pass 2: Installa l-estensjoni tal-editur
  4. Pass 3: Installa l-CLI
  5. Il-fajl AGENTS.md—il-gwida tal-proġett tiegħek
  6. L-aħjar prattiki għal AGENTS.md
  7. Punti Ewlenin

Aġġornat fit-3 ta’ Novembru, 2026 abbażi tad-dokumentazzjoni ta’ Codex (Codex CLI, Authentication, Codex IDE extension, Custom instructions with AGENTS.md): il-pakkett @openai/codex-cli u l-kmand codex auth login ma jeżistux (uża npm install -g @openai/codex u codex login); l-identifikatur tal-estensjoni huwa openai.chatgpt; l-indirizz codex.openai.com u l-pjanijiet “Team, Enterprise, jew API” ġew sostitwiti b’metodi ta’ aċċess attwali; u l-ordni ta’ qari ta’ AGENTS.md ġiet iċċarata (għerq tal-proġett → directory kurrenti). Sorsi: Codex CLI · Authentication · AGENTS.md · Pricing.

Ipprepara l-proġett tiegħek għal Codex

Qabel l-ewwel kompitu tiegħek, iridu jkunu fis-seħħ żewġ affarijiet: l-aċċess tiegħek għal Codex—il-kont u l-konnessjoni ma’ GitHub tiegħek—u l-proġett innifsu, definit permezz tal-fajl AGENTS.md li se jiggwida l-aġent. L-ewwel parti tieħu madwar 15-il minuta u hija setup li tagħmel darba biss. It-tieni parti tiddetermina l-kwalità ta’ kull ma tikseb minn Codex, u tissepara t-timijiet sodisfatti minn Codex minn dawk li jsibuh deludenti.

Pass 1: L-aċċess tiegħek għal Codex

Tista’ tuża Codex b’kont ChatGPT jew bi ċavetta API. Il-pjanijiet Free u Go jipprovdu aċċess, skont id-dispjegament attwali, għal GPT-6 Luna fl-app tad-desktop. Mill-pjan Plus ‘il quddiem, Codex huwa disponibbli fuq il-web, fil-CLI, fl-estensjoni tal-editur, u fuq iOS, b’integrazzjonijiet cloud bħar-reviżjoni awtomatizzata tal-kodiċi. Ċavetta API taħdem għall-awtomazzjoni f’ambjenti kondiviżi bħal CI, bl-użu tal-CLI, SDK jew estensjoni—għalkemm xi karatteristiċi jistgħu ma jkunux disponibbli. Id-dettalji u l-limiti tal-użu huma fuq il-paġna tal-prezzijiet ta’ Codex.

Biex taħdem fuq il-cloud fir-repożitorji tiegħek, ikkonnettja ma’ GitHub meta toħloq l-ewwel ambjent ta’ Codex Cloud tiegħek (Lezzjoni 2). Meta tagħti permessi, żommhom minimi: illimita l-aċċess biss għar-repożitorji li għandek bżonn verament.

Pass 2: Installa l-estensjoni tal-editur

F’VS Code u d-derivattivi tiegħu (Cursor, Windsurf), installa l-estensjoni Codex mis-suq—l-identifikatur tagħha huwa openai.chatgpt:

code --install-extension openai.chatgpt

Imbagħad iftaħ Codex permezz tal-ikona tiegħu, jew permezz tal-paletta tal-kmandi b’Codex: Open Codex Sidebar, u ddaħħal il-login. Xcode u JetBrains IDEs għandhom l-integrazzjonijiet tagħhom stess: f’JetBrains, iftaħ AI Chat u agħżel Codex.

Pass 3: Installa l-CLI

# Installazzjoni (macOS u Linux), jew npm install -g @openai/codex
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Ivvverifika l-installazzjoni
codex --version

# Daħħal il-login (browser), jew iċċekkja l-istatus tal-konnessjoni
codex login
codex login status

codex login jiftaħ il-fluss tal-login fil-browser tiegħek. Għal ċavetta API, għaddiha permezz tal-input standard (printenv OPENAI_API_KEY | codex login --with-api-key). Codex jikkaxxja l-kredenzjali jew f’fajl test ċar, ~/.codex/auth.json, jew fil-keychain tas-sistema, skont l-impostazzjoni cli_auth_credentials_store (file, keyring, auto, jew ephemeral). Jekk jintuża l-fajl, ittrattah bħal password: fih tokens ta’ aċċess, allura qatt ma tikkumittjah. Il-CLI u l-estensjoni jaqsmu din il-cache.

Il-fajl AGENTS.md—il-gwida tal-proġett tiegħek

AGENTS.md huwa ċentrali biex tuża Codex b’mod effettiv. Huwa fajl Markdown sempliċi mqiegħed fl-għerq tar-repożitorju tiegħek li jiġbor flimkien struzzjonijiet, konvenzjonijiet u kmandi speċifiċi għall-proġett tiegħek. Meta Codex jikklowinja r-repo, jaqra dan il-fajl l-ewwel: ħsiebhu bħala onboarding awtomatiku għall-aġent, eżattament dak li tispjega oralment lil membru ġdid tat-tim.

L-impatt huwa immedjat. Mingħajr AGENTS.md, jekk titlob test tal-unità fuq proġett li juża Vitest, hemm ċans kbir li Codex jagħtik Jest, għax dik hija l-għażla l-aktar komuni fl-ekosistema. Linja waħda ta’ konvenzjoni biżżejjed biex tikseb Vitest sew mill-ewwel darba, u tiffranka lilek innifsek milli tagħmel l-istess korrezzjoni mitt darba. Hawnhekk hija l-istruttura ta’ fajl bażiku għal proġett ta’ ġestjoni ta’ fatturi SaaS.

# AGENTS.md

## Kuntest tal-proġett
Applikazzjoni ta' ġestjoni ta' fatturi SaaS.
Stack: Next.js 15, TypeScript, Prisma, PostgreSQL.

## Konvenzjonijiet tal-kodiċi
- Uża komponenti funzjonali ta' React (l-ebda klassi)
- Semmi l-fajls fil-kebab-case
| Tipi ta' TypeScript f'fajls separati .types.ts
- Testijiet b'Vitest, fajls .test.ts ħdejn il-kodiċi

## Kmandi utli
- `npm run dev` — server ta' żvilupp
- `npm run test` — ġġib it-testijiet
- `npm run lint` — iċċekkja l-linting
- `npm run build` — build tal-produzzjoni

## Struttura tal-proġett
    src/
      app/          → Paġni ta' Next.js (App Router)
      components/   → Komponenti ta' React riutilizzabbli
      lib/          → Loġika tan-negozju u utilitajiet
      prisma/       → Skema tad-DB u migrazzjonijiet

## Regoli stretti
- QATT ma timmodifika l-iskema ta' Prisma mingħajr migrazzjoni
- QATT ma tikkumittja fajls .env
- Dejjem uża Server Actions għall-mutazzjonijiet

Kif Codex isib il-fajls AGENTS.md

Fajl wieħed fl-għerq malajr isir ġeneriku wisq. Codex jippermettilek tpoġġi struzzjonijiet f’ordni preċiża li għandek bżonn tkun taf:

  1. Livell globali: Fil-folder ta’ Codex tiegħek (~/.codex, sakemm CODEX_HOME ma jissostitwixxihx), Codex jaqra AGENTS.override.md jekk jeżisti, inkella AGENTS.md.
  2. Livell tal-proġett: Billi jibda mill-għerq tal-proġett (normalment l-għerq ta’ Git), Codex jinżel sal-directory kurrenti u jaqra, f’kull folder li jgħaddi minnu, AGENTS.override.md jew, fin-nuqqas ta’ dan, AGENTS.md.
  3. Għaqda: Il-fajls jiġu kkatinati mill-għerq ‘l isfel sad-directory kurrenti; dawk l-eqreb tad-directory kurrenti jiġu l-aħħar u għalhekk jissostitwixxu struzzjonijiet aktar ġenerali.
my-project/
  AGENTS.md              → Struzzjonijiet tal-proġett
  src/
    api/
      AGENTS.md          → "Ir-rotot tal-API jużaw Zod għall-validazzjoni"

Konsegwenza prattika: src/api/AGENTS.md jinqara biss jekk Codex ikun qed jaħdem minn src/api jew waħda mis-subdirectories tiegħu, mhux meta jitnieda mill-għerq. Fajls vojta jiġu injorati, u l-katinazzjoni tieqaf f’32 KiB b’mod default (project_doc_max_bytes). Jekk ir-repo tiegħek diġà tuża isem ieħor, bħal TEAM_GUIDE.md, żidha ma’ project_doc_fallback_filenames f’~/.codex/config.toml.

Biex tivverifika x’ħamel tagħbija Codex fil-fatt, staqsi biss: codex --ask-for-approval never "Summarize the current instructions.". Codex jerġa’ jibni l-katina tal-istruzzjonijiet f’kull tnedija: jekk ikollok dubju, erġa’ ibdih fid-directory korretta.

L-aħjar prattiki għal AGENTS.md

Il-prinċipju gwida huwa l-espliċitezza. “Uża Vitest, mhux Jest” huwa aħjar minn “Uża l-qafas tat-testijiet tagħna”, li jassumi għarfien li l-aġent m’għandux. Dejjem inkludi l-kmandi: mingħajrhom, Codex ma jkunx jaf kif iħaddem it-testijiet, il-linter jew il-build tiegħek, u se jwassal kodiċi li ma setax jivverifika. Iddokumenta l-istruttura bħala siġra tad-direttorji, li tipprevjenih milli jesplora blind u joħloq fajls fil-post żbaljat.

Fl-aħħar nett, elenka l-projbizzjonijiet. Ir-regoli miktuba bħala “QATT” huma l-aktar kost-effettivi fil-fajl, għax jimblokkaw żbalji għoljin li huma diffiċli biex tirranġahom: li tikkumittja fajl .env, li timmodifika skema mingħajr migrazzjoni. L-aktar dixxiplina diffiċli hija li żżomm il-fajl aġġornat. AGENTS.md li jiddeskrivi l-proġett tas-sena l-oħra jiggwida lil Codex b’mod attiv lejn konvenzjonijiet abbandunati—ħafna agħar milli ma jkollok l-ebda fajl, peress li l-iżball imbagħad isir sistematiku.

Punti Ewlenin

  • Is-setup inizjali jeħtieġ kont OpenAI u konnessjoni ma’ GitHub
  • L-estensjoni tal-IDE u l-CLI jinstallaw f’ftit minuti
  • AGENTS.md huwa l-aktar fajl importanti għal użu effettiv ta’ Codex
  • Fih konvenzjonijiet, kmandi u regoli speċifiċi għall-proġett tiegħek
  • Fajls AGENTS.md fis-subdirectories jippermettu struzzjonijiet kuntestwali