Fra utdaterte dokumenter til levende standarder – slik gjorde vi retningslinjene AI-klare

I store IT-prosjekter finnes det ofte flere generasjoner med dokumentasjonsvaner. Dette prosjektet var intet unntak.
Kunden hadde detaljerte Confluence-sider om kodefilosofi, rammeverk og navnestandarder – godt ment, men lite brukt.
Sist oppdatert i 2020, og etter hvert mer et historisk arkiv enn et arbeidsverktøy.
Vi ønsket å endre dette.

Spørsmålet ble:

‍Hvordan kan vi få kunnskapen til å leve der utviklingen faktisk skjer – slik at den forblir nyttig for både utviklere og AI?

‍
Fra Confluence til kode

Løsningen var å flytte dokumentasjonen inn i repoet.
Vi brukte VS Code, GitHub og GitHub Copilot – men prinsippet kan brukes i ethvert miljø.
Confluence ble gjort om til Markdown-filer i .github/instructions, der Copilot automatisk finner dem.
De dekker både generelle prinsipper og prosjektspesifikke retningslinjer: hvordan vi navngir, strukturerer Apex-klasser, organiserer tester og dokumenterer kode.
Filene ligger nå ved siden av koden de beskriver, og brukes av både utviklere og Copilot i sanntid.

Gevinsten

• Mindre tid på onboarding - Nye utviklere får standardene servert automatisk i IDE-en
• Mer konsistent kodebase - Copilot følger samme retningslinjer for alle
• Mindre frustrasjon - Slipper å lete etter utdaterte Confluence-sider
• Lav kost - Krever bare Markdown-filer i repoet
• Høy ROI - Spare tid på hver PR, hver gang Copilot brukes

Innebygd forståelse

Hver instruksjonsfil starter med et lite hode som definerer hvor og når den gjelder:

---
description: "Apex code guidelines for consistent Apex classes"
applyTo: "**/*.cls"
---

## General Principles

- Place code into the correct **layer**: Callers, Services, Domains, Utilities, or Tests.
- Always use **Dependency Injection** and the **Factory Pattern**.
- Services are the main entry points and must be **caller-agnostic**.
- Triggers must follow the **Trigger Actions Framework**.
- Code should be organized to maximize testability and maintainability.- Follow rules in `.eslintrc.js`

Dette forteller Copilot hvilke filer retningslinjene gjelder for.
Når en utvikler jobber i en .cls-fil, følger Copilot automatisk disse standardene.
Strukturen er fleksibel – alt som versjoneres og gjennomgås som kode, fungerer.

Hva bør instruksjonsfilene dekke?

• Navnekonvensjoner (klasser, metoder, variabler)
• Arkitekturprinsipper (lag, dependency injection, patterns)
• Testing-standarder (coverage, naming, struktur)
• Sikkerhetskrav (SOQL injection, sharing rules)
• Dokumentasjonskrav (når/hvordan kommentere)
• Feilhåndtering og logging

‍

Ett sted for kode og kunnskap

Når dokumentasjonen ligger sammen med koden, får den mer kontekst og blir lettere å vedlikeholde.
Man slipper å bytte mellom kode og Confluence – alt redigeres samme sted.
Dette var god praksis før AI, men nå er det blitt avgjørende.
Instruksjonsfiler og dokumentasjon smelter sammen og dekker navnekonvensjoner, rammeverk og struktur – til nytte for både mennesker og AI.

‍
Alltid oppdatert

Når beste praksis lever der utviklingen skjer, oppdateres den naturlig.
Utviklere kan forbedre standardene mens de jobber.Hver endring gjør Copilot smartere og vedlikehold til en del av hverdagen.

‍
Dokumentasjon av pakker

Å beskrive pakker direkte i Markdown gjør hverdagen enklere.
En kort .md-fil som forklarer formål, avhengigheter og struktur hjelper Copilot og kolleger med å forstå helheten.
Et packages.md-kart samler alt i én oversikt – et levende kart over systemet.

‍

‍Fra lesing til handling

Instruksjonsfiler er aktive innganger hver gang Copilot brukes.
Når du ber Copilot om kode, leser den relevante .instruction.md-filer basert på konteksten.
For repeterende oppgaver bruker vi prompt-filer( .prompt.md ) som peker til instruksjonsfiler:

- Follow the instructions from [`test-guidelines.instructions.md`](../instructions/test-guidelines.instructions.md) to generate test classes.

Slik holdes veiledningen konsistent og lett tilgjengelig.

‍

Sanity Check-prompter

Lei av de samme tilbakemeldingene i hver PR?
Glemt debug-utskrifter, manglende kommentarer eller feil navn?
Vi laget en sanity-check-prompt for Copilot som kjøres før du sender inn koden.
Den finner vanlige feil og sparer tid for både utvikler og anmelder.

‍
Versjonskontroll gir tillit

Fordi standardene lever i Git, blir de versjonert og godkjent som kode.
Det er ikke lenger “noen oppdaterte wiki’en i fjor” – men “denne endringen ble merget med kontekst”.
Slik blir dokumentasjonen en pålitelig del av systemet.

‍
Tips for å komme i gang

Start smått – velg ett område som tester, navngivning eller struktur.
Teori gir retning, eksempler gjør det konkret.
Du kan bruke Copilot til å skrive om eksisterende Confluence-dokumentasjon, men vær kritisk – AI kan legge til troverdig, men irrelevant innhold.
Hold standardene nær koden og versjoner dem som alt annet – slik gjør du dokumentasjonen levende.

‍

‍

Bilde av Myburgh Roux