SK
Sundsvalls kommun · Digital utveckling
PLAN · AI-ASSISTERAD NYUTVECKLING · 2026
Plan i fyra byggblock och tre faser

Från prompt till produktionsmönster

Målet: en utvecklare ska kunna säga ”bygg en ny app för X” till Claude Code och få en applikation som är korrekt från första commit — rätt arkitektur, rätt designsystem, rätt mönster. Ingen mänsklig kunskapsöverföring i mellanled. Den här sidan beskriver hur vi tar oss dit, steg för steg.

Utgångsläget

Vi har halva lösningen — kartan finns, men inte vägvisarna

Analysen av organisationens repon visar en ovanligt konsekvent grund att bygga på. Det som saknas är inte mönster — det är att göra mönstren tillgängliga och verifierbara för en AI-agent.

Detta finns redan

Och återanvänds rakt av i planen.

  • web-app-starter — komplett mall med frontend (Next.js, React), BFF-backend (Express, SAML, Prisma) och admin. Varje ny app föds härifrån.
  • ui.sundsvall.dev — en experimentell, AI-vänlig front till vårt webbramverk som Jari Koponen tagit fram för att testa idén: designsystemportal med llms.txt, llms-full.txt och markdown-varianter per sida. Lovande som proof of concept — men behöver lyftas in i en långsiktigt hållbar lösning.
  • @sk-web-gui — 66 komponenter + 19 AI-komponenter, tokens och Tailwind-preset via npm.
  • Tydliga konventioner — BFF-mönstret, generate:contracts, Zustand-services, namnstandarden web-app-* / api-service-*.
  • Riktlinjer — öppen källkod (MIT), parametriserad kod, tonalitet och WCAG 2.2 AA.

Detta saknas för en AI-agent

Gapen som planen stänger.

  • Ingen agentfil — varken AGENTS.md (den verktygsoberoende standarden) eller CLAUDE.md finns i något repo. Agenten öppnar ett projekt utan kontext.
  • Implicit arkitektur — BFF, WSO2, SAML-flödet och contracts-kedjan måste härledas ur kod.
  • Motstridiga signaler — olika repon visar olika router-val och olika sk-web-gui-versioner. Vad är standard nu?
  • Ingen API-katalog — ~60 mikrotjänster finns, men ingen maskinläsbar översikt över vad de gör.
  • Inga skyddsräcken — designsystemets viktigaste regel (inga hårdkodade färgvärden) kontrolleras inte maskinellt, och inget kör verifieringen automatiskt åt agenten.
  • Ingen governance — inga förgodkända kommandon, ingen sandbox och inga spärrar mot känsliga sökvägar. Avgörande när agenter rör medborgardata.
Tre bärande principer

Reglerna bakom alla beslut i planen

Princip 1

Det som kan lintas ska lintas

AI-agenter följer feedbackloopar betydligt mer pålitligt än instruktionstext. Regler som kan kodas i ESLint, type-check eller CI ska inte stå i prosa. Dokumentationen förklarar hur man gör rätt; verktygen gör det omöjligt att göra fel utan att märka det. Hooks är den körbara formen av detta — konfiguration som kör kontrollerna åt agenten, inte ett LLM-godtycke.

Princip 2

En regel, en källa

Varje regel ägs av exakt ett ställe — startern, designsystemportalen eller arkitekturdokumentationen. Allt annat länkar dit. Duplicerad text driver isär och lär agenten motstridiga saker.

Princip 3

Exempel slår prosa

Claude Code lär sig mer av en fläckfri förebild i koden än av tio stycken beskrivning. Kanoniska, kommenterade exempel i startern är dokumentation som aldrig kan bli inaktuell utan att lint och test säger ifrån.

Planens kärna

Fyra byggblock — i den ordning de bygger på varandra

Blocken är sekventiella med flit: standarderna i block 1 är förutsättningen för skyddsräckena i block 2, som tillsammans med kontexten i block 3 paketeras i block 4.

Byggblock 1 · Fundamentet

Gör web-app-starter till den auktoritativa källan

Startern är navet i hela lösningen. Eftersom varje ny app skapas via npx tiged från den, sprids allt som ligger där automatiskt till varje nytt projekt — utan utrullning, utan migrering.

1a · Fatta standardbesluten

Innan något dokumenteras måste startern entydigt representera nuvarande standard: App Router eller Pages Router, aktuella sk-web-gui-versioner, samlingspaket eller enskilda paket, pinnade eller caret-versioner. För nya appar räcker det att startern är rätt — och att besluten är nedskrivna.

1b · Skriv agentfilen i startern

Planens enskilt viktigaste fil. Skriv kanon i en verktygsoberoende AGENTS.md och låt CLAUDE.md importera den (@AGENTS.md) — då fungerar samma kontext i Claude Code, Cursor och andra agenter utan inlåsning. Innehåll: arkitekturöversikten (BFF-mönstret, varför frontend aldrig anropar mikrotjänster direkt, WSO2-flödet), alla kommandon, mappkonventionerna, proceduren för att koppla på ett nytt API (README-tabell → api-config.ts → generate:contracts), SAML-utveckling mot fake-sso-idp, samt grundreglerna från ui.sundsvall.dev. Plus en markerad sektion som fylls i per app: namn, syfte, API-tabell.

Håll filen kort (<200 rader): bryt ut områdesspecifika regler till path-scoped .claude/rules/ som bara laddas när agenten rör matchande filer, i stället för en växande monolit.

1c · Putsa de kanoniska exemplen

Gör starterns user-service och example-page till fläckfria, kommenterade mallar: service + Zustand-store, sida med i18n och layout, formulär med react-hook-form + yup + sk-web-gui, backend-controller med routing-controllers. Peka ut dem i CLAUDE.md: ”kopiera detta mönster”.

Därför förstAllt nedströms — skyddsräcken, skill, utvärdering — refererar till starterns innehåll. Är startern fel blir allt annat fel, fast snabbare.
Byggblock 2 · Skyddsräckena

Maskinella kontroller istället för instruktionstext

Här tillämpas princip 1. Varje regel som kan verifieras automatiskt flyttas från prosa till verktyg, så att Claude Code rättar sig självt medan det arbetar.

2a · ESLint-regel mot hårdkodade färger

En custom regel som förbjuder hex-värden och egendefinierade --color-*-variabler utanför node_modules. Designsystemets viktigaste princip — ”hårdkoda aldrig” — blir därmed omöjlig att bryta tyst.

2b · Skärpta regler i startern

no-explicit-any finns redan som error. Komplettera med importregler och en regel mot direkta fetch-/axios-anrop utanför den gemensamma apiService.

2c · Ett samlat verifieringskommando

yarn verify = lint + type-check + test. Samma kommando ligger i CI-mallen som följer med startern — och körs åt agenten via en hook (2d) i stället för att enbart stå som en instruktion.

2d · Hooks som kör kontrollerna automatiskt

Hooks i starterns .claude/settings.json är skillnaden mellan ”agenten bör köra verify” och ”verify körs”. En PreToolUse-hook kan stoppa en ändring som inför hårdkodade färger innan den sparas; en Stop-hook kan kräva grön yarn verify innan agenten får avsluta sitt varv. Deterministiskt, inte beroende av att modellen kommer ihåg. ESLint är regeln — hooken är körningen.

EffektenAgenten får samma omedelbara återkoppling som en senior kollega skulle ge i kodgranskning — fast vid varje fil-spar, inte vid varje pull request, och utan att någon behöver lita på att den valde att köra kontrollen.
Byggblock 3 · Kontexten

Kunskap på begäran: designsystem och API-katalog

CLAUDE.md ska vara kort. Djupkunskapen — komponenters props, tokens, tjänstekatalogen — hämtas i stunden, exakt när agenten behöver den. Halva lösningen finns redan i ui.sundsvall.dev — i dag ett experiment, framåt en del av den ordinarie, förvaltade plattformen.

3a · MCP-server mot designsystemet

Den experimentella portalen har redan markdown-endpoints per komponent, så steget är kort. Verktyg som sök_komponent, hämta_tokens och lista_ai_komponenter låter agenten hämta rätt dokumentation utan att svälja hela llms-full.txt. MCP ger mer än verktyg — exponera komponentdokar som resources och färdiga arbetsflöden som prompts, så agenten kan referera dem direkt. Servern förkonfigureras i starterns .mcp.json — varje nytt projekt är anslutet från start. Att bygga MCP-servern ovanpå portalen är också det som tar den från proof of concept till något appar faktiskt kan luta sig mot.

3b · Maskinläsbar API-katalog

Det största kunskapsgapet vid nybygge är ”vilka mikrotjänster finns och vad gör de?”. Generera en katalog från repo-beskrivningar och OpenAPI-specar för de ~60 api-service-*-tjänsterna: namn, version, syfte, viktigaste endpoints. Då kan agenten själv föreslå ”för detta behöver du CaseData och Messaging” och fylla i api-config.ts korrekt.

3c · Arkitektursidor på portalen

Komplettera ui.sundsvall.dev med sidorna som saknas för nyutveckling: BFF-arkitekturen, contracts-flödet, auth-flödet, namnkonventionerna. Samma publiceringsteknik som redan finns — md-varianter, llms.txt, no-cache. I samma veva bör portalens experimentstatus formaliseras: ägarskap, drift och förvaltning så att den blir en stabil del av plattformen, inte en sidoprodukt.

Genererat, inte handskrivetKatalogen och komponentdokumentationen byggs i CI från källorna — då kan dokumentationen aldrig ljuga om verkligheten.
Byggblock 4 · Paketeringen

Allt som en plugin: skapa-sundsvall-app

Knyt ihop allt i en plugin — inte bara en lös skill — som bundlar skapandeflödet, domänskills, granskar-subagents, hooks och .mcp.json i ett versionerat paket. Distribuera via en intern marketplace så att en utvecklare installerar hela verktygslådan med /plugin add, och stäng av den lika lätt. Skillarna skrivs enligt den öppna Agent Skills-specen, vilket gör dem portabla över Claude Code, Cursor och andra agenter.

Scaffold-skillen: proceduren steg för steg

Scaffolda via tiged från startern → initiera git → fyll i appnamn och syfte i agentfilen → fråga vilka API:er som behövs (slå upp i katalogen) → uppdatera api-config.ts och README-tabellen → sätt upp .env-filer från exempel → kör generate:contracts → verifiera med yarn verify.

Domänskills med progressive disclosure

Utöver scaffold-skillen: små, fokuserade skills som api-konventioner, säkerhetschecklista och tillgänglighet. Bara namn + beskrivning laddas i förväg; hela innehållet hämtas först när det behövs — djup kunskap utan att tynga kontexten.

Granskar-subagents i paketet

Specialiserade subagents i .claude/agents/ — en för tillgänglighet, en för designsystemsefterlevnad, en för säkerhet — som arbetar i eget kontextfönster och kan kallas in för granskning utan att belamra huvudsessionen.

Dubbel nytta

Pluginen blir samtidigt den mänskliga dokumentationen av flödet — proceduren som en ny utvecklare läser är exakt samma som agenten följer. En källa, två läsare.

Förtroende & efterlevnad

Governance: trygg automatik för en kommun

En agent som bygger appar i offentlig sektor måste ha tydliga gränser. Det här lagret gör autonomin trygg — och är en förutsättning för att lösningen ska bli långsiktigt hållbar och klara dataskyddskrav, inte bara ett experiment på en enskild dator.

Lager 1

Förgodkända kommandon

En allowlist i settings.json låter agenten köra säkra kommandon — git, lint, test, generate:contracts — utan att fråga, men stoppas vid allt utanför listan. Mindre friktion, tydligare gräns.

Lager 2

Sandbox för fil och nät

Agenten läser och skriver bara i projektmappen och når bara godkända domäner. Ett OS-nivåskydd som gäller även om en instruktion skulle säga annat — inte beroende av modellens omdöme.

Lager 3

Spärrar & managed settings

Deny-regler mot känsliga sökvägar (medborgardata) och centralt utrullade managed settings som IT äger och som inte kan kringgås lokalt. En policy, hela organisationen.

Tidslinje

Tre faser till mål — och en fjärde som blir billig på köpet

Fas 1

Fundamentet

1–2 veckor
  • Standardbeslut (router, versioner)
  • AGENTS.md + CLAUDE.md i startern
  • Putsade kanoniska exempel
  • yarn verify + första hooks
Fas 2

Räcken & kontext

3–6 veckor
  • ESLint + hooks (blockerar, kör verify)
  • MCP-server & arkitektursidor på portalen
  • Governance: permissions & sandbox
  • Första versionen av API-katalogen
Fas 3

Paketering

Löpande
  • Plugin + intern marketplace
  • Domänskills & granskar-subagents
  • Eval-harness i CI (pass^k) + telemetri
  • Autogenererad API-katalog i CI
Fas 4 · Senare

Befintliga appar

Utanför fokus nu
  • Plugin, agentfil, hooks och MCP-server finns då redan
  • Anpassningen blir installation, inte nyutveckling
Så vet vi att det fungerar

En eval-harness, inte en känsla

Behandla agentens instruktioner som en produkt med ett testsvit. Efter varje fas körs samma referensuppgifter mot lösningen och bedöms automatiskt: kodbaserade graders (kör yarn verify, räknar hex-värden) plus modellbaserade graders för det öppna (”följer detta konventionerna?”). Kör i CI, mät pass^k — att alla försök lyckas, inte bara något — och följ siffran över faserna för att se om kontextarbetet faktiskt höjer kvaliteten.

Referensuppgifter (3–5 st)

Exempel A

”Skapa en ny app som visar ärendestatus från CaseStatus, med en formulärsida för att begära uppdatering.”

Exempel B

”Lägg till en tabellvy med paginering över fakturor från Invoices, med sökfält och svensk datumformatering.”

Exempel C

”Koppla på Messaging-API:et och bygg ett flöde där en handläggare skickar ett meddelande till en medborgare.”

Bedömningschecklista

  • Rätt scaffold och mappstruktur från startern
  • Inga hex-värden — allt via @sk-web-gui
  • Contracts-flödet använt, inga handskrivna typer
  • API:er deklarerade i api-config.ts och README
  • Service + Zustand-store enligt mönstret
  • Svenska, du-tilltal, imperativ på knappar
  • Semantisk HTML, synlig fokus, label på fält
  • Grön yarn verify — lint, typer, test
Automatik + observerbarhetChecklistan körs inte för hand i längden — granskar-subagents (tillgänglighet, designsystem, säkerhet) gör bedömningen, och telemetri via OpenTelemetry mäter hur agenten faktiskt lyckas i skarp drift. Spårning av flöde och utfall, utan att logga innehållet.