Prompting para Claude Opus 5

Esta guía cubre los patrones de prompting específicos de Claude Opus 5. Para conocer las capacidades del modelo y los cambios en la API, consulta Novedades en Claude Opus 5. Para técnicas que aplican a todos los modelos actuales de Claude, consulta Mejores prácticas de prompting.

Claude Opus 5 está diseñado para trabajo empresarial y de codificación agéntica compleja, con fortalezas particulares en tareas agénticas de largo horizonte. Funciona bien de forma inmediata con los prompts existentes de Claude Opus 4.8. Los siguientes patrones cubren los comportamientos que con mayor frecuencia requieren ajustes.

Mejoras de capacidades

En comparación con Claude Opus 4.8, las mejoras más relevantes para el prompting son:

• Codificación agéntica: Claude Opus 5 es más fuerte en tareas de codificación difíciles: funcionalidades que abarcan múltiples archivos, refactorizaciones más grandes y trabajo de funcionalidades de extremo a extremo. Completa tareas enteras en lugar de dejar stubs o marcadores de posición, y rinde mejor cuando se le da la especificación completa de la tarea desde el principio y se le deja ejecutar. También rinde bien en tareas más sencillas como ediciones de un solo turno, donde la diferencia con modelos anteriores es menor.
• Revisión de código y detección de errores: Claude Opus 5 revisa código con alta precisión y exhaustividad: encuentra errores reales a una tasa alta por pasada, y sus hallazgos adicionales son en su mayoría problemas reales en lugar de falsos positivos. La precisión se mantiene en configuraciones de esfuerzo más bajas, lo que permite una pasada rápida al momento de la revisión y una pasada más exhaustiva después. Si tu prompt de revisión dice "solo reporta problemas de alta severidad" o "sé conservador", el modelo puede seguir esa instrucción literalmente y reportar menos; en su lugar, pídele que reporte todo y filtra en una pasada separada.
• Eficiencia con menor esfuerzo: Los niveles de esfuerzo low y medium producen una calidad sólida con una fracción de los tokens y la latencia de las configuraciones más altas. Comienza con el valor predeterminado (high) y ajusta según tus evaluaciones: usa low y medium libremente como tu control principal del costo de tokens y el tiempo de respuesta siempre que la calidad se mantenga, y sube a xhigh para trabajo agéntico y de codificación exigente. Si trasladaste valores predeterminados de esfuerzo de un modelo anterior, vuelve a ejecutar un barrido de esfuerzo en tus propias evaluaciones. Consulta Esfuerzo para ver las recomendaciones completas.
• Visión: Claude Opus 5 es fuerte en la comprensión de gráficos, documentos y diagramas, y en la replicación visual de interfaces de usuario y frontend. Vuelve a validar cualquier solución alternativa de visión del lado del prompt que hayas ajustado para modelos anteriores; es posible que ya no sean necesarias. El rendimiento de visión es más fuerte cuando el modelo tiene herramientas para analizar, recortar y verificar visualmente su trabajo de forma iterativa, y el "tool use" (uso de herramientas) es una palanca más rentable que el pensamiento por sí solo.
• Trabajo con contexto largo: Claude Opus 5 tiene una "context window" (ventana de contexto) de 1M de tokens tanto como valor predeterminado como máximo, y su seguimiento de instrucciones, llamadas a herramientas y razonamiento se mantienen consistentes a lo largo de toda la ventana.
• Tareas de oficina y documentos: Claude Opus 5 genera y trabaja con hojas de cálculo complejas de múltiples hojas con fórmulas no triviales, y produce presentaciones de diapositivas bien estructuradas. Indícale cualquier estilo o plantilla específica que deba seguir.
• Coordinación multiagente: Claude Opus 5 coordina bien equipos de subagentes, con patrones efectivos de escritor-verificador y pocos casos de agentes que sobrescriben el trabajo de otros. Para cargas de trabajo sensibles al costo, limita la delegación; consulta Control de la creación de subagentes.

Longitud de respuesta y verbosidad

Las respuestas predeterminadas de Claude Opus 5 dirigidas al usuario son más largas que las de los modelos Opus anteriores. El parámetro de esfuerzo controla cuánto piensa el modelo en lugar de cuánto dice: reducir el esfuerzo puede disminuir el volumen de pensamiento sin acortar de forma confiable la respuesta visible. Para controlar la longitud de la respuesta, indícalo explícitamente en el prompt.

Una instrucción breve de concisión es efectiva. Por ejemplo, para un producto de múltiples turnos dirigido al usuario:

Keep responses focused, brief, and concise. Keep disclaimers and caveats short, and spend most of the response on the main answer. When asked to explain something, give a high-level summary unless an in-depth explanation is specifically requested.

En una indicación del sistema larga, acompaña la instrucción con un breve recordatorio cerca del final del prompt:

<tone_preference>
Keep outputs reasonably concise.
</tone_preference>

Actualizaciones de progreso dirigidas al usuario

Claude Opus 5 narra con facilidad durante el trabajo agéntico: tiende a anunciar lo que está a punto de hacer, y su salida por mensaje en sesiones agénticas suele ser más larga que la de modelos anteriores. Se beneficia de una orientación explícita sobre cómo comunicarse con el usuario durante una tarea. Para reducir la narración, describe la cadencia y la forma que deseas:

Before your first tool call, say in one sentence what you're about to do. While working, give a brief update only when you find something important or change direction. When you finish, lead with the outcome: your first sentence should answer "what happened" or "what did you find," with supporting detail after it for readers who want it.

Para aumentar la narración, o cambiar su estilo, la misma palanca aplica en la dirección opuesta: describe explícitamente cómo deben verse las actualizaciones y proporciona ejemplos. Los ejemplos positivos del estilo de comunicación que deseas tienden a ser más efectivos que las instrucciones sobre qué no hacer.

Longitud de los entregables escritos

Aparte de la verbosidad conversacional, los archivos que Claude Opus 5 escribe en disco (informes, documentos Markdown, resúmenes) suelen ser más largos que en modelos anteriores. Si tu producto incluye documentos redactados por Claude, agrega una calibración explícita de longitud:

Match the length of written documents to what the task needs: cover the substance, but do not pad with filler sections, redundant summaries, or boilerplate.

Alcance de la tarea y sobreverificación

Claude Opus 5 verifica su propio trabajo sin que se le indique. Si tu prompt contiene instrucciones explícitas de verificación ("incluye un paso final de verificación para cualquier tarea no trivial", "usa un subagente para verificar"), elimínalas: instrucciones como estas causan sobreverificación en Claude Opus 5, y eliminarlas reduce los tokens desperdiciados sin pérdida de calidad. Lo mismo aplica al andamiaje heredado del harness que agrega pasos de verificación separados.

Claude Opus 5 también puede ampliar el alcance de una tarea, agregando pasos que no se solicitaron o aplicando su propio criterio sobre cuál debería ser la tarea. Para tareas acotadas, restringe el alcance explícitamente:

Deliver what was asked, at the scope intended. Make routine judgment calls yourself, and check in only when different readings of the request would lead to materially different work. If the request seems mistaken or a better approach exists, say so in a sentence and continue with the task as asked rather than quietly narrowing, widening, or transforming it. Finish the whole task, and stop short of actions that are clearly beyond what was asked.

Control de la creación de subagentes

Claude Opus 5 delega a subagentes con más facilidad que los modelos anteriores. La delegación vale la pena en líneas de trabajo genuinamente independientes y de tamaño considerable, pero multiplica el costo y el tiempo cuando se aplica a tareas pequeñas. Si tu harness admite subagentes, proporciona orientación explícita sobre qué escenarios justifican la delegación, o establece límites deterministas sobre cuántos agentes se pueden lanzar. Por ejemplo:

Delegate to a subagent only for large tasks that are genuinely independent and parallelizable, such as a wide multi-file investigation. Do not delegate work you can finish yourself in a handful of tool calls, and do not use subagents to verify or double-check your own work. If one subagent can complete the task, use one rather than several, and keep spawn counts low.

Si tu harness es Claude Code o el Claude Agent SDK, los límites deterministas son las variables de entorno CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH y CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS y la opción max_budget_usd del SDK. Requieren Claude Code 2.1.217 o posterior, así que actualiza un SDK fijado a una versión antes de apuntarlo a Claude Opus 5. Claude Code agrega una instrucción de delegación propia en Claude Opus 5 solo cuando usas su preset de indicación del sistema claude_code; con una indicación del sistema personalizada u omitida, agrega tú mismo una instrucción de delegación como el ejemplo de esta sección. Consulta Limitar la profundidad, concurrencia y gasto de subagentes en la documentación del Agent SDK.

Autocorrección

Claude Opus 5 detecta y corrige bien sus propios errores sin necesidad de indicárselo. Evita instruir revisiones que ya realiza ("verifica dos veces tu respuesta", "vuelve a verificar antes de responder"); al igual que las instrucciones de verificación, estas se acumulan con el comportamiento propio del modelo y agregan costo sin mejorar los resultados.

El modelo también narra correcciones a sus afirmaciones anteriores más que los modelos previos, lo cual puede ser indeseable en productos dirigidos al usuario. Para limitar la narración de correcciones a las correcciones que importan:

Only correct an earlier statement when the error would change the user's code, conclusions, or decisions. State corrections plainly and briefly, then continue the task. For slips that change nothing for the user, make the fix and move on without noting it.

Ejecución con el pensamiento deshabilitado

Claude Opus 5 se ejecuta con el pensamiento activado por defecto, y el pensamiento solo puede deshabilitarse con un esfuerzo high o inferior; consulta la guía de migración. Con el pensamiento deshabilitado, ocasionalmente pueden aparecer dos artefactos en la salida visible del modelo. La mitigación principal para ambos es mantener el pensamiento habilitado y controlar el costo de tokens con niveles de esfuerzo más bajos en lugar de deshabilitar el pensamiento: para la mayoría de las tareas, el pensamiento habilitado con esfuerzo low rinde mejor que el pensamiento deshabilitado a un costo similar.

Llamadas a herramientas como texto. Con el pensamiento deshabilitado, el modelo ocasionalmente escribe una llamada a herramienta en su texto dirigido al usuario en lugar de emitir un bloque tool_use estructurado. El turno se completa normalmente y la llamada nunca se ejecuta, y en bucles agénticos el texto filtrado permanece en el historial de la conversación, por lo que los turnos posteriores también se ven afectados. Esto es más común en cargas de trabajo con uso intensivo de herramientas, como la búsqueda.

Etiquetas XML internas en la salida. Con el pensamiento deshabilitado, el modelo puede emitir etiquetas <thinking> u otras etiquetas XML internas en su respuesta visible. Si tu indicación del sistema contiene una regla que instruye al modelo a no pensar o no razonar, elimínala; ese tipo de instrucción aumenta la filtración de etiquetas.

Para integraciones que deben mantener el pensamiento deshabilitado, una única instrucción combinada mitiga ambos artefactos: le da al modelo permiso explícito para hablar antes de una llamada a herramienta, una alternativa a forzar una llamada cuando ninguna herramienta es adecuada, y una regla general contra las etiquetas internas:

When you use a tool, you may say a brief sentence first. If no tool can express what the user asked for, say so instead of guessing. Do not include internal or system XML tags in your response.

Las instrucciones que mencionan las etiquetas de pensamiento por su nombre son menos efectivas que la forma general, así que evita nombrarlas específicamente.