Deel C · Module 01
Sturen: CLAUDE.md, rules, skills
Hoe leer je de agent iets?
Leerdoelen
Na deze module kun je:
- voorspellen wanneer een CLAUDE.md, een rule met
pathsen een skill in de context komen, en wat er na/compactnog van over is; - voor een instructie kiezen tussen CLAUDE.md, een rule en een skill, op basis van hoe vaak hij nodig is en wat hij aan context kost;
- een skill-description schrijven die de juiste skill laat kiezen, en
disable-model-invocationinzetten voor skills met bijeffecten.
Voorkennis-check
Twee vragen over de agentic loop en context. Fout? Lees B3 De agentic loop en B4 Context als schaars goed eerst terug.
Waar zitten we?
Deel C gaat over laag 4, de harness. Claude Code leest je instructiebestanden en zet ze in de request naar het model (laag 2). Het model ziet alleen tekst; dat die uit CLAUDE.md of een skill komt, weet het niet. Sturen werkt dus helemaal via de context, en daar gaat deze module over.
De stof in drie lagen
Kern ± 5 min lezen, daarna spelen met de visual
Uit B3 weet je dat de API niets onthoudt: elke request bevat alles wat het model weet. Wil je de agent iets leren (je build-commando, je conventies, je deploy-procedure), dan moet het dus als tekst in die request staan. Claude Code heeft drie plekken waar je zulke tekst neerzet. Ze verschillen vooral in wanneer ze laden:
| Mechanisme | Laadt | Kost context | Goed voor |
|---|---|---|---|
CLAUDE.md | bij elke sessiestart, volledig | in elke request | build-commando's, structuur, conventies die altijd gelden |
Rule met paths.claude/rules/*.md | pas als Claude een passend bestand leest of bewerkt | alleen als je in dat deel van de code werkt | regels voor één taal of map |
Skill.claude/skills/<naam>/SKILL.md | description bij start; inhoud pas bij gebruik | description in elke request, inhoud alleen na aanroep | procedures en naslag die je soms nodig hebt |
Het principe is progressive disclosure: hoe minder vaak iets nodig is, hoe later het moet laden. Alles in CLAUDE.md kost elke beurt tokens, en elke extra regel concurreert om de aandacht van het model.
Voor alle drie geldt: het zijn verzoeken, geen garanties. Het model leest de tekst en volgt hem meestal. Wat altijd moet gebeuren, hoort in een hook (C2).
Doorloop hieronder één sessie. Let erop wat bij de start laadt, wat er pas later bijkomt, en wat /compact overlaat.
Samengevat: CLAUDE.md is altijd aan, een rule met paths gaat aan in de juiste map, en een skill gaat aan als hij nodig is. Zet elke instructie zo laat mogelijk in de context, maar niet later dan nodig.
Verdieping laadvolgorde, rules, skill-routing, aanroepcontrole
CLAUDE.md: samenvoegen, niet overschrijven
CLAUDE.md-bestanden kunnen op vier niveaus staan: managed policy (bijv. /etc/claude-code/CLAUDE.md, door IT uitgerold), user (~/.claude/CLAUDE.md), project (./CLAUDE.md of ./.claude/CLAUDE.md, in git) en local (./CLAUDE.local.md, in .gitignore). Claude Code leest ze allemaal en plakt ze achter elkaar, van breed naar specifiek. Binnen de mappenboom gaat het van de root naar je werkmap, zodat de instructies het dichtst bij je werkmap als laatste komen. Spreken ze elkaar tegen, dan weegt het model ze. Er is geen regel die automatisch wint.
Both are loaded at the start of every conversation. Claude treats them as context, not enforced configuration.
Bestanden in de mappen boven je werkmap laden bij de start. Een CLAUDE.md in een submap laadt pas als Claude daar een bestand leest, schrijft of bewerkt. In een monorepo slaat claudeMdExcludes CLAUDE.md-bestanden van andere teams over. Alleen de managed CLAUDE.md kun je niet uitsluiten.
Met @pad/naar/bestand importeer je een ander bestand. Dat maakt een lang bestand overzichtelijker, maar niet goedkoper: het geïmporteerde bestand laadt gewoon mee. Een import buiten je project (bijv. uit je home-map) vraagt eenmalig om goedkeuring.
Rules: CLAUDE.md in stukjes
Markdown-bestanden in .claude/rules/ (ook in submappen) zijn modulaire instructies. Zonder frontmatter laden ze bij de start, net als .claude/CLAUDE.md. Met een paths-lijst worden ze conditioneel:
.claude/rules/api.md
---
paths:
- "src/api/**/*.ts"
- "tests/api/**/*.test.ts"
---
# API-regels
- Valideer elke input met zod.
Zo'n rule laadt zodra Claude met Read, Write of Edit een passend bestand aanraakt, of het bekijkt met een Bash-commando dat als lezen telt (cat of head op één bestand). paths is het enige veld dat Claude Code in een rule leest; andere velden worden genegeerd. Kan de YAML niet geparsed worden, dan laadt de rule alsof hij geen paths heeft, dus altijd. claude --debug toont de fout.
Skills: de description is een routing-key
Een skill is een map met een SKILL.md: YAML-frontmatter plus instructies. De mapnaam (of het veld name) wordt het commando: .claude/skills/deploy/ wordt /deploy. Er zijn twee manieren waarop een skill start: jij typt /naam, of het model vindt dat je vraag bij de description past en laadt hem zelf.
Claude matches your task against skill descriptions to decide which are relevant. If descriptions are vague or overlap, Claude may load the wrong skill or miss one that would help.
De description werkt dus als een routing-key. Zet de belangrijkste use case vooraan en noem de woorden die gebruikers echt zeggen. Probeer het verschil hieronder: dezelfde vier vragen, eerst met vage en daarna met scherpe descriptions.
Wie mag een skill starten?
| Frontmatter | Jij (/naam) | Het model | Description in context | Gebruik voor |
|---|---|---|---|---|
| (standaard) | ja | ja | ja | naslag en workflows die het model zelf mag kiezen |
disable-model-invocation: true | ja | nee | nee | bijeffecten en timing: /deploy, /commit, berichten versturen |
user-invocable: false | nee | ja | ja | achtergrondkennis die geen zinnig commando is |
Een skill zonder bijeffecten mag het model gerust zelf kiezen. Voor /deploy wil je dat niet: "You don't want Claude deciding to deploy because your code looks ready." Zet je disable-model-invocation: true, dan bespaar je bovendien context, want de description staat dan niet meer in de listing.
Waar leven skills?
Persoonlijk in ~/.claude/skills/ (al je projecten), per project in .claude/skills/ (in git, voor je team), via managed settings voor de hele organisatie, of in een plugin (C5) als /plugin-naam:skill. Bij dezelfde naam gaat enterprise vóór personal en personal vóór project. Plugin-skills botsen nooit, want die hebben een namespace. Losse bestanden in .claude/commands/ werken nog, maar zijn het oudere formaat: een skill kan ook ondersteunende bestanden hebben.
Onder de motorkap limieten, compaction, argumenten, dynamische context
De getallen
| Wat | Grens | Wat er gebeurt |
|---|---|---|
| CLAUDE.md (advies) | < 200 regels per bestand | langer kost meer context en verlaagt de naleving; /doctor stelt inkortingen voor |
| CLAUDE.md in submap, rules die op aanvraag laden | 40.000 tekens (200K-venster) | Claude krijgt alleen het begin, met een notitie om de rest met Read te lezen |
description + when_to_use | 1.536 tekens | afgekapt in de skill-listing |
| Skill-listing totaal | 1% van het contextvenster | bij overloop vallen descriptions weg, te beginnen bij de minst gebruikte skills |
| Skills na compaction | 5.000 tokens per skill, 25.000 samen | de recentste aanroep van elke skill komt terug, vanaf de nieuwste; oudere skills kunnen wegvallen |
Wat overleeft /compact?
De CLAUDE.md in de projectroot leest Claude Code na compaction opnieuw van schijf. Een CLAUDE.md in een submap en rules met paths komen pas terug als Claude daar weer een bestand aanraakt. Een instructie die je alleen in het gesprek gaf, is na compaction weg. Daarom de vuistregel: herhaal je een correctie in de chat, zet hem dan in CLAUDE.md.
De levensloop van een skill
Bij aanroep komt de gerenderde SKILL.md als één bericht in het gesprek, en daar blijft hij. Claude Code leest het bestand daarna niet opnieuw. Schrijf instructies die de hele taak moeten gelden dus als staande regels ("draai na elke edit de tests"), niet als eenmalige stap. Een allowed-tools-toestemming geldt daarentegen alleen voor de beurt waarin de skill werd aangeroepen.
Argumenten en dynamische context
$ARGUMENTSwordt de volledige argumentstring (/deploy staginggeeftstaging);$0,$1, … zijn losse argumenten, met shell-achtige quoting. Gebruikt de skill geen placeholder, dan plakt Claude Code de argumenten erachter alsARGUMENTS: ….!`git diff --staged`in de skilltekst draait vóórdat Claude de skill ziet. De output vervangt de placeholder, zodat het model echte data krijgt in plaats van een opdracht om die op te halen.${CLAUDE_SKILL_DIR}verwijst naar de map van de skill, voor meegeleverde scripts en referentiebestanden. Verwijs vanuitSKILL.mdnaar die bestanden, zodat Claude weet wanneer hij ze moet lezen: "Large reference docs, API specifications, or example collections don't need to load into context every time the skill runs."context: forkdraait de skill in een eigen subagent (C4), zodat zijn werk je hoofdgesprek niet vult.
Debuggen
- Welke instructiebestanden zijn er geladen?
/memorytoont de locaties van je CLAUDE.md-bestanden en opent ze in je editor;/contexttoont wat ze kosten. Wil je exact weten wat wanneer laadt, ook voor bestanden die later laden: eenInstructionsLoaded-hook krijgt per bestand het pad en de reden (session_start,path_glob_match,nested_traversal,include,compact). - Skill triggert niet: staan de woorden van je vraag in de description? Is de frontmatter geldige YAML? Bij kapotte YAML werkt
/naamnog wel, maar kan het model niet matchen. Gebruikclaude --debugofclaude plugin validate .claude/skills. - Skill triggert te vaak: maak de description specifieker, of zet
disable-model-invocation: true.
Unlike CLAUDE.md content, a skill's body loads only when it's used, so long reference material costs almost nothing until you need it.
Uitgewerkt voorbeeld: een CLAUDE.md opsplitsen
Een CLAUDE.md van 60 regels bevat drie soorten instructies door elkaar: wat altijd geldt, wat alleen voor src/api/ geldt, en een deploy-procedure. Na het opsplitsen in drie bestanden laadt elk deel op het juiste moment.
CLAUDE.md (na het opsplitsen)
# Webshop
REST-API in src/api, React-frontend in src/web.
## Build & test
- pnpm install (nooit npm of yarn)
- Tests: pnpm test. Draai ze vóór elke commit.
## Conventies
- TypeScript strict; geen `any`. Bestandsnamen in kebab-case.
- API-regels: zie .claude/rules/api.md. Deployen: /deploy.
- Altijd nodig, kort en concreet. "Gebruik pnpm" werkt beter dan "gebruik de juiste package manager": hoe specifieker, hoe consistenter het model het volgt.
- Een wegwijzer, geen inhoud. Eén regel vertelt waar de rest staat. De inhoud zelf laadt pas als hij nodig is.
.claude/rules/api.md
---
paths:
- "src/api/**/*.ts"
---
# API-regels
- Valideer elke input met zod, vóór er iets anders gebeurt.
- Fouten als { "error": { "code", "message" } }; nooit een stacktrace.
- 400 validatie · 404 onbekend · 409 conflict.
- Logger uit src/api/log.ts, nooit console.log.
- paths: deze rule laadt pas als Claude een TypeScript-bestand onder
src/api/leest of bewerkt. Werk je aan de frontend, dan kost hij niets. - Regels die het model kan toepassen terwijl het code schrijft. Moet dit altijd kloppen? Dan zet je er ook een lint-regel of een PostToolUse-hook op die het controleert (C2).
.claude/skills/deploy/SKILL.md
---
description: Rolt de webshop uit naar staging of productie.
disable-model-invocation: true
allowed-tools: Bash(pnpm *) Bash(./scripts/deploy.sh *)
---
Rol uit naar $ARGUMENTS:
1. pnpm test; stop bij een fout en meld welke test faalde.
2. pnpm build
3. ./scripts/deploy.sh $ARGUMENTS
4. Controleer de health-check en meld de versie.
Bij productie: vraag eerst expliciet om bevestiging.
- description: voor
/-menu en mensen. Omdat het model deze skill toch niet zelf start, hoeft hij geen routing-woorden te bevatten. - disable-model-invocation: alleen jij start een deploy. De description staat daardoor ook niet in de listing, dus de skill kost geen context tot je hem gebruikt.
- allowed-tools: tijdens de beurt waarin je
/deployaanroept, draaien deze commando's zonder permissieprompt. Bij je volgende bericht vervalt dat. - $ARGUMENTS:
/deploy stagingvult hierstagingin.
Imports help you organize a long file but don't reduce its context cost, because imported files load together with the CLAUDE.md that imports them.
Splits een te lange CLAUDE.md en meet wanneer wat laadt
Starter: oefenrepo/c1-sturen/. Een webshop met een CLAUDE.md van 40 regels die drie soorten instructies mengt. In .claude/settings.json staat al een InstructionsLoaded-hook die elke geladen instructiefile logt naar .claude/laadlog.txt. Je hebt Claude Code en jq nodig.
Opdracht
- Kopieer de map naar een eigen plek,
git init, startclaudeen sluit meteen weer af. Bekijk.claude/laadlog.txt. - Verplaats de API-regels naar
.claude/rules/api.mdmetpaths: ["src/api/**/*.ts"], de frontend-regels naar.claude/rules/web.mdmetpaths: ["src/web/**/*.tsx"], en de deploy-procedure naar.claude/skills/deploy/SKILL.mdmetdisable-model-invocation: true. Laat in CLAUDE.md alleen staan wat altijd geldt. - Leeg het log, start
claudeen vraag: "Voeg zod-validatie toe aan createUser in src/api/users.ts". Kijk na afloop in het log. - Vraag daarna: "Wil je deployen naar staging?" Doet Claude het? Typ dan zelf
/deploy staging. - Maak het kapot. Zet een tikfout in de YAML van
api.md(bijv. een ontbrekende"), leeg het log en start opnieuw. Wanneer laadt de rule nu?
Verwacht resultaat
Stap 1: het log bevat één regel session_start …/CLAUDE.md (plus eventueel je eigen ~/.claude/CLAUDE.md).
Stap 3: bij de start alleen CLAUDE.md. Zodra Claude users.ts leest, komt er een regel path_glob_match …/.claude/rules/api.md bij. web.md verschijnt niet. Het resultaat: validatie met zod en een foutobject volgens de regels, ook al stond dat niet meer in CLAUDE.md.
Stap 4: Claude start de deploy niet zelf. Hij legt uit dat je /deploy kunt draaien, of doet hooguit losse stappen na overleg. /deploy staging draait de stappen; pnpm en deploy.sh vragen geen toestemming dankzij allowed-tools.
Stap 5: met kapotte YAML laadt api.md als rule zonder paths: het log toont hem al bij session_start. Dat is geen foutmelding, maar stil gedrag. claude --debug laat de parse-fout zien.
Als het niet werkt, kijk naar …
- Log blijft leeg.
jqontbreekt, of de map is geen project (git initvergeten). Controleer de hook met/hooks. - Rule laadt niet bij
users.ts. Het pad inpathsis relatief aan de map met.claude/.src/api/**/*.tsmatcht,/src/api/*.tsmatcht alleen direct in de root. Eengrepover de map telt niet als lezen: vraag Claude het bestand te openen. /deploybestaat niet. De map moet.claude/skills/deploy/SKILL.mdheten (hoofdletters!). Nieuwe skillmappen worden meestal direct opgepikt; anders even herstarten.- Claude start de deploy toch zelf. Staat
disable-model-invocation: trueecht in de frontmatter, tussen de----regels? Bij kapotte YAML valt de frontmatter weg.