AGENTS.md: Konfigurer dine repo-instrukser
På denne side
Lektion opdateret 3. november 2026 baseret på siden Custom instructions with AGENTS.md: Codex læser kun
AGENTS.md-filer placeret mellem projektroden og den aktuelle arbejdsmappe (samt den globale fil på~/.codex). En fil i en undermappe uden for denne sti indlæses ikke, i modsætning til hvad den tidligere version antydede. Kilde: AGENTS.md.
Mestring af Codex-konfigurationsfilen
Du stødte på AGENTS.md i lektion 3. Her dykker vi ned i avancerede mønstre – forskellen mellem en dekorativ fil (tre linjer skrevet ved opstart og glemt) og en, der reelt styrer agentens adfærd i et live-projekt.
AGENTS.md-hierarkiet
Codex læser disse filer hierarkisk, fra generelt til specifikt: først den globale fil i din Codex-mappe (~/.codex/AGENTS.md, eller AGENTS.override.md hvis den eksisterer), derefter, startende fra projektroden, filerne i de mapper, der traverseres ned til den aktuelle arbejdsmappe. På et struktureret projekt ser træet sådan ud:
mon-projet/
AGENTS.md → Globale regler (lav prioritet)
src/
AGENTS.md → Regler for al kildekode
api/
AGENTS.md → Regler specifikke for API'er
routes/
AGENTS.md → Regler for ruter
components/
AGENTS.md → Regler for React-komponenter
tests/
AGENTS.md → Regler for tests
Regler akkumuleres: Codex sammenkæder filer fra roden ned til den aktuelle mappe, og dem der er tættest på den mappe, læses sidst og tilsidesætter generelle instrukser. Et punkt misforstås let: kun mapper på stien mellem roden og den aktuelle mappe læses. Hvis din rodfil forbyder any, mens tests/AGENTS.md tillader løsere assertioner i mocks, gælder den tolerance kun, når Codex arbejder fra tests/ eller en af dens undermapper; startes den fra roden, læses tests/AGENTS.md ikke. For en regel, der skal gælde overalt, placeres den i roden, selvom du skal navngive undtagelsen der. GitHub-code-review fungerer anderledes: Codex gennemsøger hele repository’et efter AGENTS.md-filer der og anvender review-reglerne (## Code Review Rules) fra filen tættest på den pågældende kode. Sammenkædningen stopper ved 32 KiB som standard (project_doc_max_bytes): en fil, der er for lang, bliver trunkeret.
De sektioner, der gør filen effektiv
Kontekst kommer først, fordi den former enhver beslutning, der følger. En SaaS-applikation underlagt GDPR (General Data Protection Regulation) kodes ikke som et internt værktøj til fem personer:
## 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.
Ved at vide, at den håndterer data underlagt GDPR, vil Codex tilføje de forventede beskyttelser uden at du skal specificere dem i hver eneste anmodning. Dernæst kommer konventionerne, som besvarer ét spørgsmål: hvordan ser korrekt kode ud her?
## 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)
Sektionen med kommandoer udelades oftest, og fraværet er dyrt: uden disse kommandoer kan Codex ikke verificere sit eget arbejde og returnerer kode, den aldrig har kørt eller testet.
## 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
Strikte regler danner værnene. Formuleret som „ALDRIG” og „ALTID” forhindrer de fejl, der koster en hel aften at rette: en slettet Prisma-migration, du skal rekonstruere fra produktion, en commitet hemmelighed, der skal tilbagekaldes, eller et innerHTML sniget ind i en komponent, der åbner en XSS-sårbarhed.
## 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
Endelig beskriver arkitekturen den tilladte flow mellem lag. Uden den producerer Codex kode, der virker, men som short-circuiter din struktur – f.eks. en rute, der spørger Prisma direkte, fordi det var den korteste vej.
## 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.
Til dette føjes, projekt for projekt, instrukser specifikke for hver anvendt teknologi:
## 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
To mønstre, der forhindrer overraskelser
At deklarere forventede miljøvariabler forhindrer Codex i at opfinde nøglenavne, når den skriver et script, eller utilsigtet at logge en følsom værdi i en debug-trace:
## 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)
At navngive dine foretrukne biblioteker, og især dem du nægter at bruge, løser en tilbagevendende ærgrelse: agenten installerer en afhængighed, der i sig selv er fuldt ud gyldig, men som dit team forkastede for to år siden efter en dårlig oplevelse.
## 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)
At holde filen i live
AGENTS.md udvikler sig sammen med din kode, ligesom en test eller en README. Opdater den, så snart du adopterer en ny konvention, skifter biblioteker eller frameworks, og især så snart du identificerer en tilbagevendende Codex-fejl: det sidste tilfælde signalerer altid en manglende instruktion snarere end en modelfejl. En fjerde, mere subtil udløser er værd at holde øje med – når en ny udvikler stiller et spørgsmål, som AGENTS.md burde have besvaret, hører det svar hjemme i filen.
Vigtige pointer
- Hierarkiet i
AGENTS.mdmuliggør stadig mere specifikke instrukser - Kommandoer er afgørende for, at Codex kan verificere sit arbejde
- ALDRIG-regler er de vigtigste for at undgå fejl
- Dokumentér foretrukne afhængigheder for at forhindre dårlige valg
- Vedligehold
AGENTS.mdsom levende kode