Claude Code Plan Mode: refactorings in review-first-lussen

Veel developers beginnen op dezelfde manier met Claude Code: plak een taak, laat \'m draaien en bekijk de diff. Dat werkt voor kleine wijzigingen, maar zodra je meerdere bestanden raakt, gaat het mis. 

Elke ongerichte beslissing die Claude neemt kan meestal wel kloppen, maar gecomponeerd wordt het riskant: ga je bijvoorbeeld uit van 80% nauwkeurigheid per beslissing, dan daalt over een feature met 20 beslismomenten 0.8^20 je kans tot ongeveer 1%.

Planmodus verandert die rekensom door een alleen-lezenfase toe te voegen. Je dwingt Claude de codebase te lezen, vragen te stellen en een plan te maken dat jij beoordeelt voordat er ook maar één bestand wordt aangeraakt. 

Deze tutorial doorloopt die workflow met een rommelige FastAPI-blog-API als doorlopend voorbeeld. We behandelen de Explore-Plan-Execute-loop, planbewerking met Ctrl+G en opschalen naar grotere refactors met Agent Teams. 

Onze Claude Code best practices-tutorial gaat dieper in op het probleem van cumulatieve fouten, en de Claude Code 2.1-gids helpt je stap voor stap met installatie en features als je hulp nodig hebt bij de setup.

Wil je meer weten over de modellen achter Claude Code, bekijk dan onze gidsen voor Claude Sonnet 4.6 en Opus 4.6, of volg de cursus Introduction to Claude Models.

Wat is de Planmodus van Claude Code?

Planmodus zet Claude vast in alleen-lezenoperaties. Hij kan bestanden lezen, de codebase doorzoeken en je vragen stellen, maar elke poging om bestanden te schrijven, code te bewerken of shellcommando's uit te voeren wordt geweigerd. Vraag je in Planmodus om "even snel die ene fix te maken", dan gebeurt er niets.

Je kunt het op vier manieren activeren:

• Shift+Tab twee keer in het invoerveld wisselt tussen Normal, Auto-Accept en Plan Mode

• Het /plan commando zet je in Planmodus totdat je weer van modus wisselt

• De CLI-vlag --permission-mode plan start een nieuwe sessie in Planmodus

• Een settings.json-entry onder permissions.defaultMode stelt Planmodus in als je permanente standaard

Zodra Claude een plan heeft gegenereerd, slaat hij het op als een markdownbestand in ~/.claude/plans/ met een willekeurig gegenereerde naam (zoals dreamy-orbiting-quokka.md). 

Het bestand is een reviewbaar contract: het blijft bestaan over sessies heen, overleeft zowel /clear als contextcompactie, en er wordt niets geïmplementeerd voordat jij het goedkeurt. Let op: het planbestand zelf blijft bestaan, maar Claude kan het soms uit het oog verliezen na contextcompactie, tenzij je hem vraagt het plan opnieuw te lezen.

Wil je plannen binnen je project opslaan voor versiebeheer, stel dan plansDirectory in settings.json in op een projectrelatief pad zoals ./plans.

Projectrelatieve plannen openen workflows die ~/.claude/plans/ niet ondersteunen:

• Review plan-diffs in pull requests voordat iemand gaat coderen
• Draag annotaties sessie-overstijgend mee zonder te vertrouwen op contextcompactie
• Behandel het markdownbestand als een levend spec-document dat meerdere teamleden direct bewerken

Voor langdurige refactors of werk over meerdere sessies geeft een versiebeheerd planbestand je meer controle dan alleen Ctrl+G.

Een Explore-Plan-Execute-workflow met Claude Code implementeren

Om te zien hoe de drie fases samenwerken, refactoren we een fastapi-blog-api-repo. Er zitten geen tests bij en er zijn drie bestanden die elk te veel doen: 

• main.py: alle routes, inline auth-checks, hardcoded config, e-mailverzending

• models.py: ORM-modellen, Pydantic-schemas, queryfuncties, seeddata

• utils.py: wachtwoordhashing, JWT-tokens, S3-uploads, markdownrendering, caching, rate limiting, CSV-export

Fase 1: Verzamel eerst context

Start de taak in Planmodus (clone de GitHub-repo eerst lokaal). De openingsprompt moet Claude vertellen wat je wilt en hem aanwijzen welke bestanden hij moet lezen:

I want to refactor this FastAPI blog API into a clean module structure with proper separation of concerns and full test coverage. Read through main.py, models.py, and utils.py first. Map out which functions belong together, flag any shared state or circular dependency risks, and identify what needs testing most.

Claude delegeert codebase-onderzoek aan een ingebouwde subagent met alleen-lezen-tools. Hij las alle drie de bestanden, volgde de imports ertussen en gebruikte AskUserQuestion om onduidelijkheden te signaleren. 

De vragen raakten een paar beslissingen op hoofdlijnen:

• Architecturale diepte (platte routers vs. volledige servichelagen)
• Hoe om te gaan met hardcoded config
• Of dode utility-functies verwijderd of behouden moeten worden
• Welke testframework te gebruiken

Die vragen doen ertoe. De architectuurkeuze alleen al was zonder menselijke input een muntje-opgooien geweest. Claude valt terug op wat hij het vaakst in trainingsdata heeft gezien, wat voor FastAPI meestal een platte routerstructuur is. Door hier te antwoorden met "gebruik een servicelaag" hebben we een hele ronde her-refactoring bespaard.

Heb je een referentieproject dat past bij je doelsarchitectuur, voeg daar dan een link naar toe in je prompt. Claude maakt betere plannen met een werkend voorbeeld om op terug te vallen dan met abstracte beschrijvingen.

Controleer één ding voordat je een plan accepteert: verwijzen Claude’s vragen naar specifieke functies en details op regelniveau, of alleen naar bestandsnamen? Als hij het heeft over "het auth-systeem" maar nooit verify_jwt_token of de middleware-keten in main.py noemt, heeft hij geskimd in plaats van echt gelezen. Dwing hem zorgvuldiger te lezen voordat je naar Fase 2 gaat.

Fase 2: Genereer en bewerk het plan

Nadat je Claude’s vragen hebt beantwoord, genereert hij automatisch een plan. Geen aparte prompt nodig. Het plan wordt opgeslagen in ~/.claude/plans/ en bevat: 

• Contextsamenvatting
• Gewenste mapstructuur
• Stapsgewijze implementatievolgorde
• Verificatiesectie met commando\'s om te bevestigen dat de refactor geslaagd is

Voordat je kiest hoe je verdergaat, druk op Ctrl+G om het plan te openen in je standaard teksteditor (ingesteld via $EDITOR). Of gebruik /plan open om het actieve planbestand direct te openen.

Planmodus verdient zichzelf hier terug. Je kunt stappen annoteren met inline notities, stappen verwijderen waar je het niet mee eens bent, bewerkingen herordenen en opslaan. Claude pikt elke wijziging op zodra je terugkeert naar de terminal.

Voor het blog-API-plan kunnen annotaties er zo uitzien:

## Step 3: Extract auth module
Move JWT validation and password hashing to auth/
> NOTE: extract auth middleware BEFORE splitting routes,
> otherwise the route files will import from utils.py
> and we'll have to update imports twice
 
## Step 5: Database layer
Create a repository pattern for database operations
> NOTE: keep the SQLAlchemy session factory in a shared
> db.py, don't put it in models.py

Voor complexe plannen is één Ctrl+G-ronde soms niet genoeg. Annoteer, kom terug, zeg tegen Claude "verwerk alle annotaties in het plan, nog niet implementeren", beoordeel de herziene versie en Ctrl+G nog eens. Elke annotatieronde haalt ambiguïteit weg die anders zou uitmonden in een verkeerde implementatiebeslissing.

Als het contract goed voelt, biedt Claude een paar opties: 

1. Werk aan het plan en wis de context (handig als de sessie muf wordt), 
2. Werk zonder wissen (om je gespreksgeschiedenis te behouden), of 
3. Blijf doorpraten over het plan. 

Kies op basis van hoeveel context je hebt opgebouwd. Als je diep in een lange sessie zit, geeft wissen Claude een frisse start voor de uitvoering.

Fase 3: Voer het goedgekeurde plan uit

Kies een werkoptie en Claude begint stap voor stap te implementeren. Hij werkt elke stap af en stopt wanneer handmatige interventie nodig is (zoals interactieve auth in de terminal) of wanneer het hele plan voltooid is.

Let op drift. Het plan zei eerst auth naar een eigen module te extraheren, maar Claude kan routes en auth-logica tegelijk gaan verplaatsen omdat hij een kortere weg ziet. Zo beland je in een half-gemigreerde codebase waar sommige imports nog naar de oude locatie wijzen en andere naar de nieuwe. 

Andere drift-signalen: 

• Een bestand bewerken dat niet in de huidige stap is genoemd
• Stiekem een architectuurkeuze maken die in het plan open gelaten is
• Twee stappen combineren die in het plan gescheiden bleven

Bij drift: Shift+Tab terug naar Planmodus. Claude leest de huidige bestandsstatus, maakt een herzien plan voor de resterende stappen en jij beoordeelt het voordat je doorgaat. Dit is geen noodgreep. De meeste refactors over meerdere bestanden gaan 2–3 planrevisies door voordat ze klaar zijn.

Voor refactors die niet in één sessie passen, hak het werk in opeenvolgende plannen in plaats van één groot plan. Rond auth-extractie af onder een eigen plan, start dan een frisse sessie en plan voor het splitsen van routes. 

Gebruik /rename om elke sessie te labelen (bijv. "blog-api-auth-extraction") zodat je met /resume weer kunt oppakken waar je gebleven was. Kleinere plannen houden het contextvenster gefocust en geven je een natuurlijke checkpoint tussen fasen.

Praktische strategieën voor de Planmodus van Claude Code

Nu we het hele proces eenmaal hebben doorlopen, bekijken we een paar best practices om zeker te zijn dat je het meeste uit Planmodus haalt.

Wanneer Planmodus gebruiken (en wanneer overslaan)

Niet elke taak heeft een plan nodig. Eendelige fixes, typefouten en geïsoleerde functie-updates gaan sneller zonder de overhead van plannen. Hetzelfde geldt voor mechanische wijzigingen, zoals het hernoemen van een variabele in een bestand.

Een handige vuistregel: als de wijziging drie of meer bestanden raakt, of je de volledige wijziging niet in één zin kunt beschrijven, plan dan eerst. Drie bestanden is ongeveer waar cumulatieve fouten beginnen te bijten, omdat elk bestand zijn eigen set beslissingen toevoegt die Claude goed moet krijgen.

Taken die altijd profiteren van Planmodus:

• Refactors die code tussen bestanden verplaatsen of gedeelde interfaces hernoemen
• Nieuwe features die bestaande modules raken
• Dependency-upgrades met breaking API-wijzigingen
• Elke taak waarbij je niet zeker weet hoe de codebase een specifiek geval afhandelt
• Brainstormsessies waarin je met Claude aan een aanpak wilt sleutelen zonder risico op te vroege edits

Zwakke plannen tijdig herkennen

Een plan dat er gestructureerd uitziet, is niet altijd een goed plan. Met de huidige versies van Claude Code zijn verzonnen bestandsverwijzingen en vage "update indien nodig"-stappen zeldzaam. Het probleem dat je eerder ziet: een plan dat alle implementatiestappen eerst zet en pas aan het einde "tests toevoegen".

Zulke plannen leveren slechtere resultaten op dan je zou verwachten. Zonder tests tijdens de implementatie heeft Claude geen manier om midden in de sessie zijn eigen werk te verifiëren. Voor de blog-API-refactor betekent een plan dat zegt "Stap 1–6: alle modules extraheren, Stap 7: tests schrijven" zes stappen code zonder feedbacklus. 

Een sterker plan gebruikt testgedreven ontwikkeling (TDD) en vlecht testen door de implementatie: schrijf tests voor auth/ vóórdat je de auth-functies extraheert, bevestig dat ze slagen, schrijf dan tests voor posts/ voordat je routes uittrekt. Elke geslaagde test geeft Claude een duidelijk signaal dat de refactor op koers ligt. 

Door TDD-conventies toe te voegen aan de CLAUDE.md van je project neemt Claude standaard teststappen op. Claude Code Hooks kan dit soort handhaving automatiseren door validatiescripts te draaien die de plankwaliteit controleren vóór goedkeuring van uitvoering.

Grote refactors opschalen met Agent Teams

Plannen die zeven of meer bestanden raken, verliezen aan kwaliteit omdat het contextvenster tijdens uitvoering volloopt. De blog-API-refactor raakt die drempel zodra je routes, modellen, services, config, tests en een nieuwe mapstructuur meeneemt.

Agent Teams is een experimentele feature die dit soort werk verdeelt over meerdere Claude Code-instanties. Eén sessie fungeert als teamlead, terwijl teamgenoten elk hun eigen, onafhankelijke contextvenster krijgen. 

Voor de blog-API kun je splitsen in drie teamgenoten: één voor route-extractie, één voor de database- en modelllaag, en één voor testdekking. De lead wijst taken toe, teamgenoten claimen en voltooien ze, en geblokkeerde taken (zoals "imports bijwerken" afhankelijk van "modules extraheren") deblokkeren automatisch zodra afhankelijkheden klaar zijn. 

Dezelfde splitsing werkt repo-overstijgend: als je API afhankelijk is van een gedeelde library, kan één teamgenoot de library refactoren terwijl een ander het gebruik ervan in de API bijwerkt.

De beste setup voor Planmodus is het verplicht stellen van plangoedkeuring voor teamgenoten. Zeg tegen de lead: "Start drie teamgenoten voor de blog-API-refactor. Vereis plangoedkeuring voordat ze wijzigingen maken." 

1. Elke teamgenoot plant in alleen-lezenmodus
2. De lead beoordeelt en keurt goed of wijst af met feedback
3. Alleen goedgekeurde plannen worden uitgevoerd

Je kunt het oordeel van de lead sturen met criteria: "keur alleen plannen goed die testdekking bevatten" of "wijs plannen af die het databaseschema direct wijzigen." Activeer Agent Teams door "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" toe te voegen aan het env-blok van je settings.json.

Voor eenvoudigere parallelisering zonder de experimentele vlag kun je met git worktrees aparte Planmodus-sessies op verschillende branches draaien, die elk zelfstandig hun eigen plan doorlopen.

Als een langlopende sessie contextcompactie ondergaat, laat teamgenoten hun planbestanden expliciet heropenen en opnieuw lezen om drift te voorkomen.

De Claude Code-plugins-tutorial behandelt aanvullende patronen voor het managen van werk in meerdere fasen.

Conclusie

De waarde van Planmodus komt neer op één ding: review vóór uitvoering. Elke annotatieronde die je toevoegt, elke vraag die Claude stelt in plaats van te gokken, haalt een beslissing weg die anders verkeerd zou uitpakken. 

Begin bij je volgende wijziging over meerdere bestanden, dwing Claude eerst te plannen en bewerk dat plan met Ctrl+G voordat je schrijfrechten geeft. Voor configuratie van CLAUDE.md, contextmanagement en hook-gebaseerde vangrails gaat de best practices-tutorial verder waar deze stopt. 

Voor een breder beeld van AI-assisted coding raad ik je onze AI for Software Engineering-skill track aan. Die leert je de basisconcepten en geeft je hands-on ervaring met vergelijkbare tools zoals GitHub Copilot, Windsurf of Replit.