Claude Code i monorepos: begränsa kontexten och bevara noggrannheten

Varför stora monorepos gör Claude mindre exakt

Claude Code i monorepos kan kännas oförutsägbart av en enkel anledning: förrådet är större än vad modellen kan hålla i arbetsminnet på en gång.

"Kontext" är mängden filer, kodsnuttar, anteckningar och instruktioner Claude har sett för den här uppgiften, plus vad den kan härleda från dem. När viktiga detaljer fattas fyller Claude luckorna med gissningar. I ett stort repo händer det oftare.

Tre feltyper dyker upp igen och igen:

För det första, missade filer. En ändring som ser säker ut i en mapp beror faktiskt på en delad typ, en konfigurationsregel eller ett byggsteg definierat någon annanstans. Om det beroendet inte finns i kontext kan Claude självsäkert redigera fel sak eller sluta för tidigt eftersom den inte ser den verkliga sanningskällan.

För det andra, falsk likhet. Monorepos innehåller ofta flera paket som ser lika ut: två auth-moduler, tre API-klienter eller flera React-appar med liknande mappstruktur. Claude kan blanda mönster mellan dem, uppdatera en hjälpfunktion i fel paket eller importera från ett "nästan rätt" modulnamn.

För det tredje, tidsdrift. Stora kodbaser har ofta både gamla och nya sätt att göra samma sak. Om Claude bara ser äldre filer kan den kopiera utåldrade mönster (föråldrade konfigurationsalternativ, legacy-APIer) även om teamet har gått vidare.

Ett vanligt verkligt exempel: du ber om en liten ändring i ett billing-UI, och Claude redigerar en delad payments-komponent som används av andra appar eftersom den aldrig såg app-specifika wrappersen som borde ha ändrats.

Målet är inte att visa Claude hela monorepot. Målet är att ge mindre, genomtänkta indata som fortfarande svarar på frågan: paketet du ändrar, dess direkta beroenden och en eller två "sanningskällor" för typer och konfig. Peka också ut områden som "inte får röras" (andra appar, infra, genererad kod) och bekräfta vilket paket som äger beteendet.

Börja med att definiera uppgiften, inte repot

Noggrannhet beror mindre på hur mycket kod du klistrar in och mer på hur tydligt du beskriver jobbet.

Börja med det resultat du vill ha: en specifik fix, refaktor eller svar. En "fråga om koden" kan vara hög nivå. En "gör en ändring"-förfrågan behöver gränser, inputs och acceptanskriterier.

Innan du delar något, skriv en mening som slutför den här frasen: "När du är klar ska jag kunna…". Till exempel: "köra unit-testerna för paket X utan fel" eller "se det nya fältet i API-svaret för endpoint Y." Den meningen blir nordstjärnan när repot är stort.

För ändringar, dela den minsta mängd artefakter som kan bevisa att ändringen är korrekt: entry point(s), relevanta typer/interfaces eller schema, ett felande test eller ett repro-steg med förväntat resultat, och all konfig som påverkar den här vägen (routing, feature flags, build- eller lint-regler). Om det hjälper, lägg till en kort mappkarta för paketet så Claude förstår vad varje katalog är till för.

Var tydlig med vad som inte ska granskas. Säg: "Ignorera genererade filer, vendor-mappar, build-utdata, snapshots och lockfiler om jag inte ber om det." Det förhindrar bortkastad tid och ändringar på ställen du inte tänker granska.

Sätt också förväntningar för osäkerhet. Be Claude markera antaganden och okända saker istället för att gissa. Till exempel: "Om du inte kan se var den här funktionen kallas, säg det och föreslå 2 sätt att lokalisera den."

Dra tydliga gränser Claude inte ska korsa

I ett stort monorepo sjunker noggrannheten när modellen börjar "hjälpsamt" plocka in närliggande kod som inte är en del av uppgiften. Lösningen är enkel: definiera vad som är in-scope och vad som är out-of-scope innan du ber om ändringar.

Börja med en gräns som matchar hur ditt repo är organiserat: ett paket, en service, en app eller ett delat bibliotek. Om ändringen är "uppdatera checkout-UI" är gränsen förmodligen ett app-paket, inte varje plats där ordet "checkout" dyker upp.

Signaler som hjälper Claude att hålla sig på plats inkluderar mappkonventioner (apps/, services/, packages/, libs/), paketmanifest (exports och dependencies), publika entry points (index-filer, exporterade komponenter, handlers) och tester (de avslöjar ofta den avsedda ytan). En README i mappen kan vara den snabbaste gränsmarkören.

Gränser fungerar bäst när du namnger broarna mellan dem. Peka ut de specifika gränssnitten Claude kan röra och behandla allt annat som förbjudet. Typiska broar är HTTP API-kontrakt, event-topics och payloads, delade typer eller ett litet set exporterade funktioner.

Namnga också "do not touch"-zoner när ändringen inte ska påverka dem. Vanliga är infrastruktur- och deploymentskonfig, säkerhets- och auth-logik, billing och payments, datamigreringar och produktionsscheman, samt delade bibliotek som används av många team.

Ett konkret promptexempel som hjälper:

"Gör ändringar endast i packages/cart/ och dess tester. Du får läsa delade typer i packages/types/ men ändra dem inte. Redigera inte infra, auth eller billing."

Hur man skriver användbara lokala sammanfattningar

Noggrannheten förbättras när du tillhandahåller en liten, stabil karta av området du vill ändra. En "local summary" är den kartan: tillräckligt kort för att läsas snabbt, tillräckligt specifik för att förhindra gissningar.

Håll varje sammanfattning runt 10–20 rader. Skriv den som om du ger koden till en ny kollega som bara behöver röra denna gräns, inte hela repot. Använd enkelt språk och verkliga namn från koden: mappar, paket, exporterade funktioner.

En användbar lokal sammanfattning besvarar fem frågor:

• Vad paketet/tjänsten är till för, och vad det inte är till för (scope)
• Var arbetet börjar (huvudentry points som viktiga filer, routes, kommandon eller komponenter)
• Vad som är säkert att anropa utifrån (publika API:er, exporterade moduler, events, endpoints)
• Vad det beror på (databaser, köer, caches, konfig, externa tjänster)
• Vilka regler som spelar roll här (namngivningsmönster, felstil, loggning och hur tester skrivs)

Lägg till en "gotchas"-rad. Här förhindrar du dyra misstag: dold caching, feature flags, migrationssteg och allt som tyst går sönder.

Här är en kompakt mall du kan kopiera:

Local summary: <package/service name>
Purpose: <1 sentence>
Scope: <what to touch> | Not: <what not to change>
Entry points: <files/routes/commands>
Public surface: <exports/endpoints/events>
Data sources: <tables/collections/queues/caches>
Conventions: errors=<how>, logging=<how>, tests=<where/how>
Gotchas: <flags/caching/migrations/edge cases>

Exempel: om du redigerar ett billing-paket, notera den exakta funktionen som skapar invoices, tabellnamnen den skriver till och regeln för retryable errors. Då kan Claude fokusera på den gränsen istället för att vandra in i delad auth, konfig eller andra paket.

Var sammanfattningarna bör leva och hur man håller dem aktuella

Den bästa sammanfattningen är den som Claude ser när den behöver den. Lägg den intill koden den beskriver så den är svår att ignorera och lätt att uppdatera. Till exempel, behåll en kort SUMMARY.md (eller en README.md-sektion) i varje paket-, service- eller app-katalog istället för ett enda gigantiskt dokument i repo-roten.

En enkel, upprepbar struktur hjälper. Håll den kort nog för att folk faktiskt ska underhålla den:

• Vad den här mappen är (syfte i 1–2 meningar)
• Publik yta (huvudentry points, exporterade moduler eller API:er)
• Nyckelberoenden (internt och externt)
• Gränser (vad den inte får importera eller modifiera)
• Hur man testar (snabbaste lokala kontrollen)
• Last updated: YYYY-MM-DD - <what changed in one sentence>

Sammanfattningar blir inaktuella av förutsägbara skäl. Behandla uppdateringar som du behandlar ändringar i en typdefinition: en del av att slutföra arbetet, inte en separat uppgift.

Uppdatera sammanfattningen när en refaktor ändrar struktur eller namn, en ny modul blir huvudvägen för en sak, ett API/event/schema ändras (även om testerna fortfarande går igenom), gränser skiftar mellan paket, eller ett beroende tas bort eller byts ut.

En praktisk vana: när du mergar en ändring, lägg till en "Last updated"-rad som beskriver vad som ändrades. Verktyg som Koder.ai kan göra kodändringen snabbare, men sammanfattningen är vad som håller framtida ändringar korrekta.

Ett steg-för-steg-workflow för att hålla sig inom rätt kontext

Noggrannhet beror ofta på hur du tempot för konversationen. Låt Claude förtjäna kontext i små bitar istället för att gissa utifrån en enorm snapshot.

Steg 1: Be om en snabb karta först

Innan några redigeringar, be Claude beskriva vad den ser och vad den behöver. En bra karta är kort: nyckelpaket som är inblandade, entry point för flödet och var tester eller typer ligger.

Prompt:

"Skapa en karta för denna ändring: paket involverade, huvudflöde och sannolika beröringspunkter. Föreslå inte kod än."

Steg 2: Börja med en slice och en gräns

Välj en smal slice: en funktion, ett paket, ett användarflöde. Ange gränsen tydligt (t.ex. "Endast ändra packages/billing-api. Rör inte shared-ui eller infra. ").

Ett workflow som håller dig i kontroll:

• Definiera mål och gräns i en mening.
• Kräv antaganden och okända saker (Claude måste lista dem).
• Be om exakt vilka filer den behöver härnäst (begränsa till 3–6).
• Ge bara de filerna, och upprepa.
• Kräv en kort plan innan någon patch görs.

Steg 3: Tvinga fram explicita antaganden och filbegäran

Om Claude saknar något ska den säga det. Be den skriva: (1) antaganden den gör, (2) vad som skulle motbevisa dem, och (3) nästa filer som krävs för att bekräfta.

Exempel: du behöver lägga till ett fält i ett Invoice-svar i ett paket. Claude begär handlern, DTO/typ-definitionen och ett test. Du delar bara de filerna. Om du använder en chat-baserad builder som Koder.ai gäller samma regel: ge minsta mängd källfiler, expandera bara när det verkligen behövs.

Använd begränsningar och kontrakt i dina prompts

Din bästa försvarslinje mot felaktiga ändringar är ett litet "kontrakt" inbyggt i prompten: vad Claude får röra, hur du bedömer framgång och vilka regler den måste följa.

Börja med en gräns som är lätt att följa och verifiera. Var explicit om var ändringar är tillåtna, och namnge "do not touch"-områden så det inte finns någon frestelse att vandra.

Kontraktmall:

• Endast modifiera filer under packages/payments/.
• Redigera inte packages/auth/, infra/ eller några delade configs.
• Om du behöver ändringar utanför scope, stoppa och fråga först.
• Håll ändringar minimala: fixa buggen, undvik refaktorer.

Definiera sedan acceptanskontroller. Utan dem kan Claude producera kod som ser rätt ut men bryter mot repoets riktiga regler.

• Kör unit-tester för paketet (namnge kommandot).
• Kör lint/format (namnge verktyget, eller säg "använd befintlig config").
• Kör typecheck/build för paketet.
• Bekräfta att appen fortfarande startar (ett enkelt run-kommando räcker).

Stilkrav spelar också roll. Säg vilka mönster som ska följas och vilka som ska undvikas baserat på vad din kodbas redan gör. Till exempel: "Använd befintliga error-helpers i det här paketet; lägg inte till nya beroenden; håll funktionsnamn i camelCase; introducera inte ett nytt arkitekturlager."

Slutligen, kräv en kort ändringsplan innan några redigeringar:

"Innan du redigerar, lista de 3–5 filer du förväntar dig att röra och den exakta beteendeförändringen. Vänta på godkännande."

Exempel:

"Fix rounding i invoice totals. Ändra endast packages/billing/src/ och tester under packages/billing/test/. Acceptans: pnpm -C packages/billing test och typecheck. Följ befintliga money-utils; skriv inte om API-typer. Ge en 4-stegsplan först."

Vanliga fallgropar som orsakar drift och felaktiga ändringar

Det snabbaste sättet att få felaktiga ändringar i ett monorepo är att ge Claude för mycket samtidigt. När du klistrar in en stor hög kod faller den ofta tillbaka på generiska mönster istället för det specifika designspråket ditt repo redan använder.

En annan fallgrop är att låta den gissa arkitekturen. Om du inte visar verkliga entry points kan den välja den första filen som ser plausibel ut och koppla logik där. I praktiken kommer noggrannhet från en liten uppsättning "sanningsfiler" (entry modules, routers, service registries, package boundary docs). Om de inte finns i kontext fyller modellen luckorna.

Namngivning kan också lura den. Monorepos har ofta paket som ui, ui-kit, shared-ui, eller duplicerade hjälpare som date.ts på två ställen. Om du blandar utdrag från båda kan Claude patcha en fil medan den resonerar om den andra. Exempel: du ber ändra en knappstil, den redigerar packages/ui/Button.tsx, men appen importerar packages/ui-kit/Button.tsx. diffen ser bra ut, men inget ändras i produktion.

Konfig är en annan källa till tyst drift. Beteende kan bero på env vars, feature flags, build-inställningar eller workspace-verktyg. Om du inte nämner dessa kan Claude ta bort en "konstig" kontroll som bara är viktig när en flagga är på, eller lägga till kod som bryter ett byggsteg.

Röda flaggor att du drifter:

• Svaret pratar om "typiska mönster" utan att namnge dina faktiska filer
• Den introducerar en ny delad util istället för att använda en befintlig
• Den ändrar imports över paketgränser
• Den ignorerar feature flags eller env-specifika grenar
• Den föreslår att lägga till ett beroende i ett kärndelat paket

Behandla cross-package-importer som ett beslut, inte som standard. Håll ändringar lokala om du inte medvetet utökar scope.

Snabb checklista innan du ber Claude om något

Det snabbaste sättet att få korrekta ändringar är att börja med begränsningar, inte volym. En bra prompt känns lite sträng: den talar om var Claude ska titta, vad som ska ignoreras och vad "klart" betyder.

Innan du klistrar kod, skriv en kort inledning som fäster arbetet till en plats i repot. Namnge paketet, den exakta mappen och det specifika målet. Inkludera sedan en lokal sammanfattning (syfte, nyckelberoenden, viktiga konventioner) och entry-filen som förankrar ändringen.

Checklista:

• Boundary: Arbeta endast i <package>/<path>. Mål: <one sentence>. Ignorera allt annat om inte begärt.
• Context starter: Lokal sammanfattning: <5-10 rader>. Entry-fil: <path/to/file>.
• Constraints: Tillåtna mappar: <...>. Får inte ändras: <folders/files or APIs>. Bevara beteende: <what must stay true>.
• File requests first: "Innan du föreslår ändringar, lista minimifilerna du behöver se (max 5) och varför."
• Output format: "Svara med en kort plan först. Efter godkännande, ge patch-liknande förslag per fil."

Om Claude föreslår ändringar utanför din gräns, se det som en signal: antingen skärp prompten, eller utöka gränsen medvetet och skriv om den tydligt.

Exempel: göra en ändring i ett paket utan att väcka hela monorepot

Säg att ditt monorepo har apps/web-store (en React-app) och packages/ui-kit (delade knappar, inputs och stilar). Du vill ha en liten funktion: lägg till en "Save for later"-knapp på cart-sidan, med en ny SaveIcon från ui-kit. Inget annat ska ändras.

Innan du ber om ändringar, skapa två lokala sammanfattningar som fungerar som gränser. Håll dem korta, specifika och opininerade om vad som spelar roll.

# apps/web-store/LOCAL_SUMMARY.md
Purpose: Customer shopping UI.
Entry points: src/routes.tsx, src/pages/cart/CartPage.tsx
Cart rules: cart state lives in src/cart/useCart.ts
Do not touch: checkout flow (src/pages/checkout), payments, auth.
Tests: npm test -w apps/web-store

# packages/ui-kit/LOCAL_SUMMARY.md
Purpose: shared UI components.
Exports: src/index.ts
Icons: src/icons/*, add new icons by exporting from index.
Do not touch: theming tokens, build config.
Tests: npm test -w packages/ui-kit

Håll sedan loopen tight:

1. Karta: "Den här ändringen är begränsad till CartPage och ui-kit-ikoner. Ingen checkout/auth-ändring."
2. Antaganden: kräva en lista över antaganden och invänta bekräftelse.
3. Filbegäran: godkänn endast de få filer som verkligen behövs (CartPage, useCart, ui-kit icons, ui-kit index).
4. Plan: bekräfta att den matchar gränserna.
5. Ändringar: gör minsta diff, och begär uppdaterade tester.

Efter ändringen, dokumentera den så framtida kontext hålls liten:

• Uppdatera båda lokala sammanfattningar med den nya exporten och de exakta filerna som rördes.
• Lägg till en kort kommentar i cart-sidans header: vad knappen gör och var state hanteras.
• Anteckna testkommandon som passerade (och eventuella snapshots som uppdaterades).

Nästa steg: gör detta upprepbart för ditt team

Om det fungerar väl för en person men inte för resten av teamet är den saknade biten oftast upprepbarhet. Gör "god kontexthygien" till standard, inte en personlig vana.

Gör dina bästa prompts till en teammall

Spara en prompt-skelett som alla kan kopiera och fylla i. Håll den kort men strikt. Inkludera målet (vad "klart" betyder), tillått scope, hårda gränser (och varför), en lokal sammanfattning och ett output-kontrakt (plan först, sedan diff-liknande ändringar och tester).

Håll sammanfattningarna aktuella med en lättviktig rytm

Hoppa över stora månatliga genomgångar som ingen gör. Koppla samman sammanfattningsuppdateringar till normalt arbete: när en ändring ändrar beteende, beroenden eller API:er, uppdatera den lokala sammanfattningen i samma PR.

En enkel regel: om en kollega skulle fråga "var ligger det här?" eller "vad beror detta på?", då är sammanfattningen inaktuell.

Om ni föredrar ett chatt-först-workflow kan Koder.ai underlätta denna typ av iteration. Planning mode hjälper er att enas om scope och gränser innan ändringar görs, och snapshots med rollback låter er prova ändringar utan att fastna när en gissning visar sig vara fel.