Vad är AGENTS.md och hur skriver du en egen på 30 minuter

Praktiskt material om vibe coding och arbete med agenter: Ailoot-dokumentation.

AGENTS.md i ett stycke#

Nedan behandlas formatet med utgångspunkt i agents.md, dokumentationen för OpenAI Codex, JetBrains Junie, Cursor Rules Docs, ändringsloggen för GitHub Copilot Coding Agent och Linux Foundations pressmeddelande om Agentic AI Foundation. Alla siffror och funktioner är aktuella per den 30 maj 2026, och stödet för AGENTS.md i Claude Code beskrivs enligt Anthropics dokumentation, med en uppdatering från den 24 september 2026.

Om du inte vet vad den här djungeln av verktyg på marknaden är eller varför de behöver en gemensam fil, läs först guiden ”Vad ska man koda med 2026: 8 AI-verktyg från Claude Code till Antigravity”. Den här artikeln handlar specifikt om formatet AGENTS.md och hur du skriver en egen på 30 minuter.

Vad är AGENTS.md och varifrån kommer det?#

Tidigare hade varje AI-verktyg sin egen regelfil: Anthropic hade CLAUDE.md, Cursor hade .cursorrules, GitHub hade .github/copilot-instructions.md, Aider hade .aider.conf.yml och JetBrains hade .junie/guidelines.md. Om teamet hade tre olika agenter betydde det tre parallella filer med samma innehåll, som skulle börja skilja sig åt inom en vecka.

OpenAI var först med att tröttna på det. I augusti 2025 släppte företaget Codex CLI och lanserade samtidigt agents.md som ett öppet format. Från webbplatsen:

”Tänk på AGENTS.md som en README för agenter.”

(agents.md, översatt från engelska)

Huvudpoängen är att AGENTS.md kompletterar README. README skrivs för människor: ”vad projektet är, hur man kör det lokalt, hur man bidrar”. AGENTS.md skrivs för agenten: exakta skalkommandon, verifierbara kriterier för att vara ”klar” och gränser som ”rör aldrig det här”.

Från webbplatsen:

”AGENTS.md kompletterar README: den innehåller ytterligare, ibland detaljerad kontext som agenten behöver – byggsteg, tester och konventioner som skulle göra README rörig eller helt enkelt inte behövs av mänskliga bidragsgivare.”

(agents.md, översatt från engelska)

I september 2025 stödde GitHub Copilot Coding Agent formatet (ändringslogg, 28.08.2025). I december hade Cursor, Junie, Gemini CLI, Aider och ett dussin andra verktyg anslutit sig. Den 9 december 2025 bildade Linux Foundation Agentic AI Foundation (AAIF): de tre grundande projekten var AGENTS.md från OpenAI, MCP från Anthropic och goose från Block. De grundande medlemmarna var AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft och OpenAI. Den 24 februari 2026 omfattade stiftelsen redan 146 organisationer, däribland Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, UiPath och Hitachi.

Från och med då slutade AGENTS.md vara ”ännu en grej från OpenAI” och blev de facto-standard.

Vilka AI-agenter läser AGENTS.md och vilka gör det inte?#

Tabell över stöd per den 30 maj 2026; raden om Claude Code uppdaterades den 24 september 2026:

Anthropic var den sista av de stora aktörerna att ansluta sig. I augusti 2025 öppnades ärende #6235 i det officiella arkivet anthropics/claude-code med en begäran om stöd för AGENTS.md.

Ärendet var öppet i nästan ett år och stängdes den 17 augusti 2026; version 2.1.277 med stöd för AGENTS.md släpptes den 18 september. Anthropics logik är följande: CLAUDE.md har företräde, och AGENTS.md läses när det inte finns någon CLAUDE.md i arbetsmappen eller någon överordnad mapp. Enligt dokumentationen fungerar det så här:

Haken: en personlig CLAUDE.local.md räknas också, och då slutar Claude Code läsa AGENTS.md. Du kan ändra detta beteende i /config, under Project instructions – till exempel så att Claude Code läser båda filerna samtidigt. I versioner äldre än 2.1.277 hämtas AGENTS.md inte automatiskt; raden @AGENTS.md i CLAUDE.md är fortfarande lösningen.

Hur skiljer sig AGENTS.md från CLAUDE.md och .cursorrules?#

Jämförelse av fyra format per den 30 maj 2026:

Grundidén är att AGENTS.md löser problemet med ”en fil för alla agenter”, men inte problemet med ”personliga inställningar som jag inte checkar in”. Claude Code har CLAUDE.local.md för det, och Cursor har lokala .mdc-filer under user. AGENTS.md har inte den funktionen i sig – du behöver antingen kombinera den med andra filer eller komma överens i teamet om att skriva personliga regler i avsnitt som ignoreras av git.

En annan viktig detalj gäller monorepon. Codex och Cursor tillämpar regeln ”den närmaste AGENTS.md vinner”:

”I ett monorepo placerar du en separat AGENTS.md i varje paket. Agenterna läser automatiskt den närmaste filen i katalogträdet, och den närmaste vinner.”

(agents.md, översatt från engelska)

agents.md nämner att OpenAI:s huvudsakliga monorepo innehåller 88 AGENTS.md-filer för olika underpaket. Om du arbetar i ett monorepo kan du fördela reglerna över nivåerna: allmänna regler i roten, specifika regler i undermappar.

Vad bör en bra AGENTS.md innehålla?#

Webbplatsen agents.md erbjuder ett flexibelt format – ”valfri Markdown”. Men 80% av bra filer som finns i verkligheten innehåller samma åtta avsnitt. Huvudregeln: varje punkt bör vara ett exakt kommando eller ett konkret exempel. En abstrakt idé som ”skriv ren kod” kommer agenten att ignorera.

1. Projektöversikt – 2–3 rader. Vad projektet är, vem det är till för och dess huvudmål. Ingen marknadsföring. Exempel: ”Telegram-bot för introduktion i en betald workshop. Stack: Next.js 14, Prisma, PostgreSQL. Utlöses av en ny post i purchases.”
2. Installationskommandon – exakta skalkommandon för lokal körning. npm install, npm run dev, npm run build. Inget ”så här brukar vi göra”.
3. Kodstil / konventioner – specifika regler med exempel, inte ”skriv prydligt”. Till exempel: ”TypeScript strict, enkla citationstecken, inga default exports, komponentnamn i PascalCase, hooks börjar med use.”
4. Tips för utvecklingsmiljön – var viktiga saker finns. Vilka variabler som behövs i .env, var hemligheter lagras, vilka portar som används och hur man arbetar med den lokala DB:n.
5. Testinstruktioner – hur man kör ett specifikt test och vad som räknas som ”godkänt”. Till exempel: npm test -- --testPathPattern=user-auth; 100% godkänt förväntas.
6. Riktlinjer för PR / commits – format för commitmeddelanden, checklista före PR (tester, linter, dokumentation) och vem som godkänner.
7. Säkerhetsöverväganden – vad som aldrig får hända. ”Checka aldrig in .env. Hemligheter hör bara hemma i Vault. Visa inte användarnas personuppgifter i loggar.”
8. Gränser / Gör aldrig detta – förbud med ett alternativ. ”Använd inte git push --force på main. Om du behöver återställa, använd git revert eller git reset på en feature branch.”

För varje avsnitt använder du principen ”kommando i stället för idé”. Agenten kommer att ignorera ”var försiktig med migreringar”. Den följer ”Kör alembic check före alembic upgrade head. Om det rapporterar ett fel ska du inte tillämpa migreringen; fråga mig.”

Färdig AGENTS.md-mall att använda (kopiera och anpassa)#

# AGENTS.md

## Projektöversikt

<project-name> - <one phrase describing its purpose>.
Stack: <Next.js / Python / Go / ...>.
Main entities: <users, orders, posts ...>.
Details for people are in README.md.

## Installationskommandon

```bash
# första installationen
npm install
cp .env.example .env  # fyll sedan i manuellt; se listan nedan

# starta
npm run dev           # utvecklingsserver på :3000
npm run build         # produktionsbygge
npm run start         # kör produktionsbygget
```

## Utvecklingsmiljö

- Node 20+ (via nvm: `nvm use 20`)
- PostgreSQL 16 lokalt på :5432 (`docker-compose up postgres`)
- Redis är valfritt, behövs bara för köer (`docker-compose up redis`)
- `.env`: `DATABASE_URL`, `STRIPE_KEY`, `RESEND_API_KEY`, `JWT_SECRET`
- Läs aldrig hela `.env`-filen. Om du behöver en variabel: `grep "^VAR=" .env`

## Kodstil

- TypeScript strict mode
- Enkla citationstecken, inga semikolon (om inte ESLint kräver det)
- Importer: externa först, sedan interna via `@/`, därefter relativa
- Komponenter i PascalCase; hooks börjar med `use`
- Ingen `any` utan en uttrycklig kommentar som förklarar ”varför det inte går att typsätta”

Exempel på en bra modul:

```ts
import { z } from 'zod'

const UserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2),
})

export function parseUser(raw: unknown) {
  return UserSchema.parse(raw)
}
```

## Testning

```bash
npm test                                # alla tester
npm test -- --testPathPattern=auth      # endast auth
npm test -- --watch                     # bevakningsläge
```

Alla tester måste vara godkända (gröna) före commit. Om ett test är rött ska du inte committa; fråga mig vad du ska göra.

## Riktlinjer för pull requests

- Commitformat: `<type>(<scope>): <description>` (`feat(auth): add magic-link`)
- Före PR: `npm run build && npm test && npm run lint`
- PR-beskrivning = vad som ändras, varför och hur det testas
- Godkänn inte din egen PR – vänta alltid på mänsklig granskning

## Säkerhet

- Hemligheter endast i `.env` och Vault, aldrig i koden
- Logga inte personuppgifter (e-post, telefon, namn)
- Vid arbete med produktionsdatabasen, använd endast läsfrågor om du inte fått uttryckligt tillstånd
- Hårdkoda inte API-nycklar till externa tjänster (Stripe, OpenAI) i tester

## Gör aldrig detta

- Kör inte `git push --force` till main. Om du behöver återställa, använd `git revert` eller öppna en ny PR
- Kör inte databasmigreringar utan `alembic check` (eller motsvarande i din ORM)
- Använd inte `npm install -g` eller `sudo` för projektberoenden
- Lägg inte till beroenden utan godkännande (särskilt tunga sådana: webpack-plugins, ORM)

I genomsnitt är mallen 80–120 rader. Om filen överstiger 150 rader är det en signal att omstrukturera: flytta något till docs/, länka till något eller komprimera något till en rad. I praktiken fungerar filer på 100–150 rader bäst; efter den punkten börjar kvalitetsvinsterna vända.

Vilka 5 regler gör AGENTS.md verkligt användbar?#

1. Kommandon i stället för idéer. En agent förstår inte ”var försiktig med migreringar”. Den följer alembic check före alembic upgrade head. Agenter arbetar med kommandon och villkor, inte stämningar. Formulera alla centrala regler som ”gör X, annars Y”.

2. Förbud med ett alternativ. Ett ensamt ”gör ingen force push” ignoreras tyst av agenten efter två eller tre promptar. Kombinationen ”gör inte X; gör Y i stället” fungerar. Exempel: ”använd inte git push --force på main; om du behöver återställa, använd git revert eller öppna en ny PR.”

3. Exakt en källa till sanningen. AGENTS.md i roten är källa till sanningen för hela projektet. Om du har ett monorepo använder du nästlade AGENTS.md-filer i undermappar enligt regeln ”den närmaste vinner”. Inga parallella filer med motstridiga instruktioner.

4. Verifierbara kriterier för när arbetet är klart. ”Tester måste vara godkända” är oanvändbart. Ett exakt kriterium är: npm test returnerar avslutningskod 0 och skriver inte ut FAIL till stdout. ”Koden ska vara snygg” är också oanvändbart. Ett exakt kriterium är: npm run lint körs utan varningar. En agent förstår vad ”klart” betyder bara när du uttryckligen beskriver villkoret.

5. En fil på färre än 150 rader. Efter 150 rader börjar mätvärdena försämras: agenten lägger mer kontext på att läsa och missar viktiga regler. Om allt inte ryms flyttar du detaljerna till docs/architecture.md och länkar till den från AGENTS.md, så att bara kommandon och gränser blir kvar i filen.

Vilka 10 misstag gör AGENTS.md till skräp?#

1. Luddiga regler utan kommandon. Agenten kommer att ignorera ”var försiktig med migreringar” – den meningen betyder ingenting för den. Bara ett konkret kommando med ett villkor fungerar: ”Kör alembic check före alembic upgrade head. Om det finns ett fel ska du inte tillämpa migreringen; fråga mig.”

2. ”Ren kod.” En oanvändbar fras. Ersätt den med ett specifikt mönster: ”Använd funktionella komponenter med hooks. Exempel: function LoginForm() { const [email, setEmail] = useState(''); ... }”

3. Ostrukturerad prosa. Om AGENTS.md består av 300 rader prosa utan rubriker lägger agenten 80K kontexttokens på irrelevanta avsnitt och missar det viktiga. Använd H2/H3-rubriker, korta avsnitt och punktlistor.

4. En fil som är längre än 150 rader. Kvalitetsmåtten försämras efter den gränsen. Dela upp den i en huvudfil och länkar till detaljer i docs/.

5. 30+ förbud utan alternativ. Om filen har en lång lista med ”gör inte X, gör inte Y” utan att förklara ”gör Z i stället” kommer agenten att famla i blindo.

6. Duplicering av README.md. Om du redan har skrivit ”så här installerar och kör man” i README ska du inte kopiera det till AGENTS.md. Hänvisa i stället till README på en rad och beskriv i AGENTS.md vad agenten behöver veta men mänskliga bidragsgivare inte behöver.

7. Hårdkodade hemligheter. AGENTS.md kan vara offentlig (den finns i git). Inga riktiga API-nycklar, token eller lösenord. Bara hänvisningar till hemlighetslagring: ”Se Vault: secret/staging/db.”

8. Motstridiga prioriteringar utan rangordning. ”Jobba snabbt” + ”behåll 90% testtäckning” gör agenten osäker på vad den ska välja. Rangordna dem uttryckligen: ”Testtäckning ≥80% först, sedan hastighet. Om de krockar prioriteras testerna.”

9. Inaktuell dokumentation. En arkitekturbeskrivning som säger REST+polling när verkligheten redan är WebSockets. Agenten följer den inaktuella beskrivningen och förstör arkitekturen. Regel: uppdatera AGENTS.md i samma PR som koden när arkitekturen ändras.

10. Arkitektoniska överdrifter för en enkel uppgift. Om någon bad om att ändra två rader i en konfiguration ska agenten inte behöva läsa hela topologin för 14 mikrotjänster. Flytta den ”djupa” arkitekturen till docs/architecture.md; låt AGENTS.md bara säga ”om uppgiften gäller arkitekturen, läs docs/architecture.md”.

I GitHub Blogs studie av över 2 500 AGENTS.md-arkiv står huvudslutsatsen:

”De flesta agentfiler misslyckas för att de är alltför allmänna. ’You are a helpful coding assistant’ fungerar inte.”

(GitHub Blog, översatt från engelska)

Hur håller man AGENTS.md och CLAUDE.md i samma arkiv?#

Den viktigaste praktiska frågan är hur man kan ha båda filerna utan att duplicera innehåll. Tre scenarier:

Scenario 1: Bara Claude Code. Behåll CLAUDE.md och använd alla Claude Codes funktioner: ~/.claude/CLAUDE.md för instruktioner på användarnivå, CLAUDE.md för projektet, CLAUDE.local.md för personliga överstyrningar, @import för att inkludera andra filer och .claude/skills/ för specialiserade färdigheter. AGENTS.md behövs inte.

Scenario 2: Flera kodklienter. Behåll gemensamma regler i AGENTS.md och anslut och kontrollera varje klient för sig. Gemini CLI stöder ett konfigurerat filnamn för kontext; Aider kan läsa en fil via sin läskonfiguration. Det är uttryckliga inläsningsvägar, inte likadan automatisk upptäckt.

Starta en ny session i ett ofarligt testrepo med en unik, ofarlig instruktion som ”ta med markören instructions-loaded i testsvaret”. Granska både klientens dokumenterade vy över inlästa filer eller loggar och dess svar. Upprepa för varje klient och version du faktiskt använder. Ett genererat påstående om att filen lästes är inget oberoende bevis; ett lyckat test bevisar inte stöd i alla andra verktyg.

Scenario 3: Ett blandat team (Claude Code + andra). Det här är den vanligaste uppsättningen 2026. Lösningen är att göra AGENTS.md till primär fil. Om du inte har regler som bara gäller Claude Code ska du inte skapa någon CLAUDE.md alls: sedan version 2.1.277 läser Claude Code AGENTS.md när det inte finns någon CLAUDE.md i projektet. Om du har sådana regler gör du CLAUDE.md till en symlänk eller en kort omslagsfil med importen @AGENTS.md.

Granska och säkerhetskopiera båda filerna före ändring. Om båda finns sammanför du gemensamma regler utan konflikt i AGENTS.md och behåller Claude-specifika instruktioner i CLAUDE.md med importen @AGENTS.md. Bevara befintliga symboliska länkar i stället för att ersätta dem.

För en vanlig CLAUDE.md bara när AGENTS.md saknas vägrar följande macOS/Linux-skalvillkor skriva över befintligt mål eller symbolisk länk:

if [ -e AGENTS.md ] || [ -L AGENTS.md ]; then
  printf '%s\n' 'STOP: AGENTS.md exists; merge both files first.' >&2
elif [ -f CLAUDE.md ] && [ ! -L CLAUDE.md ]; then
  mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md
else
  printf '%s\n' 'STOP: inspect the existing CLAUDE.md path first.' >&2
fi

Efter lyckat namnbyte är CLAUDE.md en symbolisk länk till AGENTS.md. Alla agenter som läser AGENTS.md ser samma innehåll. Claude Code, som läser CLAUDE.md, ser samma sak via symlänken.

I Windows kräver det att skapa en symlänk Developer Mode (eller administratörsbehörighet), vilket kan vara opraktiskt för hela teamet. Ett alternativ är en kort CLAUDE.md som importerar AGENTS.md:

# CLAUDE.md

@AGENTS.md

## Claude Code-specifikt

- Använd .claude/skills/ för specialiserade promptar
- När du arbetar med Skills, konsultera .claude/skills/INDEX.md
- Använd Plan Mode före större ändringar (Shift+Tab)

I Claude Code hämtar den här syntaxen in AGENTS.md med en rad och lägger till Claude Code-specifika tillägg nedanför. Om du senare vill ta bort AGENTS.md tar du bara bort importen. Den här raden leder inte till dubbel inläsning: enligt Claude Codes dokumentation laddar den inte samma AGENTS.md två gånger, även om den kan läsa den på egen hand.

Kanonisk struktur för ett team med flera verktyg 2026:

repo-root/
├── AGENTS.md                              # källa till sanningen, ≤150 rader
├── CLAUDE.md                              # bara om det finns Claude-specifika regler: symlänk → AGENTS.md ELLER @AGENTS.md + tillägg
├── .cursor/rules/                         # riktade överstyrningar bara för Cursor
├── .github/copilot-instructions.md        # ”Se AGENTS.md”, om den används
└── docs/architecture.md                   # djupgående arkitektur som AGENTS.md hänvisar till

Mer om CLAUDE.md finns i guiden ”Så konfigurerar du CLAUDE.md korrekt”. Läs ”Vad är kontextteknik” för mer om varför en agent behöver en omfattande instruktionsfil.

Vad ändrades 2026: varför förde AAIF AGENTS.md till Linux Foundation?#

Den viktigaste politiska AI-berättelsen i maj 2026 var inte ännu en modellrelease, utan konsolideringen av format. Tidigare hade varje leverantör sin egen regelfil, vilket var bekvämt för leverantörerna men besvärligt för team som arbetade med flera verktyg.

I ett pressmeddelande daterat den 9 december 2025 tillkännagav Linux Foundation Agentic AI Foundation som ett paraply för tre format:

• AGENTS.md från OpenAI – ett instruktionsfilformat för agenter
• Model Context Protocol (MCP) från Anthropic – ett protokoll för att koppla externa verktyg till agenter
• goose från Block – ett ramverk med öppen källkod för agenter

Från Linux Foundations pressmeddelande:

”Genom att samla dessa projekt under AAIF-paraplyet säkerställer vi att de kan utvecklas med den transparens och stabilitet som bara öppen styrning ger.”

(Linux Foundations pressmeddelande, 9 december 2025, översatt från engelska)

Den 24 februari 2026 tillhörde 146 organisationer AAIF (97 nya medlemmar på två månader). Bland de nya guldmedlemmarna fanns Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, Hitachi, UiPath, American Express och Autodesk. Anthropic är på platinumnivå och driver MCP. OpenAI är på platinumnivå och driver AGENTS.md. Block är på platinumnivå med goose.

Det här förändrar AGENTS.md:s position: från ett ”OpenAI-format” till en branschstandard. Våren 2026 stod Claude Code fortfarande vid sidan av, men i september lärde den sig, med version 2.1.277, att läsa AGENTS.md på egen hand. CLAUDE.md har inte försvunnit och har fortfarande företräde som standard om den finns i projektet.

En praktisk utgångspunkt är gemensamma projektregler i AGENTS.md samt den import, omslagsfil eller uttryckliga läskonfiguration varje klient kräver. För Claude Code kontrollerar du installerad version och instruktionsfilernas företräde innan du avgör om en CLAUDE.md-import eller symlänk behövs. Verifiera inläsningen i varje klient; någon täckningsprocent har inte fastställts här.

Vad händer härnäst?#

AGENTS.md är den första byggstenen i ”hur man kommer överens med en agent så att den arbetar förutsägbart”. Nästa är en kunskapsmapp för projektet, som innehåller affärskontext, målgrupp, produkter och priser. Den tredje byggstenen är kontextteknik, som samlar allt: vilka filer agenten ser i varje steg, hur tillstånd bevaras mellan sessioner och hur man växlar mellan olika modeller.

Praktiskt material: Ailoot-dokumentation.

Fler material och verktyg: Ailoot.