improve-codebase-architecture

name

improve-codebase-architecture

description

Bruk når brukeren vil forbedre arkitekturen, finne refaktoreringsmuligheter, gjøre grunne moduler dypere, konsolidere tett koblede moduler, eller gjøre Ktor-koden mer testbar og lettere å navigere for både folk og AI. Også når noen sier 'forbedre arkitekturen', 'finn refaktoreringsmuligheter', 'denne koden er rotete/vanskelig å teste', 'for mange tynne lag', eller 'rute → service → klient-kjedene er uoversiktlige'.

improve-codebase-architecture

Avdekk arkitektonisk friksjon i dette repoet og foreslå fordypningsmuligheter — refaktoreringer som gjør grunne moduler dype. Målet er testbarhet og at både mennesker og AI lett kan navigere koden.

Rolle: dette finner kandidater (oppdagelse). Designe grensesnittet på en valgt kandidat = /codebase-design; avhøre valget = /grill-with-docs; formalisere et tungt valg som ADR = /nav-architecture-review.

Skillen er informert av domenemodellen og besluttede valg, og bygger på et delt arkitekturvokabular:

• docs/glossary.md gir navn til gode sømmer i domenet; docs/context.md gir den valgte tilnærmingen; ADR-er i docs/adr/ er besluttede valg du ikke skal re-litigere uten grunn.
• Dette er @grillmester sin oppdagelsesfase: funn herfra mates inn i grilling (/grill-with-docs), plan (.grill/PLAN.md) og verifisering (.grill/VERIFICATION.md).

Vokabular

Dette bruker dyp-modul-vokabularet som /codebase-design eier — modul, grensesnitt, implementasjon, dybde (dyp/grunn), søm (seam, ikke «boundary»), adapter, lokalitet, leverage. Bruk ordene presist; ikke drift til «komponent», «service», «lag» eller «API». Full definisjon av hvert: /codebase-design.

Slettetesten (det operative verktøyet for oppdagelse): ville det å slette modulen konsentrere kompleksitet (bra — den var grunn) eller bare flytte den (da var den ekte)? Et «ja, konsentrerer» er signalet du jakter på.

Prosess

1. Utforsk

Les docs/context.md, docs/glossary.md og relevante ADR-er i docs/adr/ først.

Gå så gjennom kodebasen organisk — ikke følg rigide heuristikker. Noter hvor du opplever friksjon. I et Ktor-backend ser fordypningsmuligheter typisk slik ut:

• Tynne lag i kjede: Route { } → Service → Repository → klient der hvert ledd nesten bare videresender. Slå sammen til én dyp modul.
• DTO-mappere ekstrahert kun for testbarhet: toDto() / fromDb()-funksjoner som er rene, men der de ekte feilene sitter i hvordan de kalles (ingen lokalitet).
• Grunne klient-wrappere: en HttpClient-kall pakket i en klasse som ikke gjemmer noe — TokenX/Azure AD-token, retry og feilkontrakt lekker ut til kallstedet.
• Spredt Kafka-logikk: konsument, deserialisering, idempotens/replay-håndtering og forretningslogikk fordelt over flere moduler uten én søm.
• Lekkende databaselag: SQL/DataSource/Flyway-detaljer som siver ut av repository-modulen.
• Vanskelig å teste gjennom grensesnittet: moduler som krever oppspinning av halve Ktor-stacken for å testes — tegn på at sømmen sitter feil sted.

Bruk slettetesten på alt du mistenker er grunt.

2. Presenter kandidatene som en HTML-rapport

Skriv en selvstendig HTML-fil til OS-temp slik at ingenting havner i repoet. Resolv temp-katalog fra $TMPDIR med /tmp som fallback, og skriv til <tmpdir>/arkitektur-review-<timestamp>.html. Åpne den for brukeren (open <sti> på macOS, xdg-open <sti> på Linux) og oppgi den absolutte stien.

Hver kandidat får et kort med: Filer, Problem (én setning), Løsning (én setning), Gevinster (punktliste i vokabularet — lokalitet/leverage/testflate), Før/etter-diagram, og Anbefalingsstyrke (Sterk, Verdt å utforske, Spekulativ). Avslutt med en Topp-anbefaling: hvilken du ville tatt først og hvorfor.

Bruk docs/glossary.md-vokabular for domenet og arkitekturvokabularet over for strukturen. Heter konseptet "Sykmelding-inntak" i glossaret, snakk om "Sykmelding-inntak-modulen" — ikke "SykmeldingHandler" og ikke "Sykmelding-servicen".

ADR-konflikt: hvis en kandidat motsier en eksisterende ADR, ta den kun opp når friksjonen er ekte nok til å forsvare å gjenåpne valget. Merk det tydelig i kortet (gul callout: "motsier ADR-0007 — men verdt å gjenåpne fordi…"). Ikke list opp enhver teoretisk refaktorering en ADR forbyr.

Se HTML-REPORT.md for fullt HTML-stillas, diagrammønstre og stilguide.

Ikke foreslå konkrete grensesnitt ennå. Etter at fila er skrevet, spør brukeren: "Hvilken av disse vil du utforske?"

3. Grilling-løkke

Når brukeren har valgt en kandidat, kjør /grill-with-docs for å gå ned beslutningstreet sammen med dem — begrensninger, avhengigheter, formen på den fordypede modulen, hva som ligger bak sømmen, hvilke tester som overlever. Dette er @grillmester fase 1–2.

Sideeffekter skjer løpende mens beslutninger faller på plass:

• Navngir du en fordypet modul etter et konsept som ikke står i docs/glossary.md? Legg termen til der (bruk /domain-modeling). Opprett fila lazy hvis den mangler.
• Skjerper du en uklar term underveis? Oppdater docs/glossary.md med en gang.
• Forkaster brukeren kandidaten av en bærende grunn? Tilby en ADR: "Vil du at jeg skriver dette som ADR i docs/adr/ så fremtidige arkitektur-review ikke foreslår det på nytt?" Tilby kun når grunnen faktisk trengs av en fremtidig utforsker — hopp over flyktige ("ikke verdt det nå") og selvinnlysende grunner. Utløs via /nav-architecture-review ved reell arkitekturbeslutning.
• Vil du utforske alternative grensesnitt for den fordypede modulen? Kjør /codebase-design (design-it-twice — alternativene lages sekvensielt inline, aldri over parallelle agenter).

4. Koble til faseløkka

Når den valgte fordypningen er gjennomgrillet:

• Skriv den valgte tilnærmingen til docs/context.md og besluttede valg til docs/adr/.
• Bryt fordypningen ned i en trygg, inkrementell refaktoreringsplan i .grill/PLAN.md (plan-fasen; evt. videre til /to-issues for plukkbare snitt).
• Definer hva som beviser at fordypningen lyktes (tester gjennom ett grensesnitt, søm bekreftet av to adaptere) i .grill/VERIFICATION.md.