Claude Code-stilguide-promptar för konsekventa kodgranskningar

Varför stilavvikelser sprider sig så snabbt

Stilavvikelser visar sig sällan som ett enda stort misstag. De börjar som små "tillräckligt bra"-val som ser harmlösa ut i en pull request, och bygger sedan på varandra tills kodbasen känns ojämn och svårare att läsa.

Stildrift ser ofta ut så här: en fil använder userID, en annan userId, en tredje uid. En handler returnerar { error: "..." }, en annan kastar, en tredje loggar och returnerar null. Varje ändring är liten, men tillsammans skapar de ett repo där mönster slutar vara förutsägbara.

Snabb iteration och flera bidragsgivare gör det värre. Folk kopierar det de ser, särskilt under tidspress. Om den senaste koden i repot använde en genväg blir den mallen för nästa ändring. Efter några veckor är den "standardstil" ni följer inte er skrivna guide — det är det som hände senast.

Därför måste målet vara konsekventa konventioner, inte personliga preferenser. Frågan är inte "tycker jag om det här namnet?" utan "stämmer det här överens med de regler vi kom överens om så nästa person kan följa det utan att tänka?"

Att fånga avvikelser tidigt betyder att stoppa dåliga mönster innan de blir copy-paste-bränsle. Fokusera på ny och ändrad kod, åtgärda den första uppkomsten av en ny inkonsekvens, och blockera merges som introducerar ny drift. När du flaggar ett problem, lägg till ett kort exempel på föredragen kod som folk kan efterlikna nästa gång.

Ett realistiskt exempel: en utvecklare lägger till en ny API-endpoint och loggar råa request-body "bara för debugging." Får det landa kommer nästa endpoint kopiera det, och snart finns känslig data i loggar. Att hitta det i första PR är billigt. Att ta bort det efter att det spridits är smärtsamt och riskfyllt.

Gör din stilguide till tydliga, testbara regler

En stilguide fungerar i granskningar endast om den läses som en checklista, inte som en samling preferenser. Skriv om varje riktlinje till en regel som går att testa på en diff.

Organisera regler i fyra fack så de blir svåra att missa: namngivning, lagerindelning, felhantering och loggning. För varje fack, skriv två saker: vad som måste vara sant och vad som är förbjudet.

Bestäm styrkan för varje regel i förväg:

• Obligatorisk: underlåtenhet blockerar ändringen.
• Rekommenderad: åtgärda om det inte finns en tydlig anledning att avvika.
• Valfri: bra att ha, aldrig blockerande.

Sätt scope så granskningar inte blir ändlösa refaktorer. En enkel regel fungerar bra: "ny och modifierad kod måste följa; befintlig orörd kod skrivs inte om om det inte blockerar fixen." Vill du ha städning, tidsbegränsa det som en separat uppgift.

Definiera också vad du vill ha ut från en granskning så det är lätt att agera: en klar godkänd/underkänd-utsaga, en lista över avvikelser med fil- och linjereferenser, föreslagna fixar skrivna som konkreta ändringar, och en kort risknotis när något kan orsaka buggar eller läckor.

Exempel: om en PR loggar råa användartokens ska granskningen underkännas under "loggning: logga aldrig hemligheter" och föreslå att logga ett request ID istället.

Promptstruktur som upprätthåller regler istället för åsikter

Stilpromptar misslyckas när de låter som preferenser. En bra granskningsprompt läser som ett kontrakt: tydliga icke-förhandlingsbara regler, klart namngivna undantag och ett förutsägbart utdata.

Börja med två korta block: vad som måste vara sant och vad som kan böjas. Lägg sedan till en beslutsregel: "Om oklart, markera som Needs Clarification. Gissa inte."

Tvinga fram bevis. När verktyget flaggar en avvikelse, kräva att det citerar exakt identifierare och filväg, inte en vag beskrivning. Denna enkla begränsning tar bort mycket fram-och-tillbaka.

Håll scope tajt: kommentera bara ändrade rader och direkt påverkade kodvägar. Om du tillåter orelaterade refaktorer, förvandlas stilkontroll till att "skriv om filen", och folk slutar lita på feedbacken.

Här är en struktur du kan återanvända:

Role: strict style guide reviewer.
Input: diff (or files changed) + style guide rules.
Non-negotiables: [list].
Allowed exceptions: [list].
Scope: ONLY comment on changed lines and directly impacted code paths. No unrelated refactors.
Evidence: Every finding MUST include (a) file path, (b) exact identifier(s), (c) short quote.
Output: structured compliance report with pass/fail per category + minimal fixes.

Kräv att rapporten behåller samma sektioner varje gång, även om några är "No issues found": Naming, Layering, Error handling, Logging.

Om den säger "service layer leaking DB details" måste den citera något som internal/orders/service/order_service.go och det exakta anropet (till exempel db.QueryContext) så du kan åtgärda läckan utan diskussion om vad som menades.

Steg för steg: bygg ett workflow för stilkontrollspromptar

En stilguide sitter när processen är upprepbar. Målet är att få modellen att kontrollera regler, inte argumentera om smak, och att göra det på samma sätt varje gång.

Använd ett enkelt tvåpass-workflow:

1. Klistra in era standarder som en kompakt, numrerad reglerlista (10–25 rader). Håll varje regel testbar.
2. Lägg till kontext för ändringen: diffen, berörda filer och en mening om avsikten.
3. Be om en rapport över avvikelser först. Kräv fil- och linjereferenser, en kort anledning och exakt regelnummer.
4. Först efter rapporten, be om den minsta möjliga patchen för att nå efterlevnad.
5. Kör exakt samma prompt på den uppdaterade koden för att bekräfta att inget återstår.

Exempel: en PR lägger till en ny endpoint. Pass 1 flaggar att handlare pratar direkt med PostgreSQL (layering), använder blandad namngivning för request-structs (naming) och loggar fullständiga email (logging). Pass 2 gör minimala ändringar: flytta DB-anrop till en service eller repository, byt namn på structen och maskera email i loggarna. Inget annat ändras.

Namngivningskonventioner: promptar som fångar småsakerna

Namngivningsproblem känns små, men de skapar verkliga kostnader: folk misstolkar avsikt, sökningar blir svårare och "nästan samma"-namn multipliceras.

Ange namngivningsreglerna som granskaren måste upprätthålla över hela ändringen: filnamn, exporterade typer, funktioner, variabler, konstanter och tester. Var tydlig om skrivstil (camelCase, PascalCase, snake_case) och välj en akronymregel (till exempel APIClient vs ApiClient). Kräv sedan att den följs överallt.

Standardisera också delad vokabulär: feltyper, loggfält och konfignycklar. Om loggar använder request_id, tillåt inte reqId i en fil och requestId i en annan.

En praktisk granskningsinstruktion:

Check every new or renamed identifier. Enforce casing + acronym rules.
Flag vague names (data, info, handler), near-duplicates (userId vs userID), and names that contradict behavior.
Prefer domain language: business terms over generic tech words.

Be om en kort rapport: de tre mest förvirrande namnen, eventuella nära-duplicat och vilken som ska behållas, plus logg-/konfig-/fel-namn som inte matchar standarden.

Lagerindelning: håll ansvar separerade

Lagerregler fungerar bäst i klartext: handlers hanterar HTTP, services innehåller affärslogik, repositories pratar med databasen.

Lås riktningen för beroenden. Handlers får anropa services. Services får anropa repositories. Repositories ska inte anropa services eller handlers. Handlers ska inte importera databas-kod, SQL-hjälpare eller ORM-modeller. Om du använder delade paket (config, time, IDs), håll dem fria från applikationslogik.

Placera tvärgående funktioner i ett hem. Validering brukar höra hemma i gränsytan för request-shape och i servicen för affärsregler. Auktorisation börjar ofta i handlern (identity, scopes), men servicen bör göra det slutgiltiga beslutet. Mappning hör hemma i lagrets kanter: handler mappar HTTP till domän-input, repository mappar DB-rader till domäntyper.

Klistra in detta i en prompt för konkreta granskningar:

Check layering: handler -> service -> repository only.
Report any leaks:
- DB types/queries in handlers or services
- HTTP request/response types inside services or repositories
- repository returning DB models instead of domain objects
- auth/validation mixed into repository
For each leak, propose the smallest fix: move function, add interface, or rename package.

Gör rapporten explicit: namnge filen, vilket lager den hör hemma i, importen eller anropet som bryter regeln, och den minimala ändringen som förhindrar att mönstret sprids.

Felhanteringskonventioner: konsekvens under press

De flesta stildebatter blir högljudda när något går sönder i produktion. En klar felhanteringspolicy håller fixar lugna eftersom alla vet hur "bra" ser ut.

Skriv ner filosofin och upprätthåll den. Till exempel: "Wrappa fel för att lägga till kontext; skapa ett nytt fel bara när betydelsen förändras eller när du mappar till ett användarmeddelande. Returnera råa fel endast vid systemgränser." Den meningen hindrar slumpmässiga mönster från att spridas.

Separera användarvänlig text från intern detalj. Användarmeddelanden ska vara korta och säkra. Interna fel kan innehålla operationens namn och nyckelidentifierare, men inte hemligheter.

I granskningar, kontrollera för några återkommande fel: slängda fel (loggade men inte returnerade), tvetydiga returer (nil värde med nil fel efter ett misslyckande), och användarmeddelanden som läcker stacktraces, query-text, tokens eller PII. Om ni stödjer retries eller timeouts, kravställ att de är explicita.

Exempel: ett checkout-anrop timed out. Användaren ser "Payment service is taking too long." Internt wrappa timeout och inkludera op=checkout.charge och order-ID så det blir sökbart och hanterbart.

Loggningskonventioner: läsbart, sökbart och säkert

Loggar hjälper bara när alla skriver dem på samma sätt. Om varje utvecklare väljer egen formulering, nivå och fält blir sökningar gissningslek.

Gör loggnivåer icke-förhandlingsbara: debug för utvecklingsdetalj, info för normala milstolpar, warn för oväntade men hanterade situationer, och error när användaråtgärden misslyckas eller behöver uppmärksamhet. Håll "fatal" eller "panic" sällsynta och knutna till en tydlig kraschpolicy.

Strukturerade loggar är viktigare än perfekta meningar. Kräv stabila nyckelnamn så dashboards och larm inte går sönder. Bestäm en liten kärna (till exempel event, component, action, status, duration_ms) och håll den konsekvent.

Behandla känsliga data som ett stopptecken. Var explicit om vad som aldrig får loggas: lösenord, autentiseringstoken, fullständiga kreditkortsnummer, hemligheter och rå personlig data. Lyft fram saker som ser harmlösa ut men inte är det, som password reset-länkar, session IDs och fullständiga request bodies.

Korrelations-ID gör felsökning möjlig över lager. Kräv ett request_id i varje loggrad inom en förfrågan. Om du loggar user_id, definiera när det är tillåtet och hur man representerar saknad eller anonym användare.

En promptdel att återanvända:

Review the changes for logging conventions:
- Check level usage (debug/info/warn/error). Flag any level that does not match impact.
- Verify structured fields: require stable keys and avoid free-form context in the message.
- Confirm correlation identifiers: request_id on all request-bound logs; user_id only when allowed.
- Flag any sensitive data risk (tokens, secrets, personal data, request/response bodies).
- Identify noisy logs (in loops, per-item logs, repeated success messages) and missing context.
Return: (1) violations with file/line, (2) suggested rewrite examples, (3) what to add or remove.

Innan merge, gör en snabb "safety pass": alla nya loggar som saknar request_id för request-arbete, nya nycklar som ändrar existerande namn (userId vs user_id), fel-loggar som saknar vad som gick fel (operation, resource, status), högt-volymsloggar som triggas per request, och alla chanser att hemligheter eller personlig data kan hamna i fält eller meddelanden.

Hur man fångar avvikelser innan de sprider sig

Behandla stildrift som ett build-break, inte ett förslag. Lägg till en strikt grind som körs före merge och returnerar klart pass eller fail. Om en obligatorisk regel bryts (namngivning, lagergränser, loggsäkerhet, felhantering) så underkänns den och pekar på exakta filer och rader.

Håll grinden kort. En praktisk trick är att kräva en JA/NEJ-checklista per regel, och vägra godkännande om något är NEJ.

En PR-stor checklista som fångar de flesta problem:

• Namngivning: följer godkända mönster för filer, typer och funktioner
• Lagerindelning: inga direkta anrop som hoppar över lager (t.ex. handlers som kallar DB)
• Fel: returneras konsekvent med kontext, inget tystades bort
• Loggning: konsekventa fält, inga hemligheter, nivå matchar påverkan
• Tester/dokumentation: uppdaterade när beteende eller publika API:er ändras

När verktyget föreslår fixar, kräva ett litet kompatibelt kodsnutt för varje regel det rör. Det förhindrar vag feedback som "byt namn för tydlighet."

Vanliga fallgropar när du använder promptar för stil

Det snabbaste sättet för en stilguide att misslyckas är att lämna rum för tolkning. Om två granskare kan läsa samma regel och komma fram till olika slutsatser kommer verktyget att driva smak, inte standarder.

Namngivning är ett vanligt exempel. "Använd tydliga namn" går inte att testa. Gör om till något verifierbart: "funktioner är verb (t.ex. createInvoice), booleaner börjar med is/has/can, exporterade typer är PascalCase."

En annan fallgrop är att be om allt på en gång. När en prompt försöker täcka namngivning, lager, fel, loggning, tester och prestanda blir feedbacken ytlig. Dela upp i fokuserade pass när du behöver djup, eller håll gate-prompten begränsad till obligatoriska regler.

Problem som oftast orsakar drift i enforcement:

• Vaga regler: ersätt "rent" och "konsekvent" med mätbart språk.
• Blanda stilfixar med redesign: låt inte en stilprompt föreslå en ny arkitektur.
• Ingen citerad bevisning: kräv att varje kommentar citerar exakt identifierare eller kodsnutt.
• Tysta undantag: om du tillåter ett undantag, kräva en kort notering som förklarar varför och när det ska tas bort.

Om du behandlar promptar som tester får du förutsägbar enforcement. Om du behandlar dem som råd smyger avvikelser in och multipliceras.

Snabb checklista du kan köra på varje ändring

Kör ett snabbt pass över diffen (inte hela repot) och bekräfta:

• Namngivning: nya identifierare följer ert mönster (case, prefix, suffix). Ett koncept är namngivet på samma sätt över filer.
• Lager: beroenden går bara i tillåten riktning. Lägre lager importerar aldrig högre lager.
• Fel: fel returneras med kontext. Ingenting ignoreras tyst.
• Loggning: korrekt nivå, stabila fält och inga hemligheter eller personlig data.
• Slutpass: granskaren säger exakt: "no mandatory violations found", eller listar de avvikelser som måste åtgärdas före merge.

Håll en minimal promptmall och klistra in den med varje ändring:

Review ONLY the changed code against our rules for naming, layering, errors, and logging.
List mandatory violations first (with file + line if available). Then list optional suggestions.
End with either: “no mandatory violations found” or “mandatory violations found”.

Exempel: en ny funktion procUsr() i en handler som skriver direkt till PostgreSQL ska misslyckas på både namngivning och lager även om funktionen fungerar. Att fånga det här stoppar copy-paste från att sprida misstaget.

Exempel: en realistisk granskning som åtgärdar problem tidigt

En kollega lägger till en ny endpoint: POST /v1/invoices/{id}/send. Den påverkar en handler, en service och storage.

I första passet vill du ha en rapport, inte en omskrivning:

Pass 1 (report only)
You are a strict style checker. Read the patch.
Rules: naming must match our guide, handlers call services only, services call storage only, no SQL in handlers,
errors must be wrapped with context, logs must be structured and not leak PII.
Output: a numbered list of violations with file:line, rule name, and one-sentence impact. Do not propose fixes.
If a rule might be intentionally broken, ask one clarification question.

Typiska fynd: SendInvoiceNow() vs SendInvoice namnmismatch, handlern anropar db.QueryRow direkt, returnerar rått err utan kontext, och bullriga loggar som log.Printf("sending invoice %v", invoice) som dumpar hela objekt.

Andra passet ber om minimala, säkra ändringar:

Pass 2 (minimal fix suggestions)
Using the violations list, propose the smallest code edits to comply.
Constraints: keep behavior the same, no refactors beyond what is needed, show suggested function names and where code should move.
For each fix, include 1-2 lines of example code.

Om ett regelbrott är tillåtet, säg det öppet: "Exceptions are permitted only if you add a short comment explaining why, and you add a follow-up task to remove the exception."

Efter fixen blir handlern en tunn adapter, servicen äger workflowen, storage äger queryn, fel blir fmt.Errorf("send invoice: %w", err), och loggar blir en ren rad med säkra fält (invoice ID, inte hela fakturan).

Nästa steg: gör det rutin utan att sakta ner

Välj en team-godkänd prompt och behandla den som ett delat verktyg. Börja med det som mest smärtar i era granskningar (namndrift, läckande lager, inkonsekventa fel, osäkra loggar). Uppdatera prompten bara när du ser en verklig avvikelse i verklig kod.

Håll en liten regler-block högst upp i prompten och klistra in den i varje granskning oförändrad. Om alla redigerar reglerna varje gång har ni ingen standard — ni har en debatt.

En enkel takt hjälper: en person samlar veckans vanligaste stilmissar och ni lägger till exakt en tydligare regel eller ett bättre exempel.

Om ni jobbar i ett chattdrivet buildflöde som Koder.ai (koder.ai), är det värt att köra samma gate-kontroller under ändringar, inte bara i slutet. Funktioner som planering, snapshots och rollback kan hjälpa er hålla stilfixar små och reversibla innan ni exporterar källkod.