AGENTS.md: konfigūruokite savo saugyklos instrukcijas
Šiame puslapyje
Pamoka atnaujinta 2026 m. lapkričio 3 d. remiantis puslapiu Custom instructions with AGENTS.md: „Codex“ skaito tik
AGENTS.mdfailus, esančius tarp projekto šaknies ir dabartinio darbo katalogo (plius globalų failą~/.codex). Failas, esantis šiame kelyje nepatenkančiame pakatalogyje, nėra įkeliamas, priešingai nei teigė ankstesnė versija. Šaltinis: AGENTS.md.
„Codex“ konfigūracijos failo valdymas
3-ioje pamokoje jau susipažinai su AGENTS.md. Čia gilinsimės į pažangius šablonus – koks skirtumas tarp dekoratyvinio failo (trijų eilučių, parašytų pradedant darbą ir pamirštų) ir tokio, kuris realiai valdo agento elgseną gyvame projekte.
AGENTS.md hierarchija
„Codex“ šiuos failus skaito hierarchiškai, nuo bendro prie specifinio: pirmiausia globalų failą savo „Codex“ aplanke (~/.codex/AGENTS.md, arba AGENTS.override.md, jei jis egzistuoja), tada, pradedant nuo projekto šaknies, failus kataloguose, per kuriuos einama žemyn iki dabartinio darbo katalogo. Struktūrizuotame projekte medžio struktūra atrodo taip:
mon-projet/
AGENTS.md → Globalios taisyklės (mažas prioritetas)
src/
AGENTS.md → Taisyklės visam源代码 kodui
api/
AGENTS.md → Taisyklės specifinės API
routes/
AGENTS.md → Taisyklės maršrutams (routes)
components/
AGENTS.md → Taisyklės React komponentams
tests/
AGENTS.md → Taisyklės testams
Taisyklės kaupiasi: „Codex“ sujungia failus nuo šaknies iki dabartinio katalogo, o tie, kurie yra arčiausiai to katalogo ir skaitomi paskutiniai, perrašo bendrąsias instrukcijas. Vienas punktas dažnai suprantamas klaidingai: skaitomi tik katalogai, esantys kelyje tarp šaknies ir dabartinio katalogo. Jei šaknies failas draudžia naudoti any, o tests/AGENTS.md leidžia laisvesnius teiginius mock objektuose, ši tolerancija galioja tik tada, kai „Codex“ dirba iš tests/ arba vieno iš jo pakatalogių; paleistas iš šaknies, jis tests/AGENTS.md neskaito. Taisyklei, kuri turi galioti visur, vieta yra šaknyje, net jei tenka joje įvardyti išimtį. GitHub kodų peržiūra veikia kitaip: „Codex“ visoje saugykloje ieško AGENTS.md failų ir taiko peržiūros taisykles (## Code Review Rules) iš failo, esančio arčiausiai nagrinėjamo kodo. Sujungimas pagal nutylėjimą sustoja ties 32 KiB (project_doc_max_bytes): per ilgas failas yra sutrumpinamas.
Skyriai, sudarantys failą
Pirmiausia eina kontekstas, nes jis formuoja kiekvieną tolesnį sprendimą. SaaS programa, kuriai taikomas BDAR (Bendrasis duomenų apsaugos reglamentas), kuriama ne taip, kaip vidinis įrankis penkiems žmonėms:
## 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.
Žinodamas, kad tvarkomi duomenys, kuriems taikomas BDAR, „Codex“ pridės reikiamas apsaugas, tau nereikės jų nurodyti kiekviename prašyme. Toliau eina konvencijos, atsakančios į vieną klausimą: kaip čia atrodo teisingas kodas?
## 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)
Komandų skyrius dažniausiai praleidžiamas, o jo nebuvimas kainuoja brangiai: be šių komandų „Codex“ negali patikrinti savo darbo ir grąžina kodą, kurio niekada nevykdė ir netestavo.
## 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
Griežtos taisyklės sudaro apsauginį barjerą. Suformuluotos kaip „NIKADA“ ir „VISADA“, jos užkerta kelią klaidoms, kurių ištaisymas kainuoja visą vakarą: ištrinta Prisma migracija, kurią teks atkurti iš produkcinės aplinkos, įsipareigotas slaptažodis, kurį reikia anuliuoti, arba į komponentą įterptas innerHTML, atveriantis XSS pažeidžiamumą.
## 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
Galiausiai architektūra aprašo leistiną srautą tarp sluoksnių. Be jos „Codex“ kuria kodą, kuris veikia, bet apeina tavo struktūrą – pavyzdžiui, maršrutas, tiesiogiai užklausiantis Prisma, nes tai buvo trumpiausias kelias.
## 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.
Prie to projekto po projekto pridedamos instrukcijos, specifinės kiekvienai naudojamai technologijai:
## 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
Du šablonai, užkertantys kelią netikėtumams
Deklaruojant tikėtinus aplinkos kintamuosius, užkertamas kelias „Codex“ išgalvoti raktų pavadinimus rašant scenarijų arba netyčia įrašyti jautrią reikšmę į derinimo žurnalą:
## 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)
Įvardijant pageidaujamas bibliotekas ir ypač tas, kurių atsisakote, išsprendžiama pasikartojanti problema: agentas įdiegia priklausomybę, kuri savaime yra visiškai tinkama, bet kurią jūsų komanda prieš dvejus metus atmetė po nesėkmingos patirties.
## 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)
Failo palaikymas gyvu
AGENTS.md evoliucionuoja kartu su tavo kodu, lygiai kaip testas arba README. Atnaujink jį iškart, kai priimi naują konvenciją, keiti bibliotekas ar karkasus, ir ypač kai tik nustatai pasikartojančią „Codex“ klaidą: šis atvejis visada signalizuoja apie trūkstamą instrukciją, o ne modelio gedimą. Verta stebėti ir ketvirtą, subtilesnį triggerį – kai naujas kūrėjas užduoda klausimą, į kurį AGENTS.md turėjo atsakyti, tas atsakymas turi atsidurti faile.
Svarbiausi punktai
AGENTS.mdhierarchija leidžia naudoti vis specifiškesnes instrukcijas- Komandos yra kritiškai svarbios, kad „Codex“ galėtų patikrinti savo darbą
- NIKADA taisyklės yra svarbiausios norint išvengti klaidų
- Dokumentuokite pageidaujamas priklausomybes, kad išvengtumėte netinkamų pasirinkimų
- Tvarkykite
AGENTS.mdkaip gyvą kodą