Smärtpunkten: varför AI-kodning alltid spårar ur på samma ställe

Den som använder Cursor, Windsurf eller Claude Code har nästan alltid upplevt samma krasch: AI:n spottar ur sig en hel kodblock, du klistrar in det och kör — bygget går sönder, testerna blir röda, beroenden hamnar fel. Problemet sitter inte i AI:ns intelligens utan i att den inte känner till projektets “oskrivna regler”.

AGENTS.md är en Markdown-fil i projektroten, skriven direkt för AI:n. Den talar om hur man bygger, hur man testar, vilka konventioner som gäller. README.md är till för människor — proppfull med projektintro, bidragsguider och varumärkesberättelser. När AI:n läser det är det som att en nyanställd första dagen får en företagsbroschyr och sedan ombeds skriva kod direkt. Den vet vad bolaget gör, men inte byggkommandot, inte hur testerna körs, inte vilka ESLint-regler som gäller. Resultatet: varje gång måste du i chatten upprepa “använd pnpm, inte npm”, “testerna ligger under packages/web”, “glöm inte lint”. Upprepa det hundra gånger, projektet är fortfarande rörigt.

I frilanssammanhang är förlusten direkt. Du tar ett Next.js + Prisma-uppdrag, accelererar med Cursor, men AI:n kör npm install och pnpm:s workspace-konfig rasar. Den hittar inte ditt databasschema, migrationen kraschar direkt. Kunden jagar leverans, du lägger tre timmar på att debugga AI-genererad kod — surt för pengarna.

Tre typiska haverier när AI:n inte känner projektets regler: ① Fel pakethanterare (projektet kör pnpm, AI:n defaultar till npm install), beroenden hamnar fel, workspace-konfigen dör; ② Hittar inte testerna (projekttester ligger under packages/web, AI:n kör pnpm test i roten och får “inga testfiler hittades”); ③ Inkonsistent kodstil (projektet kör ESLint + Prettier, AI:n levererar kod med fel indentering och citattecken, CI:n går röd direkt).

Möjligheten: AGENTS.md separerar “människodokumentation” från “maskindokumentation”

Open source-projektet AGENTS.md på GitHub (repo github.com/agentsmd/agents.md, ca 24 000 stjärnor per 2026-08-25) löser just detta. Grundtanken är enkel: en Markdown-fil i projektroten som specifikt berättar för AI:n hur den bygger, testar och följer kodstil.

Det är inte en ersättning för README, utan ett komplement. README tjänar mänskliga bidragsgivare, AGENTS.md tjänar AI-agenterna. Skyldigheterna är tydliga, ingen krockar.

Enligt källan har AGENTS.md adopterats av tiotusentals open source-projekt (exakt siffra ej verifierad) och täcker VS Code, Cursor, Windsurf, Aider och GitHub Copilot (verifierat). Enligt community-feedback stödjer även OpenAI Codex och Google Jules formatet (⚠️ ej verifierat). Lär du dig inte nu låter du AI:n prata dialekt med dig.

Spår 1: skriv en minimal AGENTS.md för hand

Kostnaden är nära noll. Skapa en fil, skriv tre sektioner, sedan är du igång.

Förkunskap: exemplen nedan använder pnpm (sparar disk, stödjer monorepo workspace), turbo är monorepo-orkestrerare, --filter riktar kommandot mot ett specifikt delpaket så resten av repot lämnas ifred.

Sektion 1 “Dev environment tips”: berätta vilken pakethanterare som gäller, hur man hoppar mellan delpaket, hur man skapar nya moduler. Det officiella exemplet:

• pnpm dlx turbo run where <project_name> — hoppar rakt in i rätt delpaket utan att ls runt
• pnpm install --filter <project_name> — installerar bara beroenden för ett delpaket, inte hela monorepot
• pnpm create vite@latest <project_name> -- --template react-ts — skapar ett nytt React + Vite-paket med TypeScript-kontroll

Dessa kommandon gissar AI:n aldrig själv, men skriv ner dem så följer den dem.

Sektion 2 “Testing instructions”: berätta hur tester körs, var CI-pipelinen ligger, vilka checks som måste gå grönt innan commit. Det officiella exemplet:

• pnpm turbo run test --filter <project_name> — kör alla checks för ett delpaket
• pnpm vitest run -t "<test name>" — kör bara ett enskilt test som matchar namnet
• “Fix any test or type errors until the whole suite is green” — hela sviten måste vara grön
• “Add or update tests for the code you change, even if nobody asked” — den sista raden är nyckeln, utan den smiter AI:n ofta från testerna

Sektion 3 “PR instructions”: standardisera commit-titlar, tvinga fram lint och test. Det officiella exemplet är Title format: [<project_name>] <Title> samt “Always run pnpm lint and pnpm test before committing”.

Dessa tre sektioner tar under 50 rader men höjer andelen AI-kod som går igenom direkt märkbart (enligt community-feedback, exakt siffra saknas).

Spår 2: nästla AGENTS.md i stora monorepon

För dig som tar enterprise-uppdrag med monorepo-struktur (flera relaterade projekt i samma Git-repo, typ frontend, backend, delad kod i varsin underkatalog) räcker inte en enda AGENTS.md. AGENTS.md stödjer nästling: lägg en egen AGENTS.md i varje underkatalog, AI:n läser automatiskt den “närmaste”.

Praktiskt: AGENTS.md i roten beskriver globala regler (pakethanterare, CI-flöde, säkerhet), sedan lägger du en i packages/web/, packages/api/ och packages/shared/ med byggkommandon, testvägar och specialberoenden för just det delpaketet. Frontend-paketet behöver t.ex. “komponentbibliotek: shadcn, styling: Tailwind, ikoner: lucide-react”. Backend-paketet behöver “migrationer: Prisma, API-rutter under src/routes, auth: JWT”.

När AI:n jobbar i en underkatalog laddas den närmaste AGENTS.md automatiskt, med högre prioritet än roten. Det betyder att frontend-assistenten och backend-assistenten i samma projekt får helt olika instruktioner — ingen blandning.

Spår 3: gör det till en differentierad frilansfördel

Marknaden för AI-frilans är röd — alla kan Cursor, men leveranskvaliteten varierar enormt. Skriv en rad i offerten: “Projektet är konfigurerat med AGENTS.md-standard, AI-assisterad utveckling följer projektets regler.” Det slår konkurrenter som bara säger “jag kodar med AI”.

Spelet konkret: när du vunnit uppdraget, lägg 30 minuter på att läsa kundens projektstruktur och skriv en skräddarsydd AGENTS.md. Den filen är en del av leveransen — kunden kan sedan underhålla koden med AI utan friktion.

Prissätt AGENTS.md-konfiguration separat (anpassa efter lokal marknad): Bas ~700 kr (en fil + README-förklaring), Enterprise ~4 200 kr (monorepo-nästling + säkerhetsregler + teamutbildning). Leverans: ① Anpassad AGENTS.md ② 30 dagars frågesupport ③ 10 minuters skärminspelning. Passar: kunder som redan betalar för Cursor/Windsurf men inte får ut effekt. Passar inte: kunder som fortfarande kodar helt manuellt utan AI-verktyg.

Fallet: AGENTS.md:s kompatibilitetsfördel

AGENTS.md är MIT-licensierat (verifierat), community-underhållet (styrningsstruktur ej verifierad), webbplats agents.md.

Kompatibiliteten är dess största mur: VS Code, Cursor, Windsurf, Aider och GitHub Copilot läser alla AGENTS.md (verifierat). Enligt community-feedback stödjer även OpenAI Codex, Claude Code, Gemini CLI och Google Jules formatet (⚠️ ej verifierat). En fil, alla stora AI-assistenter — ingen separat konfig per verktyg.

Jämför med alternativen: Cursor:s .cursorrules funkar bara i Cursor, byter du till Windsurf är den värdelös. Claude Code:s CLAUDE.md tjänar bara Claude. GitHub Copilot har sitt eget instruktionssystem. AGENTS.md:s “skriv en gång, kör överallt” är anledningen till att det sprids så snabbt.

Noll migrationskostnad. Idag Cursor, imorgon Windsurf — AGENTS.md återanvänds rakt av, inga regler behöver skrivas om.

Handlingsuppmaning: ge ditt projekt en maskinmanual ikväll

5-minutterschecklistan: ① Öppna projektroten ② Skapa AGENTS.md ③ Kopiera den officiella mallen (github.com/agentsmd/agents.md) ④ Fyll i tre kommandon (build, test, lint) ⑤ Nästa gång du ber AI skriva kod, observera resultatet.

Kör du monorepo? Lägg 20 extra minuter ikväll på en nästlad AGENTS.md per delpaket. Imorgon morgon upptäcker du att AI-koden inte längre behöver ständiga rättelser.

AGENTS.md är just nu den AI-kodningskonfiguration med högst ROI — 30 minuters jobb, flera timmars debuggtid sparad varje månad.