AGENTS.md: konfigurējiet sava repozitorija instrukcijas
Šajā lapā
Nodarbība atjaunināta 2026. gada 3. novembrī, pamatojoties uz lapu Custom instructions with AGENTS.md: Codex lasa tikai
AGENTS.mdfailus, kas atrodas starp projekta sakni un pašreizējo darba direktoriju (kā arī globālo failu vietnē~/.codex). Fails apakšdirektorijā ārpus šī ceļa netiek ielādēts, pretēji tam, ko implicēja iepriekšējā versija. Avots: AGENTS.md.
Codex konfigurācijas faila apgūšana
- nodarbībā tu iepazinies ar
AGENTS.md. Šeit mēs iedziļināmies uzlabotos modeļos – atšķirībā starp dekoratīvu failu (trīs rindas, kas uzrakstītas starta brīdī un aizmirstas) un tādu, kas patiesībā virza aģenta uzvedību dzīvā projektā.
AGENTS.md hierarhija
Codex šos failus lasa hierarhiski, no vispārīgā uz specifisko: vispirms globālo failu tavā Codex mapē (~/.codex/AGENTS.md vai AGENTS.override.md, ja tas eksistē), pēc tam, sākot no projekta saknes, failus direktorijos, kas šķērsoti līdz pašreizējai darba direktorijai. Strukturētā projektā koks izskatās šādi:
mon-projet/
AGENTS.md → Globālie noteikumi (zema prioritāte)
src/
AGENTS.md → Noteikumi visam pirmkoda
api/
AGENTS.md → Noteikumi specifiski API
routes/
AGENTS.md → Noteikumi maršrutiem
components/
AGENTS.md → Noteikumi React komponentēm
tests/
AGENTS.md → Noteikumi testiem
Noteikumi uzkrājas: Codex savieno failus no saknes līdz pašreizējai direktorijai, un tie, kas atrodas vistuvāk šai direktorijai un tiek lasīti pēdējie, pārraksta vispārīgās instrukcijas. Viens punkts tiek viegli pārprasts: tiek lasīti tikai direktoriji, kas atrodas ceļā starp sakni un pašreizējo direktoriju. Ja tava saknes fails aizliedz any, bet tests/AGENTS.md pieļauj brīvākus apgalvojumus mokos, šī tolerance attiecas tikai tad, kad Codex strādā no tests/ vai kādas no tās apakšdirektorijām; palaižot to no saknes, tas nelasa tests/AGENTS.md. GitHub koda apskats darbojas citādāk: Codex meklē visā repozitorijā AGENTS.md failus un piemēro apskata noteikumus (## Code Review Rules) no faila, kas atrodas vistuvāk attiecīgajam kodam. Savienošana pēc noklusējuma apstājas pie 32 KiB (project_doc_max_bytes): pārāk garš fails tiek saīsināts.
Sadaļas, kas veido failu
Konteksts ir pirmajā vietā, jo tas nosaka katru turpmāko lēmumu. SaaS lietotne, uz kuru attiecas VDAR (Vispārīgā datu aizsardzības regula), netiek kodēta tāpat kā iekšējs rīks pieciem cilvēkiem:
## 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.
Zinot, ka tā apstrādā datus, uz kuriem attiecas VDAR, Codex pievienos paredzētās aizsardzības, tev nenāksies tās norādīt katrā pieprasījumā. Tālāk seko konvencijas, kas atbild uz vienu jautājumu: kā šeit izskatās pareizs kods?
## 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)
Komandu sadaļa tiek izlaista visbiežāk, un tās trūkums dārgi maksā: bez šīm komandām Codex nevar pārbaudīt savu darbu un atgriež kodu, ko tas nekad nav izpildījis vai testējis.
## 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
Stingrie noteikumi veido drošības barjeru. Formulēti kā „NEKAD” un „VIENMĒR”, tie novērš kļūdas, kuru labošana prasa veselu vakaru: dzēsta Prisma migrācija, kas jārekonstruē no produkcijas vides, noslēpums, kas iekļauts repozitorijā un ir jāatsauc, vai innerHTML, kas ieviests komponentē un atver XSS ievainojamību.
## 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
Visbeidzot, arhitektūra apraksta atļauto plūsmu starp slāņiem. Bez tās Codex ģenerē kodu, kas darbojas, bet apiet tavu struktūru – piemēram, maršruts, kas tieši vaicā Prisma, jo tas bija īsākais ceļš.
## 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.
Tam projektā pēc projekta tiek pievienotas instrukcijas, kas specifiskas katrai izmantotajai tehnoloģijai:
## 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
Divi modeļi, kas novērš pārsteigumus
Deklarējot paredzētās vides mainīgās, tu novērsi situācijas, kad Codex izdomā atslēgu nosaukumus, rakstot skriptu, vai nejauši žurnāla ierakstā iekļauj sensitīvu vērtību atkļūdošanas laikā:
## 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)
Nosaucot savas iecienītākās bibliotēkas un it īpaši tās, kuras tu noraidi, tu atrisini atkārtotu problēmu: aģents instalē atkarību, kas pati par sevi ir pilnīgi derīga, bet ko tava komanda noraidīja pirms diviem gadiem pēc sliktas pieredzes.
## 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)
Faila uzturēšana dzīvā stāvoklī
AGENTS.md evolucionē līdzīgi tavam kodam, tāpat kā tests vai README. Atjaunini to tiklīdz pieņem jaunu konvenciju, nomaini bibliotēkas vai ietvarus, un it īpaši tiklīdz identificē atkārtotu Codex kļūdu: šis pēdējais gadījums vienmēr signalizē par trūkstošu instrukciju, nevis modeļa kļūmi. Ir vērts pievērst uzmanību arī ceturtajam, smalkākam iemeslam – kad jauns izstrādātājs uzdod jautājumu, uz kuru AGENTS.md būtu bijis jāatbild, šī atbilde ir jāievieto failā.
Galvenās atziņas
AGENTS.mdhierarhija ļauj ieviest arvien specifiskākas instrukcijas- Komandas ir kritiski svarīgas, lai Codex varētu pārbaudīt savu darbu
- Noteikumi NEKAD ir vissvarīgākie, lai izvairītos no kļūdām
- Dokumentē iecienītākās atkarības, lai novērstu sliktas izvēles
- Uzturi
AGENTS.mdkā dzīvu kodu