Priprava okolja in datoteka AGENTS.md
Na tej strani
Posodobljeno 3. novembra 2026 na podlagi dokumentacije Codex (Codex CLI, Avtentikacija, Razširitev Codex IDE, Prilagojena navodila z AGENTS.md): paket
@openai/codex-cliin ukazcodex auth loginne obstajata (uporabinpm install -g @openai/codexincodex login); identifikator razširitve jeopenai.chatgpt; naslov codex.openai.com in načrti “Team, Enterprise ali API” so nadomeščeni s trenutnimi načini dostopa; vrstni red branja AGENTS.md je pojasnjen (koren projekta → trenutni imenik). Viri: Codex CLI · Avtentikacija · AGENTS.md · Cenik.
Pripravi svoj projekt za Codex
Pred prvo nalogo morata biti na voljo dve stvari: tvoj dostop do Codexa – tvoji račun in povezava z GitHubom – ter sam projekt, opredeljen prek datoteke AGENTS.md, ki bo usmerjala agenta. Prvi del traja približno 15 minut in ga opraviš enkrat. Drugi del določa kakovost vsega, kar dobiš od Codexa, in ločuje ekipe, ki so z Codexom zadovoljne, od tistih, ki ga razočara.
1. korak: Tvoj dostop do Codexa
Codex lahko uporabljaš z računom ChatGPT ali ključem API. Načrta Free in Go omogočata dostop, odvisno od trenutne namestitve, do modela GPT-6 Luna v namizni aplikaciji. Od načrta Plus naprej je Codex na voljo na spletu, v CLI, v razširitvi za urejevalnik in na iOS-u, z integracijami v oblaku, kot je samodejni pregled kode. Ključ API deluje za avtomatizacijo v skupnih okoljih, kot je CI, z uporabo CLI, SDK ali razširitve – čeprav nekatere funkcije morda ne bodo na voljo. Podrobnosti in omejitve uporabe so na strani s cenikom Codex.
Za delo v oblaku na svojih repozitorijih poveži GitHub, ko ustvariš svoje prvo okolje Codex Cloud (2. lekcija). Ko dodeljuješ dovoljenja, bodi previden: omeji dostop le na repozitorije, ki jih dejansko potrebuješ.
2. korak: Namesti razširitev za urejevalnik
V VS Code in njegovih različicah (Cursor, Windsurf) namesti razširitev Codex iz tržnice – njen identifikator je openai.chatgpt:
code --install-extension openai.chatgpt
Nato odpri Codex prek njegove ikone ali prek palete ukazov z Codex: Open Codex Sidebar in se prijavi. Xcode in JetBrains IDE imata lastni integraciji: v JetBrains odpri AI Chat in izberi Codex.
3. korak: Namesti CLI
# Namestitev (macOS in Linux), ali npm install -g @openai/codex
curl -fsSL https://chatgpt.com/codex/install.sh | sh
# Preveri namestitev
codex --version
# Prijava (brskalnik) ali preveri stanje povezave
codex login
codex login status
codex login odpre postopek prijave v tvojem brskalniku. Za ključ API ga posreduj prek standardnega vhoda (printenv OPENAI_API_KEY | codex login --with-api-key). Codex predpomni poverilnice bodisi v besedilno datoteko ~/.codex/auth.json bodisi v sistemski ključavnik, odvisno od nastavitve cli_auth_credentials_store (file, keyring, auto ali ephemeral). Če se uporablja datoteka, jo obravnavaj kot geslo: vsebuje žetone za dostop, zato je nikoli ne dodaj v repozitorij. CLI in razširitev si delita ta predpomnilnik.
Datoteka AGENTS.md – vodnik tvojega projekta
AGENTS.md je ključna za učinkovito uporabo Codexa. Gre za preprosto datoteko Markdown v korenu tvojega repozitorija, ki zbere navodila, konvencije in ukaze, specifične za tvoj projekt. Ko Codex klonira repozitorij, to datoteko prebere prvo: razmišljaj o njej kot o samodejni uvedbi za agenta, točno tako, kot bi ustno razložil novemu članu ekipe.
Vpliv je takojšen. Brez AGENTS.md, če zaprosiš za enotski test v projektu, ki uporablja Vitest, obstaja velika verjetnost, da ti bo Codex dal Jest, ker je to najpogostejša izbira v ekosistemu. Ena sama vrstica konvencije zadostuje, da dobiš Vitest pravilno že prvič, kar ti prihrani sto popravkov. Tukaj je struktura osnovne datoteke za projekt upravljanja faktur SaaS.
# AGENTS.md
## Kontekst projekta
Aplikacija SaaS za upravljanje faktur.
Sklad: Next.js 15, TypeScript, Prisma, PostgreSQL.
## Konvencije kode
- Uporabi funkcionalne komponente React (brez razredov)
- Poimenuj datoteke v kebab-case
- Vrste TypeScript v ločenih datotekah .types.ts
- Testi z Vitest, datoteke .test.ts ob kodi
## Uporabni ukazi
- `npm run dev` — razvojni strežnik
- `npm run test` — zaženi teste
- `npm run lint` — preveri linting
- `npm run build` — produkcijska gradnja
## Struktura projekta
src/
app/ → strani Next.js (App Router)
components/ → Ponovno uporabne komponente React
lib/ → Poslovna logika in pripomočki
prisma/ → Shema podatkovne baze in migracije
## Stroga pravila
- NIKOLI ne spreminjaj sheme Prisma brez migracije
- NIKOLI ne dodajaj datotek .env
- Vedno uporabi Server Actions za mutacije
Kako Codex najde datoteke AGENTS.md
Ena sama datoteka v korenu hitro postane preveč splošna. Codex ti omogoča, da navodila zložiš v natančnem vrstnem redu, ki ga moraš poznati:
- Globalna raven: V tvoji mapi Codex (
~/.codex, razen čeCODEX_HOMEto povozí) Codex prebereAGENTS.override.md, če obstaja, sicerAGENTS.md. - Raven projekta: Začenši od korena projekta (običajno koren Git), Codex se spusti do trenutnega imenika in v vsaki prečesani mapi prebere
AGENTS.override.mdali, če tega ni,AGENTS.md. - Združevanje: Datoteke so združene od korena navzdol do trenutnega imenika; tiste, ki so najbližje trenutnemu imeniku, so zadnje in zato povozijo bolj splošna navodila.
my-project/
AGENTS.md → Navodila projekta
src/
api/
AGENTS.md → "API poti uporabljajo Zod za validacijo"
Praktična posledica: src/api/AGENTS.md se prebere le, če Codex dela iz src/api ali ene od njegovih podmap, ne pa, ko je zagnan iz korena. Prazne datoteke so prezrte, združevanje pa se privzeto ustavi pri 32 KiB (project_doc_max_bytes). Če tvoj repozitorij že uporablja drugo ime, kot je TEAM_GUIDE.md, ga dodaj v project_doc_fallback_filenames v ~/.codex/config.toml.
Če želiš preveriti, kaj je Codex dejansko naložil, ga preprosto vprašaj: codex --ask-for-approval never "Summarize the current instructions.". Codex vsakič ob zagonu znova zgradi verigo navodil: če dvomiš, ga znova zaženi v pravilnem imeniku.
Najboljše prakse za AGENTS.md
Vodilno načelo je eksplicitnost. “Uporabi Vitest, ne Jest” je bolje kot “Uporabi naš okvir za testiranje”, kar predpostavlja znanje, ki ga agent nima. Vedno vključi ukaze: brez njih Codex ne bo vedel, kako zagnati tvoje teste, linting ali gradnjo, in ti bo dostavil kodo, ki je ni mogel preveriti. Dokumentiraj strukturo kot drevo imenikov, kar prepreči, da bi slepo raziskoval in ustvarjal datoteke na napačnih mestih.
Na koncu naštej prepovedi. Pravila, zapisana kot “NIKOLI”, so v datoteki najbolj donosna, ker blokirajo drage napake, ki jih je težko popraviti: dodajanje datoteke .env, spreminjanje sheme brez migracije. Najtežja disciplina je vzdrževanje datoteke posodobljene. AGENTS.md, ki opisuje lanski projekt, aktivno usmerja Codex k opuščenim konvencijam – kar je veliko huje, kot da datoteke sploh nimaš, saj napaka takrat postane sistematična.
Ključne ugotovitve
- Začetna nastavitev zahteva račun OpenAI in povezavo z GitHubom
- Razširitev za IDE in CLI se namestita v nekaj minutah
- AGENTS.md je najpomembnejša datoteka za učinkovito uporabo Codexa
- Vsebuje konvencije, ukaze in pravila, specifične za tvoj projekt
- Datoteke AGENTS.md v podmapah omogočajo kontekstualna navodila