Gemini Architect

Selvinitieret, selvhostet projekt. Bygget og drevet af mig som arkitekt, product owner og reviewer, med AI som en overvåget "lærling" i udviklingsprocessen og i dele af selve produktet.

Gemini Architect er en automatisk "chefarkitekt" for et softwareprojekt: hvert push til Gitea udløser en gennemgang af diffen mod projektets nedskrevne arkitekturbeslutninger, og resultatet kommer tilbage som opdateret dokumentation og en prioriteret opgaveliste. Det fordeler rollerne mellem to AI'er, en taktisk udvikler og en strategisk reviewer, med mig som projektleder, der beslutter.

Tech stack

• Backend: Python 3.11+, FastAPI-webhookserver, Pydantic v2 struktureret output (ca. 1.100 linjer)
• AI: Google Gemini (Flash som standard, valgfri eskalering til Pro ved lav sikkerhed), context caching; Claude som den interaktive udvikler
• Versionsstyring som beskedbus: Gitea-webhooks, en privat klon i /tmp, commits mærket [gemini-init] og [skip-gemini]
• Dokumenter: architecture.md, solution_design.md, todo.md og nummererede ADR-filer i /docs/adr/
• Robusthed: anmodningsdrosling, eksponentiel backoff med jitter, detektion af kvotefejl, checkpointing, indhentning af missede commits
• Drift: én instans pr. projekt på egen port, TOML-konfiguration pr. projekt

Største bedrift At få to AI'er til at samarbejde uden anden delt tilstand end git. Revieweren arbejder i sin egen klon, rører aldrig udviklerens arbejdsmappe og kommunikerer kun gennem filer i repoet: mærkede opgaveposter ([BLOCKED], [PROPOSE], [REVIEW]), ADR'er og designdokumenter. Hver udveksling er versioneret, kan sammenlignes og kan rulles tilbage.

Problemet

Hurtig, AI-støttet udvikling producerer kode hurtigere, end et menneske kan holde arkitekturen i hovedet. Beslutninger fra uge ét modsiges i uge fem; en afvist løsning foreslås igen; dokumentationen glider fra koden. I menneskelige teams er det, en arkitekt eller et reviewpanel er til for, men små teams har sjældent et.

Arkitektur og løsning

Dig + Claude → git push → Gitea → POST /webhook
                                      ↓
                        Gemini Architect (privat /tmp-klon)
                         cachet kontekst: prompt + arkitekturfiler + ADR-indeks
                         tilstandsløs JSON-løkke (maks. 5 iterationer): need_adr → done
                         valgfri genkørsel på Pro ved lav sikkerhed
                                      ↓
              todo.md / ADR'er / solution_design.md → commit [skip-gemini] → push
                                      ↓
                              Claude: git pull

Designvalg, der er værd at fremhæve

• Git som eneste kanal. Intet delt filsystem og intet sidekanal-API. Arkitektens output er et commit, så det står i historikken, kan gennemgås og rulles tilbage og kan ikke ødelægge udviklerens arbejdskopi.
• Klart ejerskab af filer. Revieweren ejer architecture.md og solution_design.md; udvikleren ejer den taktiske del af todo.md; ADR'er er kun-tilføj-registreringer. Reglerne for, hvem der må ændre hvad, står i projektets CLAUDE.md.
• Løkkeforebyggelse som design. Commits fra arkitekten bærer [skip-gemini], så de ikke udløser den igen, og arkitekten skal læse ADR-indekset før et forslag og må ikke genfremsætte en afvist løsning uden at adressere, hvorfor den blev afvist.
• Tilstandsløs analyse med et cachet præfiks. Hvert commit kører en kort struktureret løkke frem for en lang chat. Den stabile del af konteksten caches hos udbyderen og genbruges, til filer ændres, hvilket holder pris og svartid nede.
• Struktureret output. Svar valideres mod Pydantic-modeller, så et fejlformet svar fejler højlydt i stedet for lydløst at ødelægge dokumentationen.
• Eskalering baseret på sikkerhed. En billigere model klarer den rutinemæssige gennemgang; falder dens egen sikkerhedsscore under en tærskel, kører en stærkere model analysen igen med hele konteksten.
• Robust over for API'et. Drosling, backoff med jitter, øjeblikkelig detektion af faktureringskvotefejl og en handler, der aldrig går ned på API-fejl. En checkpoint-fil og indhentningslogik lader den genoptage efter nedetid.
• Observeret adfærd, ikke kun design. Projektets egen todo.md viser, at arkitekten genererer gentagne "ryd op i opgavelisten"-poster om sit eget output. Det er en reel svaghed ved en automatisk reviewer uden stopregel, og det står på forbedringslisten frem for at være skjult.
• Ingen automatiske tests. Projektet er to dages fokuseret arbejde (30. april til 1. maj 2026) og blev verificeret ved at køre det på rigtige repoer, inklusive sig selv.

AI som lærling

AI i selve produktet. Hele projektet er et AI-workflow: Gemini fungerer som reviewer under stramme rammer, med et fast værktøjssæt (læs filer, skriv dokumenterne, log en ADR, foreslå en ændring) og et struktureret svarformat. Den udfører ikke kode og kan ikke skubbe ind i udviklerens branchehistorik andet end gennem sine mærkede dokumentationscommits.

AI i udviklingsprocessen (human-in-the-loop). Grundideen er en bevidst adskillelse: én AI skriver kode interaktivt sammen med mig, en anden gennemgår ved en trigger, og jeg beslutter, hvad der sker derefter, ud fra todo.md. [BLOCKED]-posterne er skrevet for at stoppe udvikler-AI'en, når den modsiger en nedskrevet beslutning. Jeg forbliver afgøreren mellem de to.

Lederens refleksion

1. Arkitektur har brug for en hukommelse. ADR'er er billige, og en reviewer, der læser dem før den kommenterer, forhindrer teams i at genforhandle den samme beslutning.
2. Adskil forfatter og reviewer, også når begge er AI. Et andet par øjne med en anden model og et andet job fanger ting, forfatteren normaliserer.
3. Brug de værktøjer, teamet allerede stoler på, som integrationslag. Git giver historik, review og tilbagerulning gratis.
4. Automatisering har brug for en stopregel. Alt, der skriver tilbage i det system, det overvåger, skal forhindres i at reagere på sig selv; [skip-gemini]-mærket er ét svar, og den støjende opgavehistorik viser, at det ikke er hele svaret.
5. Hold et menneske som beslutningstager. Revieweren foreslår og blokerer; den sætter ikke prioriteter.

Ærlige begrænsninger. En fungerende prototype, bygget på cirka to dage, uden automatiske tests, med én udbyder, den selvrefererende opgavestøj nævnt ovenfor og med health-endpoint, replay-endpoint og BLOCKED-notifikationer stadig på fremtidslisten.