Премини към основното съдържание
Български— Изберете език
Меню

Настройте вашата среда и AGENTS.md

Урок 3 от 20 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Подгответе проекта си за Codex
  2. Стъпка 1: Вашият достъп до Codex
  3. Стъпка 2: Инсталирайте разширението за редактора
  4. Стъпка 3: Инсталирайте CLI
  5. Файлът AGENTS.md – вашият проектен наръчник
  6. Най-добри практики за AGENTS.md
  7. Ключови изводи

Обновено на 3 ноември 2026 г. въз основа на документацията на Codex (Codex CLI, Удостоверяване, Разширение за Codex IDE, Персонализирани инструкции с AGENTS.md): пакетът @openai/codex-cli и командата codex auth login не съществуват (използвайте npm install -g @openai/codex и codex login); идентификаторът на разширението е openai.chatgpt; адресът codex.openai.com и плановете “Team, Enterprise или API” са заменени с текущите методи за достъп; редът на четене на AGENTS.md е изяснен (корен на проекта → текуща директория). Източници: Codex CLI · Удостоверяване · AGENTS.md · Цени.

Подгответе проекта си за Codex

Преди първата си задача трябва да са налице две неща: вашият достъп до Codex – вашият акаунт и връзката с GitHub – и самият ви проект, дефиниран чрез файла AGENTS.md, който ще направлява агента. Първата част отнема около 15 минути и се прави веднъж. Втората определя качеството на всичко, което получавате от Codex, и разделя екипите, доволни от Codex, от онези, които го намират за разочароващ.

Стъпка 1: Вашият достъп до Codex

Можете да използвате Codex с акаунт в ChatGPT или с API ключ. Безплатните планове и планът Go осигуряват достъп, в зависимост от текущото разполагане, до GPT-6 Luna в десктоп приложението. Започвайки от плана Plus, Codex е достъпен в уеб интерфейса, в CLI, в разширението за редактор и на iOS, с облачни интеграции като автоматизиран преглед на код. API ключът работи за автоматизация в споделени среди като CI, използвайки CLI, SDK или разширението – въпреки че някои функции може да не са налични. Подробности и ограничения за използване има на страницата с цени на Codex.

За да работите в облака с вашите хранилища, свържете GitHub, когато създавате първата си среда в Codex Cloud (Урок 2). Когато предоставяте разрешения, бъдете минималисти: ограничете достъпа само до хранилищата, от които наистина имате нужда.

Стъпка 2: Инсталирайте разширението за редактора

Във VS Code и неговите производни (Cursor, Windsurf) инсталирайте разширението Codex от маркетплейса – неговият идентификатор е openai.chatgpt:

code --install-extension openai.chatgpt

След това отворете Codex чрез неговата икона или чрез палетата с команди с Codex: Open Codex Sidebar и влезте в системата. Xcode и JetBrains IDE имат свои собствени интеграции: в JetBrains отворете AI Chat и изберете Codex.

Стъпка 3: Инсталирайте CLI

# Инсталация (macOS и Linux), или npm install -g @openai/codex
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Проверка на инсталацията
codex --version

# Вход (браузър) или проверка на статуса на връзката
codex login
codex login status

codex login отваря процеса на влизане във вашия браузър. За API ключ го предайте чрез стандартния вход (printenv OPENAI_API_KEY | codex login --with-api-key). Codex кешира идентификационните данни или в текстов файл ~/.codex/auth.json, или в системния ключодържател, в зависимост от настройката cli_auth_credentials_store (file, keyring, auto или ephemeral). Ако се използва файл, третирайте го като парола: той съдържа токени за достъп, затова никога не го добавяйте в хранилището. CLI и разширението споделят този кеш.

Файлът AGENTS.md – вашият проектен наръчник

AGENTS.md е централен за ефективното използване на Codex. Това е обикновен Markdown файл, разположен в корена на вашето хранилище, който събира инструкции, конвенции и команди, специфични за вашия проект. Когато Codex клонира хранилището, той чете този файл първи: мислете за него като за автоматично въвеждане в работата за агента, точно това, което бихте обяснили устно на нов член на екипа.

Ефектът е незабавен. Без AGENTS.md, ако поискате модулен тест за проект, използващ Vitest, има голям шанс Codex да ви даде Jest, защото това е най-честият избор в екосистемата. Една единствена линия с конвенция е достатъчна, за да получите правилно Vitest от първия път, спестявайки ви необходимостта да правите същата корекция сто пъти. Ето структурата на основен файл за SaaS проект за управление на фактури.

# AGENTS.md

## Контекст на проекта
SaaS приложение за управление на фактури.
Стек: Next.js 15, TypeScript, Prisma, PostgreSQL.

## Конвенции за код
- Използвайте функционални React компоненти (без класове)
- Именувайте файловете в kebab-case
- TypeScript типовете в отделни .types.ts файлове
- Тестове с Vitest, .test.ts файлове до кода

## Полезни команди
- `npm run dev` — сървър за разработка
- `npm run test` — стартиране на тестове
- `npm run lint` — проверка на линтера
- `npm run build` — производствена версия

## Структура на проекта
    src/
      app/          → Next.js страници (App Router)
      components/   → Многоразови React компоненти
      lib/          → Бизнес логика и помощни функции
      prisma/       → DB схема и миграции

## Строги правила
- НИКОГА не променяйте Prisma схемата без миграция
- НИКОГА не добавяйте .env файлове в хранилището
- Винаги използвайте Server Actions за мутации

Как Codex открива файловете AGENTS.md

Един единствен файл в корена бързо става твърде общ. Codex ви позволява да натрупвате инструкции в точен ред, който трябва да знаете:

  1. Глобално ниво: Във вашата папка на Codex (~/.codex, освен ако CODEX_HOME не я променя), Codex чете AGENTS.override.md, ако съществува, в противен случай AGENTS.md.
  2. Ниво на проекта: Започвайки от корена на проекта (обикновено коренът на Git), Codex слиза до текущата директория и чете във всяка премината папка AGENTS.override.md или, при липса на такъв, AGENTS.md.
  3. Сливане: Файловете се конкатенират от корена надолу до текущата директория; тези, които са най-близо до текущата директория, идват последни и следователно презаписват по-общите инструкции.
my-project/
  AGENTS.md              → Инструкции за проекта
  src/
    api/
      AGENTS.md          → "API маршрутите използват Zod за валидация"

Практическо следствие: src/api/AGENTS.md се чете само ако Codex работи от src/api или една от неговите поддиректории, а не когато е стартиран от корена. Празните файлове се игнорират, а конкатенацията спира при 32 KiB по подразбиране (project_doc_max_bytes). Ако вашето хранилище вече използва друго име, като TEAM_GUIDE.md, добавете го към project_doc_fallback_filenames в ~/.codex/config.toml.

За да проверите какво всъщност е заредил Codex, просто попитайте: codex --ask-for-approval never "Summarize the current instructions.". Codex изгражда отново веригата с инструкции при всяко стартиране: ако се съмнявате, рестартирайте го в правилната директория.

Най-добри практики за AGENTS.md

Ръководният принцип е изричността. “Използвайте Vitest, а не Jest” е по-добре от “Използвайте нашия тестов框架”, което предполага знание, което агентът няма. Винаги включвайте команди: без тях Codex няма да знае как да стартира вашите тестове, линтер или билд и ще достави код, който не е могъл да провери. Документирайте структурата като дърво на директории, което предотвратява сляпото ѝ изследване и създаването на файлове на грешното място.

Накрая, избройте забраните. Правилата, написани като “НИКОГА”, са най-ефективни от гледна точка на разходите във файла, защото блокират скъпи грешки, които трудно се поправят: добавяне на .env файл в хранилището, промяна на схема без миграция. Най-трудната дисциплина е поддържането на файла актуален. AGENTS.md, който описва проекта от миналата година, активно насочва Codex към изоставени конвенции – много по-зле от липсата на файл изобщо, тъй като тогава грешката става системна.

Ключови изводи

  • Първоначалната настройка изисква акаунт в OpenAI и връзка с GitHub
  • Разширението за IDE и CLI се инсталират за минути
  • AGENTS.md е най-важният файл за ефективно използване на Codex
  • Той съдържа конвенции, команди и правила, специфични за вашия проект
  • Файловете AGENTS.md в поддиректориите позволяват контекстуални инструкции