AGENTS.md: Konfigurera dina repo-instruktioner
På denna sida
Lektionen uppdaterad 3 november 2026 baserat på sidan Custom instructions with AGENTS.md: Codex läser endast
AGENTS.md-filer som finns mellan projektroten och den aktuella arbetskatalogen (samt den globala filen på~/.codex). En fil i en underkatalog utanför denna sökväg laddas inte, vilket står i kontrast till vad den tidigare versionen antydde. Källa: AGENTS.md.
Bemästra konfigurationsfilen för Codex
Du stötte på AGENTS.md i lektion 3. Här dyker vi djupare i avancerade mönster – skillnaden mellan en dekorativ fil (tre rader skrivna vid start och sedan glömd) och en som faktiskt styr agentens beteende i ett levande projekt.
Hierarkin för AGENTS.md
Codex läser dessa filer hierarkiskt, från allmänt till specifikt: först den globala filen i din Codex-mapp (~/.codex/AGENTS.md, eller AGENTS.override.md om den finns), sedan, från projektroten, filerna i de kataloger som passeras ner till den aktuella arbetskatalogen. På ett strukturerat projekt ser trädet ut så här:
mon-projet/
AGENTS.md → Globala regler (låg prioritet)
src/
AGENTS.md → Regler för all källkod
api/
AGENTS.md → Regler specifika för API:er
routes/
AGENTS.md → Regler för rutter
components/
AGENTS.md → Regler för React-komponenter
tests/
AGENTS.md → Regler för tester
Regler ackumuleras: Codex slår samman filer från roten ner till den aktuella katalogen, där de som ligger närmast den aktuella katalogen läses sist och åsidosätter generella instruktioner. En punkt missförstås lätt: endast kataloger på sökvägen mellan roten och den aktuella katalogen läses. Om din rotfil förbjuder any medan tests/AGENTS.md tillåter lösare påståenden i mocks, gäller den toleransen endast när Codex arbetar från tests/ eller en av dess underkataloger; startas processen från roten läses inte tests/AGENTS.md. GitHub-kodgranskning fungerar annorlunda: Codex söker igenom hela arkivet efter AGENTS.md-filer där och tillämpar granskningsreglerna (## Code Review Rules) från filen som ligger närmast den aktuella koden. Sammanslagningen stoppas vid 32 KiB som standard (project_doc_max_bytes): en fil som är för lång blir trunkerad.
De sektioner som bygger filen
Kontexten kommer först, eftersom den formar varje beslut som följer. En SaaS-applikation som lyder under GDPR (General Data Protection Regulation) kodas inte på samma sätt som ett internt verktyg för 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.
När Codex vet att den hanterar data som omfattas av GDPR lägger den till förväntade skydd utan att du behöver specificera dem i varje begäran. Därefter följer konventionerna, som svarar på en fråga: hur ser korrekt kod ut här?
## 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 för kommandon utelämnas oftast, och frånvaron är kostsam: utan dessa kommandon kan Codex inte verifiera sitt eget arbete och returnerar kod den aldrig har kört eller testat.
## 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
Strikta regler utgör räcket. Formulerade som “ALDRIG” och “ALLTID” förhindrar de fel som kostar en hel kväll att åtgärda: en borttagen Prisma-migrering du måste återskapa från produktion, en hemlighet som commitats och måste återkallas, eller ett innerHTML som smugits in i en komponent och öppnar för en XSS-sårbarhet.
## 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
Slutligen beskriver arkitekturen det tillåtna flödet mellan lager. Utan den producerar Codex kod som fungerar men kortsluter din struktur – till exempel en rutt som frågar Prisma direkt, helt enkelt för att det var den kortaste vägen.
## 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.
Därtill kommer, projekt för projekt, instruktioner specifika för varje teknik som används:
## 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
Två mönster som förhindrar överraskningar
Att deklarera förväntade miljövariabler förhindrar att Codex hittar på nyckelnamn när den skriver ett skript, eller av misstag loggar ett känsligt värde i en debugg-spårning:
## 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)
Att namnge dina föredragna bibliotek, och särskilt de du vägrar använda, löser ett återkommande problem: agenten installerar ett beroende som i sig är helt giltigt, men som ditt team avvisade för två år sedan efter en dålig erfarenhet.
## 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)
Att hålla filen levande
AGENTS.md utvecklas tillsammans med din kod, precis som ett test eller en README. Uppdatera den så snart du antar en ny konvention, byter bibliotek eller ramverk, och särskilt så snart du identifierar ett återkommande Codex-fel: det sista fallet signalerar alltid en saknad instruktion snarare än ett modellfel. En fjärde, mer subtil utlösare är värd att hålla utkik efter – när en ny utvecklare ställer en fråga som AGENTS.md borde ha svarat på, hör det svaret hemma i filen.
Viktiga punkter
- Hierarkin för
AGENTS.mdmöjliggör alltmer specifika instruktioner - Kommandon är avgörande för att Codex ska kunna verifiera sitt arbete
- Regler med ALDRIG är viktigast för att undvika fel
- Dokumentera föredragna beroenden för att förhindra dåliga val
- Underhåll
AGENTS.mdsom levande kod