AI-promptengineering · Les

Root-causeanalyse voor prompts

Bepaal of de fout in de context, instructie, indeling of modelcapaciteit zit.

Les 2 van 413 stappen

Root-causeanalyse voor prompts is een gratis AI-promptengineering-les op CoddyKit. Dit is les 2 van 4. Je kunt 3 lessen uit dit leerpad gratis volledig lezen — daarna ontgrendelt CoddyKit PRO alle lessen, plus praktische oefeningen met een ingebouwde code-editor en een AI-tutor die 24/7 beschikbaar is. Deze les maakt deel uit van het leertraject AI-promptengineering. Je voortgang wordt gesynchroniseerd op het web en in de CoddyKit-app. De cursus AI-promptengineering bevat in totaal 4 lessen.

Waarom analyse van de hoofdoorzaak belangrijk is

Wanneer een prompt mislukt, zijn er meerdere mogelijke oorzaken. Willekeurig aan de formulering sleutelen kost tijd en kan het symptoom oplossen zonder de hoofdoorzaak aan te pakken — waardoor dezelfde fout bij net andere invoer opnieuw optreedt.

Analyse van de hoofdoorzaak (RCA) is een systematisch proces om de specifieke reden vast te stellen waarom een prompt mislukt, zodat de oplossing het werkelijke probleem aanpakt.

De vier categorieën van hoofdoorzaken

Elke fout in een prompt is terug te voeren op een van vier hoofdoorzaken:

Contextprobleem: het model mist informatie die nodig is om correct te antwoorden
Onduidelijke instructie: de instructie heeft meerdere geldige interpretaties en het model kiest de verkeerde
Conflict in indeling: twee delen van de prompt geven tegenstrijdige instructies voor de indeling
Grens van de modelmogelijkheden: de taak vereist redeneervermogen of kennis die dit model niet betrouwbaar kan bieden

Hoofdoorzaak 1: Contextprobleem

Een contextprobleem treedt op wanneer het model onjuist antwoordt omdat de prompt niet de benodigde informatie bevat. Het model vult het gat op met trainingsgegevens — die verouderd, onjuist of verzonnen kunnen zijn.

Controle: geef de ontbrekende informatie rechtstreeks in de prompt en kijk of het antwoord verbetert. Zo ja, dan is de oplossing het toevoegen van context (bijvoorbeeld door informatie op te halen via RAG).

# Failing prompt — no context
prompt_v1 = 'What is the current price of our Pro plan?'

# Context problem test: inject the information
prompt_v2 = '''
Our pricing (as of today):
- Free: $0/month
- Pro: $19/month
- Enterprise: $99/month

Question: What is the current price of our Pro plan?
'''
# If v2 succeeds and v1 fails -> root cause is context problem

Hoofdoorzaak 2: Onduidelijke instructie

Een onduidelijke instructie ontstaat wanneer de prompt redelijkerwijs op meerdere manieren kan worden geïnterpreteerd en het model de verkeerde interpretatie kiest.

Voorbeeld: 'Vat kort samen' — betekent 'kort' één zin, één alinea of drie opsommingstekens? Het model gokt. Controleer dit door de onduidelijke formulering te vervangen door een precieze specificatie en na te gaan of de fout verdwijnt.

# Ambiguous
prompt_ambiguous = 'Summarize the following article briefly.'

# Precise — ambiguity removed
prompt_precise = (
    'Summarize the following article in exactly 2 sentences. '
    'Do not exceed 50 words. Output only the summary, nothing else.'
)

# Test: if precise version succeeds, root cause was ambiguity
# Fix: replace vague qualifiers with exact specifications

Hoofdoorzaak 3: Conflict in indeling

Een conflict in indeling treedt op wanneer twee delen van de prompt tegenstrijdige instructies geven. Het model moet er één kiezen en de andere negeren — meestal kiest het de recentere of nadrukkelijkere instructie.

Voorbeeld: de systeemprompt zegt 'antwoord in platte tekst', terwijl het gebruikersbericht zegt 'gebruik markdown'. Het model kan de ene of de andere instructie volgen, zonder consistentie.

# Format conflict example
system_prompt = 'You are a helpful assistant. Always respond in plain text without any formatting.'

user_message = 'List the top 5 benefits of exercise. Use markdown bullet points.'

# The model faces a conflict: plain text vs markdown.
# Detection: if output format is inconsistent across runs, look for conflicting instructions.

# Fix: ensure all format instructions agree. Move format to system prompt only.
system_prompt_fixed = (
    'You are a helpful assistant. '
    'Always respond using markdown bullet points for lists.'
)

Hoofdoorzaak 4: capaciteitslimiet van het model

Een fout door een capaciteitslimiet ontstaat wanneer de taak daadwerkelijk verder gaat dan wat het model betrouwbaar kan uitvoeren. Dit verschilt van de andere drie oorzaken: geen enkele wijziging van de prompt lost het probleem volledig op.

Signalen: het foutpercentage blijft hoog, zelfs met duidelijke instructies en volledige context. Oplossingen: gebruik een krachtiger model, splits de taak op in eenvoudigere stappen of voeg een verificatiestap toe.

# Capability limit test: try the same task on different models
models = ['gpt-4o-mini', 'gpt-4o', 'gpt-4o-2024-11-20']
results = {}

for model in models:
    resp = client.chat.completions.create(
        model=model,
        messages=[{'role': 'user', 'content': complex_reasoning_prompt}]
    )
    results[model] = evaluate(resp.choices[0].message.content)

# If accuracy improves with more capable models -> capability limit
for model, score in results.items():
    print(f'{model}: {score:.0%} accuracy')

De isolatiemethode

Gebruik systematische isolatie om vast te stellen welke hoofdoorzaak actief is:

Voer de prompt met de fout uit en classificeer het fouttype (verkeerd antwoord, formaat enzovoort)
Voeg informatie toe → als het probleem is opgelost: contextprobleem
Verduidelijk de instructies → als het probleem is opgelost: dubbelzinnigheid
Controleer op tegenstrijdigheden → als het probleem is opgelost: formatconflict
Upgrade het model → als het probleem is opgelost: capaciteitslimiet

Er zou maar één oplossing nodig moeten zijn. Als er meerdere oplossingen nodig zijn, waren er meerdere hoofdoorzaken.

def rca_test(base_prompt, test_input, expected_output):
    results = {}

    # Test 1: base (failing) prompt
    results['base'] = run_and_evaluate(base_prompt, test_input, expected_output)

    # Test 2: add context
    results['with_context'] = run_and_evaluate(
        base_prompt + '\nContext: ' + get_context(test_input),
        test_input, expected_output
    )

    # Test 3: clarify instructions
    results['clarified'] = run_and_evaluate(
        clarify(base_prompt), test_input, expected_output
    )

    for name, passed in results.items():
        print(f'{name}: {"PASS" if passed else "FAIL"}')

Eliminatie versus bevestiging

RCA kent twee werkwijzen:

Eliminatie: sluit oorzaken uit die NIET verantwoordelijk zijn (test elke hypothese en kijk welke hypothese de uitvoer NIET verandert)
Bevestiging: identificeer de oorzaak die de fout consequent oplost wanneer je deze herstelt, bij meerdere testinvoeren

Voor bevestiging zijn minstens 3 testinvoeren nodig. Een oplossing die voor één invoer werkt maar niet voor andere, heeft de hoofdoorzaak niet opgelost: misschien is alleen een symptoom verholpen.

def confirm_root_cause(fix_fn, test_cases, threshold=0.9):
    '''fix_fn: a function that takes a prompt and returns a fixed prompt'''
    passed = 0
    for case in test_cases:
        fixed_prompt = fix_fn(case['prompt'])
        result = run_and_evaluate(fixed_prompt, case['input'], case['expected'])
        if result:
            passed += 1

    pass_rate = passed / len(test_cases)
    print(f'Fix pass rate: {pass_rate:.0%}')
    if pass_rate >= threshold:
        print('Root cause CONFIRMED — fix is reliable.')
    else:
        print('Root cause NOT confirmed — failure has multiple causes.')

De hoofdoorzaak documenteren

Documenteer de hoofdoorzaak na het identificeren ervan in het wijzigingslogboek van de prompt. Neem het volgende op:

Het waargenomen fouttype
De categorie van de hoofdoorzaak
De geteste hypothese
Het bewijs (welke test na de oplossing slaagde)
De specifieke wijziging die aan de prompt is aangebracht

Zo voorkom je dat toekomstige ontwikkelaars dezelfde fout opnieuw onderzoeken en maak je patroonherkenning tussen prompts mogelijk.

rca_record = {
    'prompt_id': 'summarize_v3',
    'failure_type': 'wrong_format',
    'root_cause': 'format_conflict',
    'hypothesis': 'System prompt said plain text, user message asked for markdown',
    'evidence': 'Removing markdown instruction from user message resolved failure on 8/8 test cases',
    'fix_applied': 'Moved all format instructions to system prompt; removed format instructions from user template',
    'fix_date': '2024-11-15'
}

Veelgemaakte fout: de verkeerde oorzaak oplossen

De meest voorkomende RCA-fout is dat je het symptoom oplost in plaats van de oorzaak. Bijvoorbeeld:

Symptoom: het model retourneert JSON met een extra inleidende tekst
Verkeerde oplossing: nabewerking toevoegen om de inleidende tekst uit de uitvoer te verwijderen
Werkelijke hoofdoorzaak: er staat geen formaatinstructie in de prompt en het model gebruikt standaard een conversationele stijl
Juiste oplossing: de expliciete instructie 'Geef alleen geldige JSON terug. Geen andere tekst.' toevoegen

Hacks voor nabewerking stapelen technische schuld op. Oplossingen die de hoofdoorzaak aanpakken, blijven duurzaam werken.

RCA bij intermitterende fouten

Sommige fouten zijn intermitterend: de prompt werkt 80% van de tijd, maar faalt 20% van de tijd. Deze fouten zijn moeilijker te diagnosticeren, omdat één keer uitvoeren van de prompt een correct resultaat oplevert.

Aanpak: voer de prompt 10–20 keer uit met dezelfde invoer. Als het foutpercentage niet nul is, heeft de prompt een probabilistische hoofdoorzaak, meestal dubbelzinnigheid in de instructie of een hoge temperatuur. Oplossing: maak de instructie specifieker of verlaag de temperatuur.

def measure_failure_rate(prompt, test_input, expected, runs=20):
    failures = 0
    for _ in range(runs):
        resp = client.chat.completions.create(
            model='gpt-4o',
            messages=[{'role': 'user', 'content': prompt + '\n' + test_input}],
            temperature=0.7
        )
        if not evaluate(resp.choices[0].message.content, expected):
            failures += 1
    print(f'Failure rate: {failures}/{runs} = {failures/runs:.0%}')

Kenniscontrole

Een prompt vraagt om een JSON-antwoord, maar retourneert soms JSON met een conversationele inleiding zoals 'Zeker! Hier is de JSON:'. Nadat je 'Geef alleen geldige JSON terug. Geen andere tekst.' hebt toegevoegd, stopt de fout. Wat was de hoofdoorzaak?

Beantwoord dit in de interactieve les

Samenvatting: analyse van hoofdoorzaken

De vier categorieën van hoofdoorzaken voor fouten in prompts:

Contextprobleem: het model mist benodigde informatie — oplossing: voeg context toe via RAG of directe injectie
Dubbelzinnigheid in de instructie: een vage instructie met meerdere interpretaties — oplossing: voeg precisie toe
Formatconflict: tegenstrijdige formaatinstructies — oplossing: voeg ze samen in de systeemprompt
Capaciteitslimiet van het model: de taak gaat verder dan wat het model kan — oplossing: upgrade het model of splits de taak op

Gebruik systematische isolatie om elke hypothese te testen. Bevestig de oplossing met meerdere testgevallen. Documenteer je bevindingen. Volgende les: systematisch debuggen met binair zoeken.

Gratis beginnen

Leer AI-promptengineering met een AI-tutor — gratis

Schrijf echte code en voer die uit in je browser, krijg direct hulp van een AI-tutor die 24/7 beschikbaar is en ga verder waar je gebleven bent op het web of in de app.

Cursussen: 53
Lessen: 199

Gratis beginnen met leren Bekijk de volledige cursus

Veelgestelde vragen

Is de les “Root-causeanalyse voor prompts” gratis?

Ja — je kunt hier op het web alle 3 lessen van het leerpad AI-promptengineering, waaronder “Root-causeanalyse voor prompts”, gratis volledig lezen. Daarna ontgrendelt CoddyKit PRO alle lessen, plus interactieve oefeningen met een ingebouwde code-editor en een AI-tutor die 24/7 beschikbaar is. De cursus AI-promptengineering bevat in totaal 4 lessen.

Wat leer ik in “Root-causeanalyse voor prompts”?

Bepaal of de fout in de context, instructie, indeling of modelcapaciteit zit. Je oefent met AI-promptengineering door code rechtstreeks in de browser uit te voeren. Een AI-begeleider die 24/7 beschikbaar is beantwoordt je vragen terwijl je de les doorwerkt.

Heb ik ervaring nodig om met AI-promptengineering te beginnen?

Ervaring vooraf is niet nodig. AI-promptengineering op CoddyKit is opgebouwd voor beginners tot gevorderden, zodat je hier of bij het begin kunt starten en in je eigen tempo kunt leren. Dit is les 2 van 4.

Hoe lang duurt de les “Root-causeanalyse voor prompts”?

De meeste lessen van CoddyKit duren ongeveer 5–10 minuten. Elke les is kort en interactief, zodat je gestaag vooruitgaat en op het web en in de app precies verdergaat waar je was gebleven.

Kan ik code schrijven en uitvoeren in deze les over AI-promptengineering?

Ja. Elke les over AI-promptengineering bevat een ingebouwde code-editor, zodat je rechtstreeks in je browser echte code kunt schrijven en uitvoeren en direct feedback van AI krijgt — lokale installatie is niet nodig.

Alle lessen in deze cursus

Onverwachte uitvoer diagnosticeren
Root-causeanalyse voor prompts
Systematische aanpak voor debuggen
Strategieën voor logging en documentatie

← Terug naar AI-promptengineering