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

AGENTS.md: Конфигуриране на инструкциите за вашето хранилище

Урок 15 от 20 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Овладяване на конфигурационния файл на Codex
  2. Йерархията на AGENTS.md
  3. Секциите, които изграждат файла
  4. Два шаблона, които предотвратяват изненади
  5. Поддържане на файла жив
  6. Ключови изводи

Урокът е актуализиран на 3 ноември 2026 г. въз основа на страницата Custom instructions with AGENTS.md: Codex чете само файлове AGENTS.md, разположени между корена на проекта и текущата работна директория (плюс глобалния файл в ~/.codex). Файл в поддиректория извън този път не се зарежда, contrary to what the previous version implied. Източник: AGENTS.md.

Овладяване на конфигурационния файл на Codex

Вие открихте AGENTS.md в Урок 3. Тук ще навлезем в разширени шаблони – разликата между декоративен файл (три реда, написани при стартиране и забравени) и такъв, който реално управлява поведението на агента в жив проект.

Йерархията на AGENTS.md

Codex чете тези файлове йерархично, от общото към конкретното: първо глобалният файл във вашата папка на Codex (~/.codex/AGENTS.md, или AGENTS.override.md, ако съществува), след това, започвайки от корена на проекта, файловете в директориите, през които се преминава до текущата работна директория. При структуриран проект дървото изглежда така:

mon-projet/
  AGENTS.md                    → Глобални правила (нисък приоритет)
  src/
    AGENTS.md                  → Правила за целия изходен код
    api/
      AGENTS.md                → Правила специфични за API
      routes/
        AGENTS.md              → Правила за маршрути
    components/
      AGENTS.md                → Правила за React компоненти
  tests/
    AGENTS.md                  → Правила за тестове

Правилата се натрупват: Codex конкатенира файловете от корена надолу до текущата директория, като тези, най-близки до тази директория, прочетени последни, заместват общите инструкции. Един момент често се разбира погрешно: четат се само директории по пътя между корена и текущата директория. Ако вашият коренов файл забранява any, докато tests/AGENTS.md позволява по-свободни твърдения в моковете, тази толерантност важи само когато Codex работи от tests/ или една от нейните поддиректории; стартиран от корена, той не чете tests/AGENTS.md. За правило, което трябва да важи навсякъде, го поставете в корена, дори ако трябва да именувате изключението там. Прегледът на код в GitHub работи различно: Codex търси в цялото хранилище за файлове AGENTS.md и прилага правилата за преглед (## Code Review Rules) от файла, най-близък до съответния код. Конкатенацията спира по подразбиране на 32 KiB (project_doc_max_bytes): твърде дълъг файл се съкращава.

Секциите, които изграждат файла

Контекстът идва на първо място, защото той оформя всяко следващо решение. SaaS приложение, подлежащо на GDPR (Общ регламент за защита на данните), не се кодира като вътрешен инструмент за петима души:

## 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.

Знаейки, че обработва данни, подлежащи на GDPR, Codex ще добави очакваните защити, без да е нужно да ги уточнявате във всяка заявка. Следват конвенциите, които отговарят на един въпрос: как изглежда правилният код тук?

## 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)

Секцията с команди е най-често пропускана, а липсата ѝ струва скъпо: без тези команди Codex не може да провери собствената си работа и връща код, който никога не е изпълнявал или тествал.

## 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

Строгите правила формират предпазната ограда. Формулирани като “НИКОГА” и “ВИНАГИ”, те предотвратяват грешки, които струват цяла вечер за поправка: изтрита миграция на Prisma, която трябва да възстановите от продукцията, секретен ключ, който е комитнат и трябва да бъде анулиран, или innerHTML, промъкнат в компонент, който отваря 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

Накрая, архитектурата описва разрешения поток между слоевете. Без нея Codex произвежда код, който работи, но заобикаля вашата структура – например маршрут, който заявява Prisma директно, защото това е най-краткият път.

## 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.

Към това, проект по проект, се добавят инструкции, специфични за всяка използвана технология:

## 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

Два шаблона, които предотвратяват изненади

Декларирането на очакваните променливи на средата предотвратява Codex да измисля имена на ключове при писане на скрипт или случайно да логира чувствителна стойност в дебъг проследяване:

## 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)

Именуването на предпочитаните от вас библиотеки, и особено на тези, които отказвате, решава един повтарящ се проблем: агентът инсталира зависимост, която сама по себе си е напълно валидна, но вашият екип я е отхвърлил преди две години след лош опит.

## 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)

Поддържане на файла жив

AGENTS.md еволюира заедно с вашия код, точно като тест или README. Актуализирайте го веднага щом приемете нова конвенция, смените библиотеки или.frameworks, и особено веднага щом идентифицирате повтаряща се грешка на Codex: този последен случай винаги сигнализира за липсваща инструкция, а не за провал на модела. Четвърти, по-фин тригер си заслужава да се следи – когато нов разработчик зададе въпрос, на който AGENTS.md е трябвало да отговори, този отговор принадлежи във файла.

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

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