Ipprepara l-ambjent tiegħek u AGENTS.md
F'din il-paġna
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-cliu l-kmandcodex auth loginma jeżistux (użanpm install -g @openai/codexucodex login); l-identifikatur tal-estensjoni huwaopenai.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:
- Livell globali: Fil-folder ta’ Codex tiegħek (
~/.codex, sakemmCODEX_HOMEma jissostitwixxihx), Codex jaqraAGENTS.override.mdjekk jeżisti, inkellaAGENTS.md. - 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.mdjew, fin-nuqqas ta’ dan,AGENTS.md. - 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