Håll genererad kod underhållbar: regeln om tråkig arkitektur

Varför underhåll blir svårare med genererad kod

Genererad kod förändrar det dagliga arbetet. Du bygger inte bara funktioner — du styr ett system som kan skapa många filer snabbt. Farten är verklig, men små inkonsekvenser multipliceras snabbt.

Genererat output ser ofta okej ut i isolation. Kostnaderna syns vid andra eller tredje ändringen: du vet inte var en del hör hemma, du fixar samma beteende på två ställen, eller undviker att röra en fil för du vet inte vad mer den påverkar.

"Kluriga" strukturer blir dyra eftersom de är svåra att förutsäga. Anpassade mönster, dold magi och tunga abstraktioner kan verka vettiga dag ett. Vecka sex går nästa ändring långsamt eftersom du måste lära om tricket innan du kan uppdatera säkert. Med AI-assisterad generering kan den där smartheten dessutom förvirra framtida generationer och leda till duplicerad logik eller nya lager ovanpå.

Tråkig arkitektur är motsatsen: enkla gränser, enkla namn och uppenbara standarder. Det handlar inte om perfektion. Det handlar om att välja en struktur som en trött kollega (eller framtida du) kan förstå på 30 sekunder.

Ett enkelt mål: gör nästa ändring enkel, inte imponerande. Det betyder oftast en tydlig plats för varje typ av kod (UI, API, data, delade verktyg), förutsägbara namn som matchar vad en fil gör, och minimalt med "magi" som automatisk wiring, dolda globala variabler eller metaprogrammering.

Exempel: om du ber Koder.ai lägga till "team invites" vill du att UI hamnar i UI-området, en API-rutt i API-området, och att invite-data lagras i datalagret — utan att verktyget hittar på en ny mapp eller mönster bara för den funktionen. Den tråkiga konsekvensen är vad som håller framtida ändringar billiga.

Regeln om tråkig arkitektur

Genererad kod blir dyr när den ger många sätt att göra samma sak. Regeln om tråkig arkitektur är enkel: gör nästa ändring förutsägbar, även om första bygget känns mindre smart.

Du ska kunna svara på de här snabbt:

• Var lever denna funktion?
• Var lägger jag en ny fil?
• Vad ska jag namnge den?
• Vad är den enklaste vägen från UI till data?

Regeln

Välj en enkel struktur och håll dig till den överallt. När ett verktyg (eller en kollega) föreslår ett fint mönster är standardsvaret "nej" om det inte tar bort verklig smärta.

Praktiska standarder som håller över tid:

• En ansvarighet per mapp och per fil. Har en fil två skäl att ändras — dela upp den.
• Förutsägbarhet slår flexibilitet. Samma sak går alltid på samma ställe.
• Föredra standardapproachen i din stack framför egna mini-ramverk.
• Gör "happy path" uppenbar. Nya bidragsgivare ska gissa rätt plats utan att fråga.
• Avvisa "magi." Undvik dolt beteende, reflection-tunga tricks och kluriga abstraktioner.

Ett snabbt mentalt test

Föreställ dig att en ny utvecklare öppnar ditt repo och behöver lägga till en "Avbryt prenumeration"-knapp. De ska inte behöva lära sig en anpassad arkitektur först. De ska hitta ett tydligt feature-område, en tydlig UI-komponent, en enda API-klientplats och en enda dataåtkomstväg.

Denna regel fungerar särskilt bra med vibe-coding-verktyg som Koder.ai: du kan generera snabbt, men du styr ändå output in i samma tråkiga gränser varje gång.

Enkla mappgränser som skalar

Genererad kod växer ofta snabbt. Det säkraste sättet att hålla den underhållbar är en tråkig mappkarta där vem som helst kan gissa var en ändring hör hemma.

Ett litet topplayout som passar många webbappar:

• app/ skärmar, routing och sidonivå-state
• components/ återanvändbara UI-delar
• features/ en mapp per feature (billing, projects, settings)
• api/ API-klientkod och request-helpers
• server/ backendhandlers, tjänster och affärsregler

Detta gör gränser uppenbara: UI finns i app/ och components/, API-anrop i api/ och backendlogik i server/.

Dataåtkomst bör vara tråkig också. Håll SQL-frågor och repository-kod nära backend, inte utspritt i UI-filer. I en Go + PostgreSQL-setup är en enkel regel: HTTP-handlers kallar tjänster, tjänster kallar repositories, repositories pratar med databasen.

Delade typer och hjälpverktyg förtjänar ett tydligt hem, men håll det litet. Lägg tvärsnitts-typer i types/ (DTOs, enums, delade gränssnitt) och små hjälpare i utils/ (datumformattering, enkla validatorer). Om utils/ börjar kännas som en andra app hör koden troligen hemma i en feature-mapp istället.

Genererad vs handskriven kod

Behandla genererade mappar som utbytbara.

• Lägg genererat output i generated/ (eller gen/) och undvik att redigera det direkt.
• Håll anpassad logik i features/ eller server/ så regeneration inte skriver över den.
• Om du måste patcha genererat beteende, wrappa det (adapterfil) istället för att ändra källan.

Exempel: om Koder.ai genererar en API-klient, lägg den under generated/api/, och skriv sedan tunna wrappers i api/ där du kan lägga till retries, logging eller tydligare felmeddelanden utan att röra genererade filer.

Namnkonventioner som förhindrar förvirring

Genererad kod är lätt att skapa och lätt att stapla upp. Namn är vad som håller den läsbar en månad senare.

Välj en namngivningsstil och blanda den inte:

• Mappar och filer: kebab-case (user-profile-card.tsx, billing-settings)
• React-komponenter: PascalCase (UserProfileCard)
• Funktioner och variabler: camelCase (getUserProfile)
• Konstanter: SCREAMING_SNAKE_CASE (MAX_RETRY_COUNT)

Namnge efter roll, inte efter hur det fungerar idag. user-repository.ts är en roll. postgres-user-repository.ts är en implementation som kan ändras. Använd implementationstillägg bara när du verkligen har flera implementationer.

Undvik skräplådor som misc, helpers eller ett gigantiskt utils. Om en funktion bara används av en feature, håll den nära den feature:n. Om den är delad, låt namnet beskriva kapabiliteten (date-format.ts, money-format.ts, id-generator.ts) och håll modulen liten.

Konventioner som gör navigering snabb

När routes, handlers och komponenter följer ett mönster kan du hitta saker utan sökning:

• Routes: routes/users.ts med paths som /users/:userId
• Handlers (HTTP): handlers/users.get.ts, handlers/users.update.ts
• Services (affärsregler): services/user-profile-service.ts
• Dataåtkomst: repositories/user-repository.ts
• UI-komponenter: components/user/UserProfileCard.tsx

Om du använder Koder.ai (eller någon generator), lägg dessa regler i prompten och håll dem konsekventa under redigeringar. Poängen är förutsägbarhet: om du kan gissa filnamnet förblir framtida ändringar billiga.

No-cleverness-standarder (tumregler)

Genererad kod kan se imponerande ut dag ett och smärtsam dag trettio. Välj standarder som gör koden uppenbar, även när den är något repetitiv.

Börja med att reducera magi. Hoppa över dynamisk laddning, reflection-liknande tricks och automatisk wiring om det inte finns ett mätt behov. Dessa funktioner döljer var saker kommer ifrån och gör debugging och refaktorering långsammare.

Föredra explicita imports och tydliga beroenden. Om en fil behöver något — importera det direkt. Om moduler behöver wiring, gör det på ett synligt ställe (t.ex. en enda composition-fil). En läsare ska inte behöva gissa vad som körs först.

Håll konfiguration tråkig och centraliserad. Lägg miljövariabler, feature-flaggor och app-omfattande inställningar i en modul med ett namngivningsschema. Sprid inte config över slumpmässiga filer för att det kändes bekvämt.

Tumregler som håller teamet konsekvent:

• Välj explicit framför implicit (imports, routing, DI, side effects).
• Om det sparar 10 rader men lägger till ett nytt koncept — skippa det.
• Ha ett sätt att göra saker (en logging-verktyg, en config-modul).
• Föredra enkel dataflöde framför dolda observatörer eller eventkedjor.
• Vid debugging: ta bort kluriga lösningar först.

Felhantering är där klurighet gör mest skada. Välj ett mönster och använd det överallt: returnera strukturerade fel från datalagret, mappa dem till HTTP-responser på ett ställe, och översätt dem till användarvänliga meddelanden i UI-gränsen. Släng inte tre olika feltyper beroende på fil.

Om du genererar en app med Koder.ai, be om dessa standarder från början: explicit module-wiring, centraliserad config och ett enhetligt felmönster.

Gränser mellan UI, API och data

Tydliga linjer mellan UI, API och data håller ändringar isolerade. De flesta mystiska buggar uppstår när ett lager börjar göra ett annat lags arbete.

UI: visa state, samla in input

Behandla UI (ofta React) som en plats för att rendera skärmar och hantera UI-only-state: vilken flik som är öppen, formulärfel, laddningsspinners och grundläggande inputhantering.

Håll server-state separat: hämtade listor, cacheade profiler och allt som måste matcha backend. När UI-komponenter börjar räkna totalsummor, validera komplexa regler eller avgöra behörigheter, sprids logiken över skärmar och blir dyr att ändra.

API: tunna, stabila former

Håll API-lagret förutsägbart. Det ska översätta HTTP-förfrågningar till samtal till affärskod, och översätta resultat tillbaka till stabila request/response-objekt. Undvik att skicka databasmodeller direkt över nätet. Stabilt svar låter dig refaktorera internt utan att bryta UI.

En enkel väg som fungerar bra:

• UI anropar en API-klient med typade request/response-objekt.
• API-handlers validerar input och kallar en servicemetod.
• Services innehåller affärsregler och workflows.
• Repositories döljer databasfrågor bakom små metoder.

Data: dölj queries bakom repositories

Lägg SQL (eller ORM-logik) bakom ett repository-skal så resten av appen inte "vet" hur data lagras. I Go + PostgreSQL betyder det oftast repositories som UserRepo eller InvoiceRepo med små, tydliga metoder (GetByID, ListByAccount, Save).

Konkreta exempel: lägga till rabattkoder. UI visar ett fält och uppdaterar priset. API accepterar code och returnerar {total, discount}. Service avgör om koden är giltig och hur rabatter staplas. Repository hämtar och sparar nödvändiga rader.

Steg för steg: ställ in underhållbar genererad kod

Genererade appar kan se "klara" ut snabbt, men struktur är vad som håller ändringar billiga senare. Bestäm tråkiga regler först, generera sedan bara tillräckligt med kod för att bevisa dem.

Ett praktiskt setup-flöde

Börja med en kort planeringsrunda. Om du använder Koder.ai är Planning Mode en bra plats att skriva en mappkarta och några namnregler innan du genererar något.

Följ sedan denna sekvens:

1. Definiera kartan och reglerna skriftligt. Välj gränser (t.ex. ui/, api/, data/, features/) och ett par namnregler.
2. Generera en tunn vertikal skiva. Välj en liten funktion som rör UI, API och lagring, som "create a contact." Målet är end-to-end-pathen, inte fullständighet.
3. Refaktorera omedelbart för att matcha gränserna. Flytta kod till planerade mappar, döp om oklara filer och ta bort dubbletter. Dela upp "gör allt"-funktioner i UI, handler och dataåtkomst.
4. Lägg till en andra feature för att testa formen. Välj något liknande, som "list contacts." Om du tvingas bryta reglerna är gränserna sannolikt fel.
5. Lås konventioner tidigt. Lägg till en kort CONVENTIONS.md och behandla den som ett kontrakt. När kodbasen växer blir det dyrt att byta namn och mappmönster.

Reality check: om en ny person inte kan gissa var man lägger "edit contact" utan att fråga, är arkitekturen fortfarande inte tillräckligt tråkig.

Exempelscenario: lägga till en funktion utan att städa till kaos

Föreställ dig ett enkelt CRM: en contacts-lista och ett kontaktredigeringsformulär. Du bygger första versionen snabbt, en vecka senare ska du lägga till "tags" för kontakter.

Behandla appen som tre tråkiga lådor: UI, API och data. Varje låda får tydliga gränser och bokstavliga namn så ändringen för "tags" förblir liten.

En ren layout kan se ut så här:

• web/src/pages/ContactsPage.tsx och web/src/components/ContactForm.tsx
• server/internal/http/contacts_handlers.go
• server/internal/service/contacts_service.go
• server/internal/repo/contacts_repo.go
• server/migrations/

Nu blir "tags" förutsägbart. Uppdatera schemat (ny contact_tags-tabell eller en tags-kolumn), och ändra ett lager i taget: repo läser/sparar tags, service validerar, handler exponerar fältet, UI renderar och redigerar det. Smuggla inte SQL in i handlers eller affärsregler in i React-komponenter.

För tester och fixtures, håll saker små och nära koden:

• server/internal/service/contacts_service_test.go för regler som "tag-namn måste vara unika per kontakt"
• server/internal/repo/testdata/ för minimala fixtures
• web/src/components/__tests__/ContactForm.test.tsx för formulärbeteende

Om du genererar detta med Koder.ai gäller samma regel efter export: håll mappar tråkiga, håll namn bokstavliga, och redigeringar slutar kännas som arkeologi.

Vanliga misstag som gör framtida ändringar dyra

Genererad kod kan se ren ut dag ett och ändå bli kostsam senare. Den vanliga boven är inte "dålig kod", det är inkonsekvens.

En dyr vana är att låta generatorn hitta på struktur varje gång. En feature landar med egna mappar, namngivningsstil och hjälpfunktioner, och du får tre sätt att göra samma sak. Välj ett mönster, skriv ner det och behandla nya mönster som ett medvetet val, inte ett standardval.

En annan fälla är att blanda lager. När en UI-komponent pratar direkt med databasen, eller en API-handler bygger SQL, blir små ändringar riskfyllda och brett spridda. Håll gränsen: UI anropar API, API anropar service, service anropar dataåtkomst.

Att överanvända generiska abstraktioner för tidigt ökar också kostnaden. Ett universellt "BaseService" eller "Repository"-ramverk kan kännas snyggt, men tidiga abstraktioner är gissningar. När verkligheten ändras kämpar du mot ditt eget ramverk istället för att leverera.

Konstant namnändring och omorganisation är en tyst form av skuld. Om filer flyttas varje vecka slutar folk lita på layouten och snabba fixar hamnar på slumpmässiga platser. Stabiliser mappkartan först, refaktorera sedan i planerade steg.

Slutligen — var försiktig med "plattformskod" som ingen användare ser. Delade bibliotek och egengjord tooling ger värde först när du har upprepade, bevisade behov. Tills dess, håll standarderna direkta.

En snabb checklista innan du shippar

Om någon ny öppnar repot ska de kunna svara på en fråga snabbt: "Var lägger jag detta?"

2-minuters navigeringstest

Ge projektet till en kollega (eller framtida du) och be dem lägga till en liten funktion, som "lägg till ett fält i signup-formuläret." Om de inte snabbt hittar rätt plats hjälper inte strukturen.

Kolla tre tydliga hem:

• UI-ändringar bor på ett uppenbart ställe.
• API-rutter/handlers är lätta att hitta från UI.
• Datamodell och databasändringar har en klar plats.

Regler värda att upprätthålla i code review

• UI, API och data har hem, undantag är sällsynta.
• Namn läses som etiketter, inte pussel.
• Lagerbrytningar flaggas (t.ex. UI som når in i databasen).
• Kluriga genvägar avslås som standard.

Om din plattform stöder det, ha en rollback-väg. Snapshots och rollback är särskilt användbara när du experimenterar med struktur och vill ha ett säkert sätt tillbaka.

Nästa steg: håll det tråkigt, håll det billigt

Underhållbarhet förbättras snabbast när du slutar debattera stil och börjar fatta ett par beslut som håller.

Skriv ner en kort uppsättning konventioner som tar bort daglig tvekan: var filer går, hur de namnges, och hur fel och config hanteras. Håll det kort nog att läsa på en minut.

Gör sedan en städpass för att matcha reglerna och sluta flytta om varje vecka. Frekvent omorganisering gör nästa ändring långsammare, även om koden ser finare ut.

Om du bygger med Koder.ai (koder.ai) hjälper det att spara dessa konventioner som en startprompt så varje ny generation landar i samma struktur. Verktyget kan röra sig snabbt, men de tråkiga gränserna är vad som håller koden lätt att ändra.