Modul 4 – AGENTS.md och agentdesign

OpenCode-utbildningen på AIWiki.se ← Tillbaka till översikten

AGENTS.md är ett Markdown-baserat konfigurationsformat som styr hur en AI-agent ska bete sig i ett givet repo eller katalog. Det är inte:

En prompt (även om det innehåller instruktioner)
En konfigurationsfil i traditionell mening (JSON/YAML)
Dokumentation för människor (även om det är läsbart för dem)

Det är ett styrande dokument för maskiner – en deklaration av avsikt, begränsningar och beteende som agenten läser och följer.

Arkitektparallell: Tänk på AGENTS.md som ett Architecture Decision Record (ADR) kombinerat med ett API-kontrakt. Det dokumenterar beslut (vilken modell, vilka verktyg) och specificerar gränser (vad som är tillåtet).

AGENTS.md-filer söks i en hierarkisk ordning. Varje nivå kan utöka eller överskriva föregående:

Prioritetsordning (lägst → högst):

  ~/.opencode/AGENTS.md          (1) Globalt – gäller alla projekt
  ~/projekt/AGENTS.md            (2) Repo-rot – gäller hela projektet
  ~/projekt/src/AGENTS.md        (3) Underkatalog – gäller src/
  ~/projekt/src/api/AGENTS.md    (4) Djupare nivå – gäller src/api/

En agent som arbetar i ``src/api/`` läser alla fyra filerna och slår ihop dem med prioritet nedåt i hierarkin. Det innebär att du kan definiera globala kodkonventioner på toppnivå och specialiserade regler per komponent djupare ner.

En AGENTS.md-fil är ett Markdown-dokument med valfri YAML front matter och fri textsektion:

---
model: claude-sonnet-4-5
max_steps: 20
tools:
  - read_file
  - write_file
  - run_command
  - search_code
permissions:
  allow:
    - read: "src/**"
    - write: "src/**"
    - run: "npm test"
  ask:
    - write: "package.json"
    - run: "npm install *"
  deny:
    - write: ".env*"
    - run: "rm -rf *"
---
 
# Agent: Backend API

Du arbetar med backend-API:et för produkten. Följ dessa riktlinjer:

- Alla nya endpoints dokumenteras med JSDoc.
- Valideringslogik placeras i `src/validators/`.
- Inga direkta databasanrop i route-handlers – använd service-lagret.
- Felhantering via `AppError`-klassen i `src/utils/errors.ts`.

Fält	Typ	Beskrivning
``model``	string	Vilken LLM-modell agenten använder
``max_steps``	integer	Maximalt antal steg per körning
``tools``	lista	Vilka verktyg agenten har tillgång till
``permissions.allow``	lista	Vad agenten får göra utan att fråga
``permissions.ask``	lista	Vad agenten ska fråga om innan den gör
``permissions.deny``	lista	Vad agenten aldrig får göra
``agents``	lista	Sub-agenter denna agent kan delegera till

Behörighetsmodellen är det viktigaste säkerhetskontrollen i AGENTS.md. Den fungerar som ett lager-3-filter:

Inkommande handling → deny? → STOPPA
                    → ask?  → FRÅGA ANVÄNDAREN
                    → allow? → TILLÅT
                    → (implicit) → FRÅGA ANVÄNDAREN

Bästa praxis:

Börja med restriktivt – lägg till behörigheter när du ser att du behöver dem.
Lägg alltid ``.env*`` och hemligheter i deny-listan.
Använd ask för destruktiva operationer (delete, package-ändringar).
Specifika glob-mönster är bättre än breda wildcards.

Ett vanligt och effektivt mönster är att definiera separata agenter per domänansvarsområde:

projekt/
├── AGENTS.md                    ← Globala standarder, modellval
├── src/
│   ├── backend/
│   │   └── AGENTS.md            ← Backend-agent: databas, API, tjänster
│   ├── frontend/
│   │   └── AGENTS.md            ← Frontend-agent: komponenter, stilar
│   └── integrations/
│       └── AGENTS.md            ← Integrationsagent: API-anrop, adaptrar
└── docs/
    └── AGENTS.md                ← Dokumentationsagent: README, OpenAPI

Varje domänagent:

Känner till sin domäns konventioner och mönster
Har minimala behörigheter (principen om minsta privilegium)
Kan specificera en annan modell om det är lämpligt (t.ex. en billigare modell för dokumentation)

---
model: claude-sonnet-4-5
max_steps: 15
tools:
  - read_file
  - write_file
  - search_code
  - run_command
permissions:
  allow:
    - read: "src/backend/**"
    - write: "src/backend/**"
    - run: "npm run test:backend"
  ask:
    - write: "src/backend/migrations/**"
  deny:
    - write: "src/frontend/**"
    - write: ".env*"
---
 
# Backend-agent
 
Ansvarar för API-lager, tjänster och databaslogik. TypeScript strict mode.
Alla databasmigrationer granskas manuellt – fråga alltid innan du skriver dem.

---
model: claude-haiku-4-5
max_steps: 30
tools:
  - read_file
  - write_file
  - search_code
permissions:
  allow:
    - read: "**"
    - write: "docs/**"
    - write: "**/*.md"
  deny:
    - write: "src/**"
    - run: "*"
---
 
# Dokumentationsagent
 
Läser kod och skriver dokumentation. Får aldrig modifiera källkod.
Dokumentation skrivs på svenska för interna dokument, engelska för API-docs.

AGENTS.md-filer ska versionshanteras i git precis som all annan konfiguration:

Checka in dem i repot – de är en del av projektets styrning.
Granska ändringar i AGENTS.md i code review, inte bara källkoden.
Använd git blame för att spåra varför en viss behörighet lades till.

AGENTS.md är ett styrande dokument som definierar agentens beteende, verktyg och behörigheter.
Hierarkisk sökning möjliggör global + projektspecifik + komponentspecifik konfiguration.
Behörighetsmodellen (allow/ask/deny) är det primära säkerhetskontrollen.
Domänbaserade agenter är ett skalbart mönster för komplexa projekt.
Versionshanta AGENTS.md – det är infrastruktur, inte bara konfiguration.

Kopierad!

AI Prompt: Skriv AGENTS.md för ett kafé

Du ska skriva en AGENTS.md för en fiktiv espressomaskin som är konfigurerad som en AI-agent. Definiera dess verktyg (tools), vad den alltid får göra (allow), vad den måste fråga om (ask) och vad den aldrig under några omständigheter får göra (deny). Var specifik. Kaffet beror på det.

Testa prompt på …