Naar de inhoud
NLEN
Illustratie: Conventies voor het delen en documenteren van prompts

Conventies voor het delen en documenteren van prompts

Door Ivo Donker — samengesteld met AI-ondersteuning · Laatst bijgewerkt: 7 augustus 2026

Wanneer softwareteams taalmodellen integreren in productieapplicaties, ontstaat al snel de noodzaak om natuurlijke-taalinstructies over te dragen tussen ontwikkelaars, data-engineers en domeinexperts. In veel organisaties voltrekt dit proces zich ad hoc: ontwikkelaars kopiëren tekstblokken via chatkanalen, bewaren varianten in persoonlijke notitie-apps of embedden losse instructies direct in applicatiecode. Dit leidt onherroepelijk tot onherleidbare regressies, onduidelijkheid over het beoogde taalmodel en verlies van essentiële randcontext.

Prompts zijn in moderne applicatie-architecturen volwaardige broncode. Het uitwisselen en vastleggen van instructies vraagt daarom om exact dezelfde technische discipline als softwarecode, API-specificaties en README-documentatie. Het formeel behandelen van instructies vereist dat het team gestandaardiseerde afspraken maakt over de volledige levenscyclus van deze artefacten. Lees hoe je prompts als code behandelen moet om overzichtelijkheid en reproduceerbaarheid van wijzigingen in het ontwikkelproces te borgen.

Bij het opzetten van een professionele werkwijze is het essentieel om drie concepten strikt van elkaar te scheiden. Ten eerste is er het mechanisme voor versiebeheer, dat zorgt voor het opslaan en traceren van tekstuele wijzigingen in een repository. Ten tweede is er de prompt-bibliotheek, die fungeert als de georganiseerde verzameling waarin de instructies leven. Raadpleeg het overzicht van de prompt-bibliotheek waarin gedeelde prompts leven om te zien hoe gestructureerde verzamelingen in productieomgevingen worden ingedeeld. Dit artikel behandelt de derde pijler: de organisatorische en technische conventies rondom het documenteren en overdragen van prompts. Zonder eenduidige afspraken raakt zelfs de best gestructureerde repository vervuild met onbruikbare artefacten.

Teamafspraken vooraf: Naamgeving, Metadata en Frontmatter

Voordat een team start met het delen van instructies, moeten er eenduidige afspraken worden vastgelegd over de identificatie en metadata van promptbestanden. Het ontbreken van conventies leidt tot bestandsnamen zoals prompt_v2_final.txt, waarin geen enkele informatie besloten ligt over het doel, het verwachte model of de benodigde invoervariabelen.

Naamgevingsconventies dienen te berusten op semantische identifiers die de functie van de prompt beschrijven, onafhankelijk van de auteur of de specifieke applicatielaag. Gebruik een hiërarchische map- of bestandsstructuur op basis van kebab-case notatie volgens het patroon domein/subdomein/actie.prompt.md. (Aanname: teams die een strikte hiërarchische naamgevingsconventie hanteren reduceren de zoektijd naar specifieke instructies binnen het team met 50%).

Naast de bestandsnaam moet elk gedeeld promptbestand voorzien zijn van een gestandaardiseerd headerblok. YAML frontmatter biedt hiervoor de meest geschikte structuur, omdat dit formaat zowel door menselijke ontwikkelaars als door geautomatiseerde CI/CD-pipelines en linter-tools uitgelezen kan worden. Het team legt vooraf vast welke velden binnen de organisatie verplicht zijn en welke optioneel blijven.

De verplichte metadatavelden in de frontmatter omvatten minimaal:

Het insluiten van deze velden voorkomt dat configuratieparameters verborgen blijven in applicatiecode of dat een collega de prompt uitvoert met onjuiste modelinstellingen. Bekijk de richtlijnen voor prompt-modulariteit en herbruikbare componenten om te leren hoe je complexe instructies opsplitst in onderhoudbare bouwstenen die elk een eigen frontmatter dragen.

Het documentatieblok: Zelfstandig uitvoerbare instructies

Een belangrijk criterium voor een goed gedocumenteerde prompt is dat een collega de instructie direct en doeltreffend kan uitvoeren in een testomgeving of playground, zonder dat daartoe mondelinge toelichting, toegang tot applicatiecode of aanvullende context vereist is. Dit wordt bereikt door de prompt in te bedden in een zelfstandig documentatieblok.

Het documentatieblok moet de volgende vaste onderdelen bevatten:

  1. Functioneel Doel: Een duidelijke omschrijving van de taak die het taalmodel moet uitvoeren en het beoogde bedrijfsproces.
  2. Invoer- en Uitvoerspecificaties: Een expliciete declaratie van alle runtime-variabelen met hun datatypes, gecombineerd met een concreet JSON-schema of een TypeScript-interface voor de verwachte uitvoer.
  3. Beperkingen en Randvoorwaarden: Bekende randgevallen (edge cases), onderwerpen die de prompt expliciet moet negeren en instructies om hallucinaties of ongewenste opmaak te voorkomen.
  4. Model- en Runtime-configuratie: De exacte parameters waarmee de prompt is gevalideerd. Dit omvat naast temperatuur en top_p ook eventuele stop-sequences en de systeemrol-instelling.
  5. Tokenbudget: Een indicatie van het verwachte aantal tokens voor zowel de instructie als de respons. Gebruik de prompt-tokenteller om het tokenbudget te schatten voordat een nieuwe promptversie wordt vrijgegeven aan het ontwikkelteam.

Onderstaand sjabloon toont een gestandaardiseerd en direct kopieerbaar artefact voor een promptdocumentatieblok inclusief YAML frontmatter:

---
id: "customer-support/ticket-classifier"
title: "Klantenservice Ticket Classificatie en Entiteit-extractie"
version: "1.2.0"
owner: "team-support-engineering"
target_model: "claude-3-5-sonnet-20241022"
parameters:
  temperature: 0.0
  max_tokens: 500
  top_p: 1.0
inputs:
  - name: "ticket_body"
    type: "string"
    description: "De volledige tekst van het ingediende klantticket."
  - name: "customer_tier"
    type: "string"
    description: "Het serviceniveau van de klant (bijv. 'free', 'pro', 'enterprise')."
outputs:
  type: "json_object"
  schema:
    category: "string"
    urgency: "string (low|medium|high|critical)"
    sentiment: "string (positive|neutral|negative)"
    action_required: "boolean"
changelog:
  - version: "1.2.0"
    date: "2026-08-01"
    author: "Ivo Donker"
    change: "Toevoeging van customer_tier variabele voor nauwkeurigere bepaling van urgentie."
---

# Functioneel Doel
Deze prompt analyseert inkomende klantenservicetickets, bepaalt de categorie en urgentie, en extraheert gestructureerde metadata voor automatische routering in het helpdesksysteem.

# Invoervariabelen
- `ticket_body`: Platte tekst van de klant.
- `customer_tier`: 'free', 'pro' of 'enterprise'.

# Verwachte Uitvoer
De uitvoer MOET een valide JSON-object zijn zonder aanvullende tekst of Markdown-fences buiten de JSON-structuur.

Voorbeeld van geldige uitvoer:
{
  "category": "billing",
  "urgency": "high",
  "sentiment": "negative",
  "action_required": true
}

# Beperkingen en Randvoorwaarden
- Geen aannames doen over ontbrekende factuurnummers.
- Indien de tekst in een andere taal dan het Nederlands is gesteld, toch analyseren maar de categorie 'multilingual-routing' toekennen.
- Geen persoonsgegevens overnemen in de output-velden.

# Prompt Instructie

[SYSTEM]
Je bent een gespecialiseerde verwerker van klantenservicetickets. Je analyseert de onderstaande tekst en retourneert uitsluitend een JSON-object dat voldoet aan de opgegeven specificatie.

[USER]
Klantniveau: {{customer_tier}}
Ticketinhoud:
{{ticket_body}}

Hygiëne en Veiligheid: Wat je NÍET meegeeft bij het delen

Bij het uitwisselen van prompts binnen teams of het publiceren van sjablonen ontstaat een reëel risico op het lekken van vertrouwelijke informatie. Omdat instructies in natuurlijke taal geschreven zijn, vervaagt de grens tussen applicatielogica en gegevens sneller dan bij traditionele code. Een strikte hygiëne is noodzakelijk om te voorkomen dat bedrijfskritische informatie onbedoeld wordt verspreid.

De volgende gegevens mogen onder geen beding voorkomen in gedeelde promptbestanden:

Wanneer instructies gedeeld worden binnen een internationaal samengesteld team, moeten er bovendien duidelijke afspraken zijn over het taalgebruik in de instructies en voorbeelden. Raadpleeg het artikel over meertalige prompts voor specifieke conventies bij het documenteren van instructies in internationale softwareteams om ruis en interpretatiefouten door taalmodellen te voorkomen.

Het verschil tussen intern delen en publiek publiceren

De eisen die aan een documentatieblok worden gesteld, variëren afhankelijk van het bereik van de distributie. Er bestaat een fundamenteel verschil tussen het delen van een prompt binnen een besloten ontwikkelteam en het publiek publiceren van een instructie als open-source artefact of onderdeel van een externe API-documentatie.

Bij interne distributie binnen een organisatie mag de documentatie leunen op gedeelde domeinkennis en interne standaarden. Interne vaktermen, verwijzingen naar specifieke microservices en kaders van de eigen organisatie hoeven niet bij elke individuele prompt van de grond af aan uitgelegd te worden, mits de overkoepelende context geborgd is in het repository. De focus ligt hier op verwerkingssnelheid, directe integratie in de software-architectuur en onderhoudbaarheid.

Bij publieke publicatie vervalt elke veronderstelde context. Een openbaar gemaakte prompt moet aan aanvullende kwaliteits- en veiligheidseisen voldoen:

Om deze uitwisseling binnen teams gestroomlijnd te laten verlopen, is een passend instrumentarium nodig. Het overzicht van prompt-management-tools vergelijkt geschikte platforms en repository-integraties die teams ondersteunen bij het beheren van gedeelde instructies.

Onderhoud, Levenscyclus en Changelogs

Het documenteren en opleveren van een prompt is geen eenmalige handeling. Taalmodellen veranderen hun gedrag bij updates van de provider, en applicatie-eisen evolueren doorlopend. Een gedeelde prompt die niet actief wordt onderhouden, transformeert snel in technische schuld. (Aanname: prompts die langer dan zes maanden niet zijn herbeoordeeld tegen de nieuwste modelversie vertonen in 30% van de gevallen onbedoelde kwaliteitsdegradatie).

Het gestructureerd onderhouden van gedeelde prompts rust op drie specifieke pijlers:

1. Periodieke Opschoning van Few-Shot Voorbeelden

Few-shot voorbeelden die zijn opgesteld voor een oudere modelgeneratie kunnen op nieuwere modellen een averechts effect hebben. Nieuwere modellen hebben vaak minder of juist specifieker gestructureerde voorbeelden nodig om hetzelfde kwaliteitsniveau te behalen. Controleer bij elke major update van het doelmodel of de ingesloten voorbeelden nog noodzakelijk en representatief zijn.

2. Beheer van Modelnamen en Provider-Aliases

Het koppelen van een gedeelde prompt aan een generieke model-alias zoals gpt-4o of claude-3-5-sonnet veroorzaakt risico's. Providers passen de onderliggende modelversie achter deze aliases regelmatig aan. In de documentatie moet daarom altijd de exacte, gefixeerde versiestring worden vastgelegd (bijvoorbeeld claude-3-5-sonnet-20241022), gecombineerd met de datum waarop de instructie op die specifieke versie is gevalideerd.

3. Versiehistorie en Changelog per Prompt

Elk promptbestand moet beschikken over een changelog in de frontmatter of in de bijbehorende documentatie. Een changelog-regel bevat minimaal de versienummering, de datum, de auteur, de reden van de aanpassing en de geobserveerde impact op de uitvoerkwaliteit. Dit maakt het voor teamleden direct inzichtelijk waarom bepaalde instructielijnen zijn toegevoegd of gewijzigd.

Voordat een aanpassing in een gedeelde prompt definitief wordt doorgevoerd in de hoofdbranch van de bibliotheek, dient deze een collegiale toetsing te ondergaan. Lees hoe je prompts kunt reviewen in een team om kwaliteitsborging en beveiligingscontroles in het ontwikkelproces in te richten.

Aanpassingen aan een gedeelde prompt mogen nooit plaatsvinden op basis van gevoel of incidentele waarnemingen. Om objectief vast te stellen of een gewijzigde instructie daadwerkelijk een verbetering oplevert ten opzichte van de vorige versie, is kwantitatieve evaluatie verplicht. Voer gedefinieerde A/B-testen op prompts uit om te verifiëren of een gedocumenteerde instructiewijziging daadwerkelijk tot betere modeluitvoer leidt.

Overzicht van Conventies voor Promptdocumentatie

De onderstaande tabel geeft een overzicht van de minimale eisen waaraan een gedeeld promptbestand binnen het ontwikkelteam moet voldoen:

Onderdeel Vereiste Standaard Doel van de Conventie
Bestandsnaam Kebab-case met functionele hiërarchie (domein/actie.prompt.md) Voorkomt naamconflicten en maakt de functie van het bestand direct herkenbaar.
Metadata YAML frontmatter met verplichte velden (id, version, owner, target_model) Borgt automatische uitleesbaarheid door linter-tools en CI/CD-pipelines.
Modelconfiguratie Exacte versiestring van de provider plus temperatuur en tokenlimiet Garandeert dat de prompt onder exact dezelfde condities wordt uitgevoerd.
Datahygiëne Geen credentials, PII of vertrouwelijke interne context in tekst of voorbeelden Voorkomt datalekken en beveiligingsrisico's bij distributie binnen of buiten het team.
Invoer/Uitvoer Expliciteer alle variabelen en definieer een JSON-schema voor de uitvoer Maakt het artefact zelfstandig uitvoerbaar voor andere ontwikkelaars.
Onderhoud Changelog bijhouden en periodiek valideren tegen nieuwe modelversies Voorkomt 'prompt rot' en borgt kwaliteitsbehoud op de lange termijn.

Door deze conventies vanaf de start van een project strikt te hanteren, transformeren losse instructies in betrouwbare, overdraagbare en onderhoudbare software-artefacten die naadloos meeschalen met de organisatie.