AI-agent maken in Claude Code: stap voor stap

Redactie AI voor Bedrijven | Documentatie nagekeken op 19 augustus 2026 | Laatst bijgewerkt: 19 augustus 2026

Een AI-agent in Claude Code is geen software die je laat bouwen, maar een tekstbestand van een paar regels. Wie dat weet, kijkt anders naar de vraag “kunnen we hier iets mee automatiseren”.

Snel antwoord: een ai agent maken in Claude Code betekent dat je een Markdown-bestand aanmaakt in .claude/agents/ of ~/.claude/agents/. Bovenin komt een kop met instellingen (YAML-frontmatter), daaronder de instructie in gewone tekst. Alleen name en description zijn verplicht. Je kan het bestand zelf schrijven of het gewoon aan Claude vragen. Claude schakelt er daarna zelf naar door als een taak past.

Samenvatting in het kort

• Een subagent is een gespecialiseerde AI-assistent: één Markdown-bestand met een kop (instellingen) en een systeemprompt (de vaste instructie).
• Verplicht zijn alleen name en description. Alle andere velden zijn optioneel.
• Zet agenten die je team moet delen in .claude/agents/ in het project, zodat ze meegaan in versiebeheer.
• Claude kiest zelf een agent op basis van de description. Met een @-vermelding forceer je welke agent draait.
• Beperk het gereedschap met tools of disallowedTools. Dat is geen detail, dat is een veiligheidsmaatregel.
• Een subagent begint met een verse context en kent je gespreksgeschiedenis niet. Alles wat hij moet weten, geef je mee in de opdracht.
• Claude Code is een terminalgereedschap. Zonder ontwikkelaar in de buurt is dit geen logische startplek.
• Voor losse eenmalige klussen is een gewone prompt sneller. Voor vakkennis is een skill vaak de betere keuze.

Wat is een AI-agent, en wat is een subagent in Claude Code?

Een AI-agent is een taalmodel dat een doel krijgt, zelf stappen bepaalt en gereedschap gebruikt (bestanden lezen, zoeken, commando’s uitvoeren) tot de taak klaar is. Het verschil met een chatprompt: je beschrijft het doel, niet elke tussenstap.

In Claude Code heet dat een subagent: een gespecialiseerde assistent die je vastlegt in een Markdown-bestand met YAML-frontmatter (een kop met instellingen) gevolgd door een systeemprompt in gewone tekst. Volgens de documentatie van Claude Code werkt zo’n subagent in een eigen, losse context naast je hoofdgesprek.

In bedrijfstaal: een agent is een vaste werkwijze die je één keer vastlegt, in plaats van elke keer opnieuw uit te leggen. Zoals een checklist die je aan een nieuwe collega geeft, alleen leest hier het model hem.

Vuistregel uit de documentatie: één agent, één taak. Een agent die “alles” doet, doet niets goed.

Kan je een AI-agent maken zonder programmeerkennis?

Het bestand schrijven kan zonder programmeren. Claude Code opstarten en beheren niet helemaal.

Claude Code werkt in de terminal (de opdrachtregel van je computer). Wie daar nooit komt, loopt eerder vast op de installatie dan op de agent zelf. Eerlijk gezegd:

• Wel geschikt voor jou als je zelf al met Claude Code werkt, of een ontwikkelaar in dienst hebt en wil begrijpen wat je vraagt en waarom.
• Niet geschikt als je een chatbot voor je klanten zoekt. Dat is een ander soort product en Claude Code is er niet voor bedoeld.

De snelste route zonder technische kennis is het aan Claude zelf vragen, bijvoorbeeld: “Maak een persoonlijke code-improver subagent in ~/.claude/agents/ die bestanden nakijkt en verbeteringen voorstelt.” Claude schrijft dan het bestand met de juiste structuur. Daarna lees je het na en pas je de tekst aan.

Wat heb je nodig voordat je begint?

Weinig. Er zijn geen bibliotheken, frameworks of API-koppelingen nodig om een agent te maken.

Op de checklist staan:

1. Claude Code, geïnstalleerd en ingelogd.
2. Een projectmap, bij voorkeur met git, zodat agenten in versiebeheer meegaan.
3. Een teksteditor voor .md-bestanden.
4. Optioneel: MCP-servers als je agent externe systemen moet raken (zie verder).

Waar staat het bestand, en wat hoort er in de kop?

Agenten worden op vijf plekken gevonden, met deze voorrang van hoog naar laag:

De documentatie beveelt .claude/agents/ aan voor projectagenten die je met je team deelt. Op Windows verwijst ~/.claude naar %USERPROFILE%\.claude.

Ter oriëntatie: de map .claude/ in een project bevat settings.json (gedeeld, in git), settings.local.json (persoonlijk, buiten git), agents/, skills/, commands/ en CLAUDE.md. De map ~/.claude/ bij de gebruiker heeft dezelfde onderdelen, maar dan voor al je projecten.

Welke velden kan je in de kop zetten?

Alleen name en description zijn verplicht.

Hoe ziet een compleet voorbeeldbestand eruit?

Dit is een volledige, werkende agent. Meer is niet nodig.

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide specific, actionable feedback on quality, security, and best practices.

Wat hier gebeurt: de agent heet code-reviewer, hij mag alleen lezen en zoeken (Read, Glob, Grep), hij gebruikt Sonnet, en de tekst onder de streepjes is zijn vaste opdracht. Omdat Write en Edit ontbreken, kan hij niets aanpassen. Dat is precies de bedoeling bij een nakijker.

Sla dit op als .claude/agents/code-reviewer.md en je bent klaar. De mappen ~/.claude/agents/ en .claude/agents/ worden in de gaten gehouden: wijzigingen worden binnen enkele seconden opgepikt, zonder herstarten. Alleen bij het aanmaken van een nieuwe agents-map geldt dat niet.

Hoe beslist Claude welke agent hij inzet?

Claude leest de description van elke agent en schakelt door als een taak daarbij past. De description is dus geen beschrijving voor mensen, maar de routeringsregel.

Je kan het ook zelf bepalen, op drie manieren:

• In gewone taal de naam noemen: “Use the code-reviewer subagent to look at my changes.”
• Met een @-vermelding: dat garandeert dat die agent draait.
• Een hele sessie als die agent starten: claude --agent code-reviewer, of {"agent": "code-reviewer"} in .claude/settings.json.

Wil je dat Claude vaker zelf doorschakelt, zet dan “use proactively” in de description. Veelgemaakte fout: twee agenten met bijna dezelfde description. Dan wordt de keuze een gok. Schrijf liever expliciet wanneer hij moet inspringen en wanneer niet.

Waarom is gereedschap beperken een veiligheidskwestie?

Omdat een agent standaard alle beschikbare tools krijgt. Een agent die alleen hoeft te lezen, kan dan ook schrijven, verwijderen en commando’s uitvoeren. De documentatie beveelt daarom aan zo min mogelijk gereedschap te geven.

De vier patronen die je nodig hebt:

tools: Read, Grep, Glob, Bash
disallowedTools: Write, Edit
disallowedTools: mcp__github
tools: Agent(worker, researcher), Read, Bash

De laatste regel beperkt welke subagenten deze agent zelf mag starten. Dat is relevant zodra agenten elkaar aanroepen.

Denk hierbij ook aan promptinjectie: als je agent externe tekst leest (een issue, een webpagina, een klantmail), kan daarin een instructie verstopt zitten. Een agent zonder Write en zonder Bash kan die instructie simpelweg niet uitvoeren. Beveiliging was in 2026 een terugkerend thema in de releases van Claude Code, met extra bescherming rond goedkeuringen, worktrees en riskante shell-omleidingen. Minder gereedschap blijft de goedkoopste maatregel.

Wat kunnen agenten in Claude Code eigenlijk doen, en kunnen ze koppelen aan API’s en databases?

Ja, via MCP-servers. MCP (Model Context Protocol) is een standaard koppelvlak waarmee Claude Code praat met externe systemen zoals een issue-tracker, een database of een interne API. Met mcpServers bepaal je welke een agent mag gebruiken, met disallowedTools: mcp__github haal je een hele server weg.

Realistische taken die binnen bereik liggen:

• Codewijzigingen nakijken op kwaliteit en veiligheid voordat ze naar review gaan.
• Een codebase verkennen en samenvatten voordat er iets aangepast wordt.
• Terugkerende opruimklussen uitvoeren volgens een vaste werkwijze.
• Gegevens ophalen uit een gekoppeld systeem en samenvatten in een rapport.

Wat dit niet is: een klantgerichte chatbot of een dienst die 24/7 aanvragen verwerkt. Wil je dat, dan bouw je iets op de API van Anthropic, niet in Claude Code. Voor wie liever in een editor werkt dan in de terminal: Cursor werkt met een vergelijkbare aanpak van instructiebestanden.

Hoe test en debug je je AI-agent in Claude Code?

Test in de voorgrond met een @-vermelding, met één concrete opdracht, en kijk of hij het juiste gereedschap gebruikt. Pas daarna laat je Claude zelf routeren.

Een werkbare aanpak:

1. Roep de agent geforceerd aan met een @-vermelding. Werkt de inhoud?
2. Geef daarna een taak in gewone taal, zonder de naam te noemen. Schakelt Claude door? Zo niet, dan is de description te vaag.
3. Zet maxTurns als hij te lang doorgaat.
4. Gebruik hooks (PreToolUse, PostToolUse, Stop) als je wil zien of vastleggen wat er gebeurt rond gereedschapsgebruik.
5. Pas het bestand aan en probeer opnieuw. Wijzigingen worden binnen enkele seconden opgepikt.

Let op dit verschil: subagenten draaien standaard op de achtergrond met een kleiner setje gereedschap, op de voorgrond hebben ze het volledige setje. Een agent die op de voorgrond werkt maar op de achtergrond faalt, mist waarschijnlijk gereedschap.

Wat zijn de grenzen, valkuilen en gedragsregels?

Dit is de belangrijkste sectie. De meeste teleurstellingen komen niet van fouten, maar van verkeerde verwachtingen.

Verse context. Een subagent begint leeg. In zijn context zit alleen de opdracht, zijn systeemprompt, de CLAUDE.md-bestanden, de git-status en vooraf geladen skills. Niet je gespreksgeschiedenis. Alles wat hij moet weten, geef je dus mee in de opdracht.

Diepte en aantal. Subagenten kunnen standaard tot 3 lagen diep genest worden, aanpasbaar met CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH. Er kunnen standaard maximaal 20 subagenten tegelijk draaien, aanpasbaar met CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS.

Ingebouwde agenten. Explore, Plan en general-purpose zijn er altijd, tenzij ze geweigerd worden. Belangrijk detail: Explore en Plan slaan CLAUDE.md en de git-status over, voor snelheid en kosten. Verwacht dus niet dat ze jouw projectafspraken kennen.

Mappen worden gevolgd. Aanpassingen in ~/.claude/agents/ en .claude/agents/ worden binnen enkele seconden opgepikt. Alleen het aanmaken van een nieuwe agents-map vraagt om een herstart.

De vijf fouten die je zonder nadenken maakt:

• Een description van drie woorden, waardoor Claude nooit doorschakelt.
• Het gereedschap niet beperken, ook niet bij een agent die alleen leest.
• Aannemen dat de agent weet wat je tien minuten eerder in het gesprek zei.
• Een teamagent in ~/.claude/agents/ zetten, waardoor je collega’s hem niet hebben.
• Een name met hoofdletters of een dubbele punt. Alleen kleine letters en koppeltekens.

Wat kost het om een AI-agent met Claude te bouwen?

Het bestand maken kost niets extra: het is een Markdown-bestand. Het verbruik zit in het gebruik, en dat stuur je met de instellingen. Tarieven noemen we hier niet, want die staan bij Anthropic en veranderen.

Vier knoppen die het verbruik bepalen:

• model: haiku voor eenvoudig werk, opus alleen waar het echt nodig is.
• effort: van low tot max, hoeveel denkwerk hij mag doen.
• maxTurns: harde stop, zodat een agent niet blijft rondlopen.
• Gelijktijdigheid: 20 agenten tegelijk mag, maar dat telt uiteraard op.

Hoe verschilt dit van andere AI-frameworks, en hoe zet je het in productie?

Het grote verschil: bij Claude Code is een agent configuratie, geen code. Er is geen orkestratielaag om te programmeren, geen bibliotheek om te leren. Dat maakt de instapdrempel laag, maar geeft je ook minder controle dan een zelfgebouwd systeem op de API.

“Beter” hangt vooral af van waar je team werkt. Zit je in een editor in plaats van in de terminal, dan biedt Cursor een vergelijkbare aanpak met instructiebestanden. Kies op basis van je eigen werkwijze, niet op basis van een ranglijst.

“In productie” betekent hier: vast onderdeel van de werkwijze van je team, niet een draaiende webdienst. Concreet:

1. Zet projectagenten in .claude/agents/ en commit ze.
2. Leg de standaardagent vast met {"agent": "..."} in .claude/settings.json.
3. Laat IT organisatiebrede agenten uitrollen via managed settings, die hebben de hoogste voorrang.
4. Gebruik isolation: worktree voor werk dat je hoofdmap niet mag raken, en background: true voor langlopende taken.

Wanneer gebruik je beter een skill of een gewone prompt?

Kies een agent als je een terugkerende werkwijze wil vastleggen die een eigen context en eigen gereedschapsgrenzen nodig heeft. Kies een skill als je vooral vakkennis of een werkinstructie wil meegeven die de hoofdsessie zelf gebruikt. Kies een gewone prompt voor eenmalig werk.

Ze sluiten elkaar niet uit: met het veld skills laad je vakkennis vooraf in een agent. Dat is de aanbevolen combinatie in de documentatie.

<!DOCTYPE html>
<html lang="nl">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<style>
.cg-kiezer{font-family:-apple-system,Segoe UI,Roboto,Arial,sans-serif;max-width:640px;margin:0 auto;padding:18px;border:1px solid #d8dee6;border-radius:10px;background:#fbfcfd;color:#1c2530}
.cg-kiezer h3{margin:0 0 4px;font-size:1.1rem}
.cg-kiezer p.cg-sub{margin:0 0 14px;font-size:.86rem;color:#5a6875}
.cg-kiezer fieldset{border:0;padding:0;margin:0 0 14px}
.cg-kiezer legend{font-weight:600;font-size:.92rem;margin-bottom:6px}
.cg-kiezer label{display:block;font-size:.9rem;padding:6px 8px;border:1px solid #e2e8ee;border-radius:6px;margin-bottom:5px;cursor:pointer;background:#fff}
.cg-kiezer button{background:#1c4f8a;color:#fff;border:0;border-radius:6px;padding:10px 16px;font-size:.92rem;cursor:pointer}
.cg-uit{margin-top:14px;padding:12px;border-radius:8px;background:#eef4fb;border-left:4px solid #1c4f8a;font-size:.92rem;display:none}
.cg-uit strong{display:block;margin-bottom:4px}
</style>
</head>
<body>
<div class="cg-kiezer">
<h3>Agent, skill of gewone prompt?</h3>
<p class="cg-sub">Drie vragen, gebaseerd op de aanbevelingen in de documentatie van Claude Code.</p>
<fieldset>
<legend>1. Hoe vaak komt deze taak terug?</legend>
<label><input type="radio" name="cgq1" value="1" checked> Eenmalig of zelden</label>
<label><input type="radio" name="cgq1" value="2"> Regelmatig, met vaste stappen</label>
</fieldset>
<fieldset>
<legend>2. Moet het gereedschap beperkt worden?</legend>
<label><input type="radio" name="cgq2" value="1" checked> Nee, gewoon meedenken</label>
<label><input type="radio" name="cgq2" value="2"> Ja, alleen lezen of geen shell</label>
</fieldset>
<fieldset>
<legend>3. Wat lever je vooral aan?</legend>
<label><input type="radio" name="cgq3" value="1" checked> Kennis of huisregels</label>
<label><input type="radio" name="cgq3" value="2"> Een werkwijze met eigen context</label>
</fieldset>
<button id="cgBtn" type="button">Toon advies</button>
<div class="cg-uit" id="cgUit"></div>
</div>
<script>
document.getElementById('cgBtn').addEventListener('click',function(){
var v=function(n){return parseInt(document.querySelector('input[name="'+n+'"]:checked').value,10);};
var s=v('cgq1')+v('cgq2')+v('cgq3');
var t,d;
if(s<=3){t='Gewone prompt';d='Eenmalig werk zonder vaste grenzen. Formuleer je vraag goed en klaar; een bestand aanmaken levert hier niets op.';}
else if(v('cgq3')===1&&v('cgq2')===1){t='Skill';d='Je levert vooral kennis of huisregels aan. Zet dit in een skill; met het veld skills laad je die later alsnog vooraf in een agent.';}
else{t='Subagent';d='Terugkerende werkwijze met eigen context of beperkt gereedschap. Maak een bestand in .claude/agents/, met minimaal name en description, en beperk tools.';}
var u=document.getElementById('cgUit');
u.innerHTML='<strong>Advies: '+t+'</strong>'+d;
u.style.display='block';
});
</script>
</body>
</html>

Conclusie

Een ai agent maken in Claude Code is minder werk dan de term “agent” suggereert: een Markdown-bestand, twee verplichte velden, een duidelijke instructie. De winst zit niet in het bestand, maar in de discipline erachter: één agent per taak, een description die precies zegt wanneer hij moet inspringen, en zo weinig gereedschap als mogelijk.

Wat je vandaag kan doen:

1. Kies één taak die bij jullie elke week op dezelfde manier terugkomt.
2. Laat Claude een eerste versie van het bestand schrijven in .claude/agents/.
3. Haal het gereedschap eruit dat de taak niet nodig heeft, met tools of disallowedTools.
4. Test met een @-vermelding, daarna zonder, om de routering te controleren.
5. Commit het bestand zodat je team dezelfde werkwijze gebruikt.

Controleer de details altijd in de officiële documentatie op code.claude.com/docs, want Claude Code kreeg in 2026 in hoog tempo nieuwe instellingen. De opzet met een Markdown-bestand en een kop met instellingen is intussen stabiel.

Bronnen

Claude Code, documentatie over subagenten - https://code.claude.com/docs/en/sub-agents Claude Code, documentatie over instellingen - https://code.claude.com/docs/en/settings Claude Code, documentatie over toestemmingen - https://code.claude.com/docs/en/permissions