Claude Code onder de knie

Stap 1. Node.js. Open je terminal en typ node --version. Staat er v22 of hoger? Ga dan verder. Zo niet: op Mac gebruik je brew install node, of download het via nodejs.org. Check daarna: node --version moet v22.x.x tonen. Stap 2. VS Code of Cursor. Download via code.visualstudio.com (gratis) of cursor.com. Installeer, open, klaar. Stap 3. Claude Code CLI. Typ in je terminal: npm install -g @anthropic-ai/claude-code. Check met: claude --version. Eerste keer opstarten: typ claude en log in wanneer dat gevraagd wordt. Stap 4. Docker Desktop. Download via docker.com/products/docker-desktop. Installeer en open het. Het draait op de achtergrond. Check: docker --version. Stap 5. GitHub. Maak een account aan op github.com. Voer daarna in je terminal uit: git config --global user.name "Your Name" en git config --global user.email "your@email.com". Check: git --version. Stap 6. Supabase. Ga naar supabase.com, maak gratis een account aan en start een project. Ga naar Settings, dan API. Kopieer de project URL en de anon key naar een veilige plek. Stap 7. Vercel. Ga naar vercel.com en registreer je met GitHub. Meer hoef je nu niet te doen. Alles werkt als elk van deze commando's een versienummer teruggeeft: node --version, npm --version, git --version, docker --version, claude --version.

Maak een bestand aan genaamd CLAUDE.md in je projectroot. Zie het als de werkinstructies voor Claude Code. Sectie 1. Huidige status. In welke fase je zit, wat er klaar is, wat er nog aankomt. Bijwerken na elke commit, niet elke sessie. Claude leest dit als eerste, dus het bepaalt direct wat hij oppakt. Sectie 2. Vaste regels. Afspraken waar niet van afgeweken wordt. "Database eerst: voer migraties uit vóór de code." "Geen hardgecodeerde kleuren: gebruik CSS custom properties." "i18n altijd: alle tekst via next-intl." Zonder deze regels maakt Claude keuzes die logisch lijken maar toch fout zijn. Sectie 3. Bron van waarheid. Welke documenten gezaghebbend zijn. Zo voorkom je dat Claude content verzint terwijl er al een briefing bestaat. Sectie 4. Kritieke bestanden. Bestanden die je niet zomaar wijzigt. Middleware, migraties, design tokens. Claude waarschuwt je voordat hij ze aanpast. Sectie 5. AI-agentregels. Wat Claude automatisch doet. "Na elke commit: update de huidige status." Daarmee wordt Claude een actief onderdeel van het project in plaats van een passief gereedschap. Test dit even. open Claude Code vanuit je projectmap en vraag "Waar werken we aan?" Als Claude antwoord geeft op basis van je CLAUDE.md, werkt het bestand.

MCP 1. Supabase (meeste impact). Claude kan je database bevragen, tabellen inspecteren, RLS-policies checken en migraties uitvoeren. Handmatig SQL schrijven is verleden tijd. Setup: npx supabase mcp setup. Het vraagt om je project-URL en service role key. Test: vraag Claude "Welke tabellen staan er in mijn database?" Claude somt ze op.

Het verschil. voor MCP vertel jij Claude hoe je schema eruitziet. Na MCP inspecteert Claude het echte schema. Migraties kloppen omdat Claude de werkelijkheid ziet, niet jouw omschrijving.

MCP 2. Context7 (documentatie). Claude zoekt actuele docs op voor elke library, geen trainingsdata van maanden geleden maar de versie van vandaag. Verificatie: vraag Claude een specifieke API van Next.js of Supabase op te zoeken.

MCP 3. Vercel. Claude checkt de deployment-status, zet omgevingsvariabelen en beheert projecten. Concreet: "Zet de Supabase URL en anon key als Vercel-omgevingsvariabelen" en Claude regelt het. Geen dashboard-geklik.

MCP 4. Figma (als je Figma gebruikt). Claude leest design specs uit Figma-bestanden. Componentafmetingen, kleuren, spacing, typografie. Exacte waarden in plaats van gokken op basis van screenshots.

Na de setup. vraag Claude "Welke MCPs heb je tot je beschikking?" Claude geeft een lijst en bevestigt de verbinding.

Maak de skills-map aan met `mkdir -p .claude/skills`. Skills zijn markdown-bestanden die Claude oppikt wanneer ze relevant zijn. Auto-skills activeren op basis van trefwoorddetectie. Handmatige skills roep je aan via `/skill-name`. Skill 1. critical. Maak `.claude/skills/critical/SKILL.md` aan. Hier komen je harde regels: database eerst, migraties altijd vóór code. Geen hardgecodeerde kleuren, gebruik CSS-variabelen. Valideer alle input bij POST/PUT/PATCH. Commit nooit secrets. Draai de build vóór je commit. Voeg een sectie Lessons Learned toe. Elke fout in productie levert een nieuwe regel op. Skill 2. page-build. Maak `.claude/skills/page-build/SKILL.md` aan. Leg hier je bouwconventies vast: de bestandsstructuur voor nieuwe pagina's, spacing-standaarden, typografieregels, testvereisten en de commit-checklist. Skill 3. eod (end of day). Maak `.claude/skills/eod/SKILL.md` aan. De afsluiting: update de status in `CLAUDE.md`, stage gewijzigde bestanden, commit met een duidelijke beschrijving, push en schrijf een samenvatting voor morgen. Controleer of het werkt door Claude te vragen welke skills beschikbaar zijn. Test daarna met "Ik wil een nieuwe pagina bouwen." Claude pakt dan automatisch je page-build conventies op. Nog één ding om te onthouden. skills zijn instructies, geen documentatie. Schrijf ze als opdrachten. "Use CSS custom properties" in plaats van "The project uses CSS custom properties."

Stap 0. Controleer je omgeving. Werk je aan meerdere projecten, draai even je checkscript. Zo weet je zeker dat Supabase, Vercel en Git naar de juiste omgeving wijzen. Kost je drie seconden, scheelt je een hersteloperatie op de verkeerde database. Stap 1. Open je project in VS Code. Start de terminal en typ `claude`. Claude Code laadt automatisch je CLAUDE.md én de bijbehorende skills, zodat het je werkwijze en conventies al kent voordat je de eerste vraag stelt. Stap 2. Vraag de status op. Stel Claude de vraag. "What's our current status?" Het leest CLAUDE.md en geeft je een overzicht. Klopt er iets niet, herstel dat meteen. Stap 3. Kijk wat er op de planning staat. "What are the next deliverables?" Claude leest je roadmap of CLAUDE.md en geeft een lijst terug. Zo weten jullie allebei waar de sessie naartoe gaat. Drie stappen, twee minuten. Daarna is Claude volledig ingelicht. Lang niet aan het project gewerkt? Geen probleem. CLAUDE.md bevat de huidige status. Het restartbestand heeft de aantekeningen van de vorige sessie. De setup-info skill slaat de omgevingsinstellingen op. Claude leest alles automatisch bij het opstarten. Je zit meteen weer waar je gebleven was.

Stap 1. plan eerst, bouw daarna. Typ niet "bouw een contactformulier." Typ: "Ik heb een contactformulier nodig. Voordat je code schrijft, plan je de aanpak. Welke componenten? Welke API-route? Welke validatie? Welke tests?" Claude stelt voor, jij stuurt bij. Kwaliteit bij de eerste poging gaat van 80% naar 95%. Stap 2. bouw in kleine stukken. Niet de hele feature in één keer. "Bouw de formuliercomponent." Dan "Voeg validatie toe." Dan "Maak de API-route aan." Dan "Voeg e-mailverzending toe." Elk stuk is klein genoeg om te reviewen, te testen en terug te draaien. Stap 3. test terwijl je bouwt. Na het bouwen van het formulier: "Schrijf een Playwright-test die controleert of het formulier op alle locales wordt weergegeven en verplichte velden valideert." Draai die meteen. Los fouten op voordat je verdergaat. Stap 4. tweede ronde. Als de feature klaar is: "Review alles wat je net gebouwd hebt. Controleer op ontbrekende foutafhandeling, inconsistente naamgeving, hardcoded strings, toegankelijkheidsproblemen, problemen met de mobiele layout." Claude vindt altijd iets. Repareer dat meteen. Stap 5. commit. Stage specifieke bestanden, niet git add -A. Beschrijvende commit-message. Werk de CLAUDE.md-status bij. Een contactformulier bouwen kost op deze manier 45 tot 60 minuten. Zonder dit proces kost het evenveel tijd, maar dan met meer bugs, geen tests en hardcoded strings die je er later alsnog uit moet halen.

De snelle check (2 minuten, vóór elke commit). npm run build. Geen errors? Code compileert. Dan npx playwright test. Alle tests groen. Iets rood? Fix het eerst. Nooit committen als je weet dat er iets stukzit. De grondige check (10 minuten, aan het einde van een fase): 1. Hardcoded waarden. Doorzoek src/ op hex-kleuren, losse strings en pixelwaarden die tokens moeten worden. 2. TypeScript-kwaliteit. Let op. het type `any` (vervang door een echt type), `console.log` (weghalen voor je commit), TODO-comments (bijhouden). 3. Beveiliging. Valideert elke API-route de input? Staan er secrets in je commits? Heeft elke nieuwe tabel RLS? 4. i18n-volledigheid. Zitten er nog Engelse strings in je componenten? Hebben alle drie de locale-bestanden dezelfde keys? 5. Build en tests. npm run build zonder errors. npx playwright test alles groen. Open localhost en kijk even zelf. Automatiseer dit. maak een phase-check skill die alle vijf stappen uitvoert. Of vraag het aan Claude: "Run a quality check on the codebase." Claude pakt ze allemaal op.

Stap 1. Werk de CLAUDE.md-status bij. "Noteer waar je staat. de contactpagina is klaar, de insights-pagina is volgende." Stap 2. Schrijf je herstartnotes. "Waar hebben we vandaag aan gewerkt? Welke keuzes hebben we gemaakt? Waar beginnen we morgen mee?" Sla dit op in CLAUDE.md of een restart.md bestand. Stap 3. Commit alles. Stage de gewijzigde bestanden, schrijf een helder commit-bericht en push. Stap 4. Controleer de push. Gelukt? Als je Vercel gebruikt, kijk dan of de deployment gestart is. Wat je hiermee voorkomt. verwarring de volgende ochtend ("Waar was ik ook alweer?"), verloren context ("Waarom kozen we Zod en niet yup?"), werk dat uncommitted blijft liggen, en een CLAUDE.md die morgen al verouderd is. Het cumulatieve effect is simpel. Na een week heb je een projectdagboek. Na een maand kun je elke beslissing terugvinden. Na drie maanden leest een nieuw teamlid de geschiedenis en begrijpt niet alleen wat er gebouwd is, maar ook waarom.

Skills groeien van fouten. Je deployt een pagina met ontbrekende Duitse vertalingen. Nieuwe regel in critical: "Commit nooit i18n-wijzigingen zonder alle drie de locale-bestanden te controleren." Die fout maak je nooit meer.

Skills groeien van patronen. Je hebt vijf pagina's gebouwd met dezelfde structuur. De page-build skill wordt beter: preciezere spacing-waarden, een testchecklist die vangt wat je eerder hebt gemist.

Skills groeien van onderzoek. Je ontdekt dat getSession() de client-JWT vertrouwt zonder verificatie. Nieuwe regel in security: "Gebruik altijd getUser() voor auth-checks." Zet er de reden bij, zodat je weet waarom.

Een nieuwe skill stap voor stap opbouwen. mkdir -p .claude/skills/i18n. Begin met wat je weet: alle tekst via useTranslations, keys toevoegen aan alle drie de locale-bestanden, Nederlandse informele toon (je/jij), technische termen in het Engels, namespace per pagina. Begin met 3 regels. Voeg meer toe naarmate je leert.

Maandelijkse review. lees je skills door. Verwijder verouderde regels. Combineer duplicaten. Pas aan wat is veranderd. Bijgehouden skills zijn een levende kennisbank. Vergeten skills worden misleidend.

Het cumulatieve effect. na drie maanden heeft je critical skill 20+ regels. Dat zijn 20 fouten die nooit meer voorkomen. Elk nieuw teamlid erft al die kennis op dag één.

Één bestand per pagina. e2e/about.spec.ts, e2e/contact.spec.ts. Elk bestand dekt vier dingen. 1. De pagina laadt. Alle drie de locales geven 200 terug. Loop door en, nl, de en verifieer elk. 2. De content klopt. Belangrijke tekst verschijnt in de juiste taal. Niet "de pagina laadt" maar "de Nederlandse heading zegt wat hij moet zeggen." 3. Werkt op mobiel. Geen horizontale overflow bij 375px. Vergelijk scrollWidth met clientWidth. 4. Interactieve elementen doen het. Formulieren valideren, navigatie opent, accordions klappen open en dicht. Claude om tests vragen doe je zo. niet "schrijf tests voor contact" maar "Schrijf Playwright-tests voor de contactpagina. Test: 200 status alle locales, formuliervalidatie (leeg toont foutmeldingen, geldig slaagt), responsive bij 375px, juiste heading per locale." Concrete vragen leveren concrete tests op. Na 10 pagina's heb je 50+ testcases. npx playwright test voor een commit draaien kost 30 seconden en pakt regressies op die je handmatig nooit ziet. Refactoren wordt betrouwbaar omdat tests laten zien wat er eventueel kapot is gegaan. En dan de praktijk. test gedrag, geen weergave. Design-aanpassingen en copy-wijzigingen hebben geen tests nodig. Formulierinzendingen en API-routes wel.

Heb je dit eigenlijk nodig? Als je solo werkt op één machine. prettig, maar geen must. Met meerdere developers: geen "werkt bij mij wel"-discussies meer. En als je naar productie deployt, wil je dat je lokale omgeving en de server hetzelfde draaien. Stap 1. Dockerfile.dev aanmaken Voor development met hot reload. De inhoud. `FROM node:22-alpine`, `WORKDIR /app`, package-bestanden kopiëren, `RUN npm install`, de rest van de code kopiëren, `EXPOSE 3000`, en `CMD npm run dev`. Stap 2. docker-compose.yml aanmaken Hier definieer je een `dev`-service die bouwt vanuit je Dockerfile.dev, port 3000 doorstuurt, je projectmap als volume koppelt zodat je wijzigingen meteen terugziet, en de variabelen uit `.env.local` doorgeeft. Stap 3. opstarten Voer `docker compose up dev` uit en open `localhost:3000`. Je project draait nu in Docker. Pas een bestand aan in VS Code en de browser ververst vanzelf. Voelt precies als `npm run dev`, maar dan op elke machine gelijk. Stap 4. stoppen `docker compose down`. Dat is het. Wat je zojuist hebt opgezet. je project draait in een container met Node 22 op Alpine Linux, los van wat er verder op jouw machine staat. Een collega kloont de repo, tikt `docker compose up dev`, en zit direct in dezelfde omgeving. Voor productie gebruik je een Dockerfile met meerdere bouwfases: base, dependencies, build en runner. Die laatste fase draait als gewone gebruiker zonder rootrechten, op een zo klein mogelijke image. Vraag Claude om er een te genereren die past bij jouw project.

Dag 1 vs dag 30.

CLAUDE.md begon met 5 regels, nu zijn het er 15. Elke nieuwe regel pakt een fout aan die één keer voorkwam en daarna nooit meer. Het Current Status-gedeelte is al meer dan 40 keer bijgewerkt. Altijd kloppend.

Skills begon met 3, nu 8 tot 10. Elke skill verdient zijn plek door een terugkerend probleem op te lossen. De belangrijkste bevat 15 of meer lessons learned. Nieuwe teamleden lezen het en lopen niet meer vast op fouten die jij al hebt gemaakt.

Tests begon op 0, nu meer dan 100. Elke pagina getest in alle locales. Elk formulier gevalideerd. Refactoring is veilig omdat tests regressies in 30 seconden pakken.

Dagritme De ochtendcheck duurt 2 minuten en geeft je meteen de juiste context. Bouwen verloopt voorspelbaar. Kwaliteitschecks lopen vanzelf. De avondafronding kost 5 minuten en de volgende dag begin je precies waar je gebleven was.

Compounding Elke skill maakt Claude scherper. Elke test maakt refactoring veiliger. Elke CLAUDE.md-update laadt de context sneller. Het systeem houdt kwaliteit niet alleen op peil, de standaard stijgt mee.

Eerlijk gezegd beklijft niet elke les meteen op dag 1. De ochtendcheck wordt pas automatisch na een week. De tweede review voelt als verloren tijd, tot je er een productiebug mee vangt. Skills voelen als overhead, tot ze voor de derde keer dezelfde fout voorkomen. Geef het 30 dagen.