Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

AGENTS.md: konfigūruokite savo saugyklos instrukcijas

Paskaita 15 iš 20 Atnaujinta 2026 m. lapkričio 3 d. Kūrėjas
Šiame puslapyje
  1. „Codex“ konfigūracijos failo valdymas
  2. AGENTS.md hierarchija
  3. Skyriai, sudarantys failą
  4. Du šablonai, užkertantys kelią netikėtumams
  5. Failo palaikymas gyvu
  6. Svarbiausi punktai

Pamoka atnaujinta 2026 m. lapkričio 3 d. remiantis puslapiu Custom instructions with AGENTS.md: „Codex“ skaito tik AGENTS.md failus, 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.md hierarchija 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.md kaip gyvą kodą