PricingLoginStart free
AI Prompt Engineering · Lección

Análisis de causa raíz de prompts

Determine si el fallo está en el contexto, la instrucción, el formato o las capacidades del modelo.

Lección 2 de 413 pasos

Análisis de causa raíz de prompts es una lección gratuita de AI Prompt Engineering en CoddyKit. Esta es la lección 2 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de AI Prompt Engineering, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de AI Prompt Engineering incluye 4 lecciones en total.

Por qué es importante el análisis de causa raíz

Cuando falla un prompt, puede haber varias causas posibles. Cambiar la redacción al azar hace perder tiempo y puede corregir el síntoma sin solucionar la causa raíz, lo que provoca el mismo fallo con entradas ligeramente diferentes.

El análisis de causa raíz (RCA) es un proceso sistemático para aislar el motivo específico por el que falla un prompt, de modo que la corrección aborde el problema real.

Las cuatro categorías de causas raíz

Todo fallo de un prompt se remonta a una de cuatro causas raíz:

  1. Problema de contexto: al modelo le falta información necesaria para responder correctamente
  2. Ambigüedad de la instrucción: la instrucción admite varias interpretaciones válidas y el modelo elige la incorrecta
  3. Conflicto de formato: dos partes del prompt proporcionan instrucciones de formato contradictorias
  4. Límite de capacidad del modelo: la tarea requiere un razonamiento o unos conocimientos que el modelo no puede realizar de forma fiable

Causa raíz 1: Problema de contexto

Un problema de contexto se produce cuando el modelo responde incorrectamente porque el prompt no proporciona la información necesaria. El modelo rellena la laguna con datos de entrenamiento, que pueden estar desactualizados, ser incorrectos o proceder de una alucinación.

Prueba: proporcione directamente la información que falta en el prompt y compruebe si mejora la respuesta. Si es así, la solución consiste en añadir contexto, por ejemplo mediante recuperación con 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

Causa raíz 2: Ambigüedad de la instrucción

La ambigüedad de la instrucción se produce cuando el prompt puede interpretarse razonablemente de varias maneras y el modelo elige la interpretación incorrecta.

Ejemplo: «Resuma brevemente». ¿Significa «brevemente» una oración, un párrafo o tres viñetas? El modelo adivina. Prueba: sustituya la frase ambigua por una especificación precisa y compruebe si el fallo se resuelve.

# 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

Causa raíz 3: Conflicto de formato

Un conflicto de formato se produce cuando dos partes del prompt proporcionan instrucciones contradictorias. El modelo debe elegir una e ignorar la otra, normalmente siguiendo la instrucción más reciente o destacada.

Ejemplo: el prompt del sistema dice «responda en texto sin formato» y el mensaje del usuario dice «use markdown». El modelo puede seguir cualquiera de las dos, de forma inconsistente.

# 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.'
)

Causa raíz 4: límite de capacidad del modelo

Un fallo por límite de capacidad ocurre cuando la tarea supera realmente lo que el modelo puede hacer de forma fiable. Esto es diferente de las otras tres causas: ningún cambio en el prompt lo solucionará por completo.

Señales: la tasa de fallos es alta incluso con instrucciones claras y todo el contexto. Soluciones: utilizar un modelo más potente, dividir la tarea en pasos más sencillos o añadir un paso de verificación.

# 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')

El método de aislamiento

Para identificar qué causa raíz está activa, utilice el aislamiento sistemático:

  1. Ejecute el prompt que falla y clasifique el tipo de fallo (respuesta incorrecta, formato, etc.)
  2. Añada información → si se corrige: problema de contexto
  3. Aclare las instrucciones → si se corrige: ambigüedad
  4. Audite las contradicciones → si se corrige: conflicto de formato
  5. Actualice el modelo → si se corrige: límite de capacidad

Solo debería ser necesaria una solución. Si se necesitan varias, había varias causas raíz.

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"}')

Eliminación frente a confirmación

El análisis de causa raíz sigue dos modalidades:

  • Eliminación: descarte las causas que NO son responsables (pruebe cada hipótesis y observe cuál NO cambia la salida)
  • Confirmación: identifique la causa que, al corregirse, resuelve de forma consistente el fallo en múltiples entradas de prueba

La confirmación requiere al menos 3 entradas de prueba. Una solución que funciona con una entrada, pero no con las demás, no ha resuelto la causa raíz; puede haber resuelto un síntoma.

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.')

Documentación de la causa raíz

Después de identificar la causa raíz, documéntela en el registro de cambios del prompt. Incluya:

  • Tipo de fallo observado
  • Categoría de la causa raíz
  • Hipótesis comprobada
  • Pruebas (qué prueba pasó después de la corrección)
  • El cambio específico realizado en el prompt

Esto evita que otros ingenieros vuelvan a investigar el mismo fallo y permite reconocer patrones entre distintos prompts.

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'
}

Error común: corregir la causa equivocada

El error más común en el análisis de causa raíz es corregir el síntoma en lugar de la causa. Ejemplo:

  • Síntoma: el modelo devuelve JSON con un prefijo de texto adicional
  • Corrección equivocada: añadir posprocesamiento para eliminar el texto adicional de la salida
  • Causa raíz real: no hay instrucciones de formato en el prompt + el modelo utiliza de forma predeterminada un estilo conversacional
  • Corrección adecuada: añadir la instrucción explícita 'Devuelva solo JSON válido. No incluya ningún otro texto.'

Los parches de posprocesamiento acumulan deuda técnica. Las correcciones de la causa raíz son duraderas.

Análisis de causa raíz de fallos intermitentes

Algunos fallos son intermitentes: el prompt funciona el 80 % de las veces, pero falla el 20 %. Son más difíciles de diagnosticar porque, al ejecutarlo una sola vez, se obtiene un resultado correcto.

Enfoque: ejecute el prompt entre 10 y 20 veces con la misma entrada. Si la tasa de fallos no es cero, el prompt tiene una causa raíz probabilística, normalmente ambigüedad en las instrucciones o una temperatura alta. Solución: haga la instrucción más específica o reduzca la temperatura.

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%}')

Comprobación de conocimientos

Un prompt solicita una respuesta JSON, pero ocasionalmente devuelve JSON precedido por un prefijo conversacional como '¡Claro! Aquí está el JSON:'. Después de añadir 'Devuelva solo JSON válido. No incluya ningún otro texto.', el fallo deja de producirse. ¿Cuál era la causa raíz?

Responde en la lección interactiva

Resumen: análisis de causa raíz

Las cuatro categorías de causas raíz de los fallos de los prompts:

  • Problema de contexto: al modelo le falta información necesaria; solución: añadir contexto mediante RAG o inyección directa
  • Ambigüedad en las instrucciones: instrucción vaga con varias interpretaciones; solución: añadir precisión
  • Conflicto de formato: instrucciones de formato contradictorias; solución: unificarlas en el prompt del sistema
  • Límite de capacidad del modelo: la tarea supera las capacidades del modelo; solución: actualizar el modelo o descomponer la tarea

Utilice el aislamiento sistemático para comprobar cada hipótesis. Confirme la solución con varios casos de prueba. Documente los hallazgos. Próxima lección: depuración sistemática mediante búsqueda binaria.

Gratis para empezar

Aprende AI Prompt Engineering con un tutor de IA — gratis

Escribe y ejecuta código real en tu navegador, obtén ayuda instantánea de un tutor de IA disponible 24/7 y continúa donde lo dejaste en la web o en la aplicación.

Cursos
53
Lecciones
199
Empezar a aprender gratisVer el curso completo

Preguntas frecuentes

¿La lección «Análisis de causa raíz de prompts» es gratis?

Sí — el texto completo de «Análisis de causa raíz de prompts» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de AI Prompt Engineering, actualiza a CoddyKit PRO. El curso de AI Prompt Engineering incluye 4 lecciones en total.

¿Qué aprenderé en «Análisis de causa raíz de prompts»?

Determine si el fallo está en el contexto, la instrucción, el formato o las capacidades del modelo. Practicas AI Prompt Engineering con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar AI Prompt Engineering?

No se requiere experiencia previa. AI Prompt Engineering en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 2 de 4.

¿Cuánto tiempo toma la lección «Análisis de causa raíz de prompts»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de AI Prompt Engineering?

Sí. Cada lección de AI Prompt Engineering incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

  1. Diagnóstico de resultados inesperados
  2. Análisis de causa raíz de prompts
  3. Enfoque sistemático para depurar
  4. Estrategias de registro y documentación
← Volver a AI Prompt Engineering