Claude Code Meesterschap Deel 3: Projectconfiguratie

Hier is iets waar bijna iedereen die nieuw is met Claude Code tegenaan loopt: ze beginnen het te gebruiken op een project, krijgen matige resultaten en concluderen dat het gewoon niet zo goed is. Maar dan zien ze iemand anders fantastische resultaten behalen op een vergelijkbare codebase. Wat is het verschil?

Configuratie.

Een goed geconfigureerde Claude Code-sessie begrijpt niet alleen je code—het begrijpt je patronen, je conventies, de voorkeuren van je team. Het weet dat je Bun gebruikt in plaats van npm, dat API-routes in app/api/ staan, en dat je team uitgesproken meningen heeft over foutafhandeling. Dit hoofdstuk laat je zien hoe je dat instelt.

CLAUDE.md: Het Geheugen van je Project

CLAUDE.md wordt automatisch geladen wanneer Claude Code opstart. Zie het als de handleiding die je aan een nieuwe ontwikkelaar geeft op hun eerste dag—alleen leest Claude het bij elke sessie opnieuw.

Waar Zet je Het Neer

Claude Code gebruikt een hiërarchisch systeem voor het laden van CLAUDE.md-bestanden:

Projectroot (meest voorkomend):

Your-project/CLAUDE.md

Check het in via git. Deel het met je team. Dit is wat je in 90% van de gevallen wilt.

Alternatieve locatie:

Your-project/.claude/CLAUDE.md

Zelfde effect, maar houdt je projectroot schoner.

Globaal (geldt voor alle projecten):

~/.claude/CLAUDE.md

Persoonlijke voorkeuren die je overal volgen. Handig voor dingen als "ik prefereer tabs boven spaties" of "gebruik altijd TypeScript strict mode."

Lokale variant (gitignored):

Your-project/CLAUDE.local.md

Persoonlijke tweaks die je niet wilt committen. API-keys, experimentele instellingen, of die controversiële codeerstijl die je team niet deelt.

Monorepo-ondersteuning

Hier wordt het slim. In een monorepo kun je het volgende hebben:

Monorepo/
├── CLAUDE.md              # Geladen voor alles
├── apps/
│   ├── web/
│   │   └── CLAUDE.md      # Geladen bij werk in web/
│   └── api/
│       └── CLAUDE.md      # Geladen bij werk in api/
└── packages/
    └── shared/
        └── CLAUDE.md      # Geladen bij werk in shared/

Wanneer je claude uitvoert vanuit monorepo/apps/web, worden zowel de root CLAUDE.md als de web-specifieke versie geladen. CLAUDE.md-bestanden in submappen worden on-demand ingeladen wanneer je met bestanden in die mappen werkt.

Wat Zet je in CLAUDE.md

Een goede CLAUDE.md beantwoordt drie vragen:

WAT — Wat is dit project? Wat is de tech stack? Wat is de mapstructuur?

WAAROM — Wat is het doel? Welk probleem lost het op? Wat zijn de belangrijkste zakelijke concepten?

HOE — Hoe werk je eraan? Welke commando's draaien tests? Wat is het deploymentproces? Hoe verifieer je wijzigingen?

Een Praktisch Template

# Project Name

Eén zin: wat dit is en wat het doet.

## Tech Stack

- Next.js 14 (App Router)
- TypeScript (strict mode)
- Tailwind CSS
- Prisma + PostgreSQL
- Jest for testing

## Directory Structure

Src/
├── app/           # Next.js routes
├── components/    # Reusable UI components
├── lib/           # Utilities and helpers
├── services/      # Business logic
└── types/         # TypeScript interfaces

## Commands

- `bun dev` - Start development server (port 3000)
- `bun test` - Run Jest tests
- `bun lint` - ESLint check
- `bun build` - Production build
- `bunx prisma studio` - Database GUI

## Coding Conventions

- Use path aliases (@/components, @/lib, @/services)
- Server components by default, 'use client' only when needed
- All functions must have typed parameters and return types
- Keep methods small with single responsibility
- Tests colocated with components (Component.test.tsx)

## Important Notes

- Never commit .env files
- Run `bunx prisma generate` after schema changes
- API routes use Zod for runtime validation
- Authentication uses NextAuth with JWT strategy

Frameworkspecifieke Voorbeelden

Next.js App Router:

## Next.js Conventions

- Server Components by default
- Use 'use client' only for useState, useEffect, event handlers
- Data fetching: direct DB calls in Server Components, SWR in Client
- API Routes: app/api/[route]/route.ts
- File naming: PascalCase components, camelCase utilities

Python FastAPI:

## FastAPI Conventions

- Type hints on all functions
- Async/await for I/O operations
- Pydantic v2 models for request/response validation
- Dependency injection for services
- Alembic for migrations: `alembic upgrade head`

Go:

## Go Conventions

- Standard project layout (cmd/, internal/, pkg/)
- Use interfaces for testability
- Error wrapping with fmt.Errorf and %w
- Tests in same package with _test.go suffix
- Run `go test ./...` before commits

Het Importsysteem

CLAUDE.md-bestanden kunnen andere bestanden importeren met de @pad/naar/bestand-syntax. Dit houdt je hoofdbestand compact terwijl het toch uitgebreide context biedt.

# Project Overview

See @README.md for detailed project description.
See @docs/api-patterns.md for API conventions.
See @docs/testing-guide.md for testing requirements.

## Quick Reference

@package.json shows available npm scripts.

Hoe imports werken:

• Relatieve paden worden opgelost ten opzichte van de locatie van het CLAUDE.md-bestand
• Imports kunnen recursief zijn (tot 5 niveaus diep)
• Codeblokken worden uitgesloten (imports binnen ``` worden niet geëvalueerd)
• Latere imports hebben voorrang op eerdere

Organiseren met een rules-map:

Voor grotere projecten kun je instructies opsplitsen in meerdere bestanden:

.claude/
├── CLAUDE.md           # Hoofdbestand
└── rules/
    ├── coding-style.md
    ├── testing.md
    ├── security.md
    └── deployment.md

Alle .md-bestanden in .claude/rules/ worden automatisch geladen als projectgeheugen.

De #-Toetssnelkoppeling

Hier is een productiviteitstip die de meeste mensen missen: druk tijdens een Claude Code-sessie op # om instructies direct aan je CLAUDE.md toe te voegen.

Merk je dat je steeds dezelfde instructie herhaalt? Druk op # en voeg het permanent toe. Claude onthoudt het de volgende keer.

Settings.json: Rechten en Automatisering

Naast CLAUDE.md kun je het gedrag van Claude configureren met instellingenbestanden.

Bestandslocaties

~/.claude/settings.json           # Globaal (alle projecten)
.claude/settings.json             # Project (gecommit naar git)
.claude/settings.local.json       # Lokaal (gitignored)

Instellingen worden samengevoegd in volgorde van prioriteit: lokaal > project > globaal.

Rechtenconfiguratie

Bepaal wat Claude mag doen zonder te vragen:

{
  "permissions": {
    "allow": [
      "Read(./src/**)",
      "Read(./tests/**)",
      "Bash(git status)",
      "Bash(git diff)",
      "Bash(bun test:*)",
      "Bash(bun lint)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(rm *)",
      "Bash(git push *)"
    ]
  }
}

Hoe regels worden geëvalueerd:

1. Deny-regels worden eerst gecontroleerd (blokkeren ongeacht andere regels)
2. Allow-regels worden daarna gecontroleerd (toestaan als er een match is)
3. Al het andere vraagt om goedkeuring

De deny-lijst is je beveiligingsgrens. Bestanden die matchen met deny-patronen worden volledig onzichtbaar voor Claude—het kan niet eens zien dat ze bestaan.

Hooks: Geautomatiseerde Acties

Hooks voeren commando's uit op specifieke momenten in de levenscyclus van Claude:

PreToolUse — Voordat Claude een tool gebruikt (kan de actie blokkeren)

PostToolUse — Nadat een tool is voltooid (ideaal voor formatters)

SessionStart — Wanneer een sessie begint (omgeving opzetten)

Notification — Wanneer Claude notificaties verstuurt

Stop — Wanneer Claude klaar is met reageren

Voorbeeld: Python-bestanden automatisch formatteren na bewerkingen:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "if [[ \"$CLAUDE_FILE_PATH\" == *.py ]]; then black \"$CLAUDE_FILE_PATH\"; fi"
          }
        ]
      }
    ]
  }
}

Voorbeeld: Wijzigingen aan productieconfiguraties voorkomen:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write(./config/production.*)",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Blocked: Cannot modify production config' && exit 1"
          }
        ]
      }
    ]
  }
}

Tip: Je kunt hooks ook interactief configureren met het /hooks-commando tijdens een sessie.

Teamconfiguratie

Voor teams: dit is wat je commit vs. gitignored:

Commit deze (gedeeld met het team):

• CLAUDE.md — Projectinstructies die iedereen moet volgen
• .claude/settings.json — Gedeelde rechten en hooks
• .claude/rules/ — Georganiseerde instructiebestanden
• .claude/commands/ — Team slash-commando's (behandeld in Deel 4)

Gitignore deze (persoonlijk):

• CLAUDE.local.md — Je persoonlijke voorkeuren
• .claude/settings.local.json — Je lokale overschrijvingen

Zo kunnen teams standaarden afdwingen terwijl individuen hun ervaring kunnen aanpassen.

Best Practices die er Echt Toe Doen

Houd Het Compact

Onderzoek suggereert dat geavanceerde LLM's (Large Language Models, grote taalmodellen) betrouwbaar zo'n 150-200 instructies kunnen opvolgen. Daarboven daalt de naleving. Kleinere modellen verwerken er nog minder.

Doe dit niet:

## General Guidelines
- Write clean code
- Follow best practices
- Use meaningful variable names
- Keep functions small

Claude weet deze dingen al. Je verspilt waardevolle instructieruimte aan generiek advies.

Doe dit in plaats daarvan:

## Project-Specific Rules
- Error responses use the ApiError class from @/lib/errors
- All dates stored as UTC, displayed in user's timezone
- Feature flags checked via @/lib/features.isEnabled()
- Log format: [LEVEL] [SERVICE] [REQUEST_ID] message

Neem alleen op wat uniek is voor jouw project.

Itereer Zoals een Prompt

Je CLAUDE.md is onderdeel van Claude's prompt. Behandel het ook zo.

• Test of instructies daadwerkelijk gedrag veranderen
• Voeg nadruk toe voor kritieke regels: "IMPORTANT:" of "YOU MUST"
• Verwijder instructies die niet worden opgevolgd
• Laat het af en toe door Claude's prompt improver halen

Bij Anthropic stemmen ze CLAUDE.md-bestanden op dezelfde manier af als prompts—continu itereren op basis van wat daadwerkelijk werkt.

Gebruik /init als Startpunt

Het uitvoeren van /init genereert een CLAUDE.md door je project te analyseren. Maar het is een startpunt, geen eindproduct.

De automatisch gegenereerde versie vangt voor de hand liggende patronen op (tech stack, mapstructuur, veelgebruikte commando's), maar mist de stamkennis van je team. Bekijk wat Claude produceert en voeg toe wat het belangrijkst is voor hoe je daadwerkelijk werkt.

Draai /init opnieuw na grote features of refactors om nieuwe patronen op te pikken.

Je Configuratie Testen

Na het opzetten van je CLAUDE.md, verifieer of het werkt:

Claude

Vraag dan:

Summarize the project configuration and conventions you understand.
What tech stack is this? What commands should you use for testing?

Als Claude iets belangrijks mist, heeft je CLAUDE.md werk nodig.

Wat Komt er Hierna

Je weet nu hoe je Claude Code configureert voor jouw specifieke project. Maar configuratie gaat maar tot op zekere hoogte—de echte kracht komt van het uitbreiden van Claude met aangepaste commando's.

In Deel 4: Aangepaste Commando's bouwen we slash-commando's die je workflows omzetten in herbruikbare acties. Zie het als het aanleren van de snelkoppelingen van je team aan Claude.