Reglas de ingeniería de contexto para el modelo Claude 5

Para utilizar eficazmente los modelos Claude con una capacidad de juicio mejorada, no basta con perfeccionar una sola frase del prompt. Es necesario diseñar como un único entorno de información las instrucciones del sistema, los archivos del proyecto, las herramientas, la memoria, el historial de conversaciones y los resultados de ejecución que el modelo verá durante una inferencia.

El principio fundamental es sencillo.

En lugar de prescribir de antemano cada comportamiento, proporciona un objetivo claro, límites de seguridad, interfaces expresivas y materiales de referencia fiables, y deja las decisiones de detalle en manos del modelo.

En este artículo, Claude 5 se refiere al entorno de modelos Claude de alto rendimiento de próxima generación al que aluden los materiales proporcionados. El enfoque no está en especificaciones concretas del producto ni en su estado de lanzamiento, sino en principios de diseño del contexto aplicables a modelos con una capacidad de juicio mejorada.

Ingeniería de prompts e ingeniería de contexto

Ingeniería de prompts

La ingeniería de prompts consiste en diseñar cómo expresar la solicitud actual. Por lo general, aborda los siguientes elementos.

• Objetivo de la tarea
• Alcance de la ejecución
• Restricciones
• Formato de salida
• Criterios de éxito
• Ejemplos necesarios

Por ejemplo:

Implementa una función de cancelación de pagos en una API Route de Next.js.
Reutiliza la capa de servicio existente y añade pruebas.
No modifiques el contrato de la API pública y explica el motivo de los cambios.

Ingeniería de contexto

La ingeniería de contexto consiste en seleccionar y mantener todo el conjunto de información que interviene en el razonamiento del modelo. En agentes de programación como Claude Code, el contexto se compone aproximadamente de los siguientes elementos.

Solicitud actual del usuario
+ instrucciones del sistema
+ CLAUDE.md e instrucciones del proyecto
+ Skills
+ memoria automática
+ código, especificaciones, pruebas y documentación
+ definiciones de herramientas y recursos MCP
+ historial de conversaciones
+ resultados de ejecución de herramientas y registros de errores

Por tanto, incluso un buen prompt puede perder eficacia si se proporciona junto con memoria obsoleta, reglas de proyecto duplicadas o registros enormes. Por el contrario, una solicitud breve puede ejecutarse con suficiente precisión si viene acompañada del código y las pruebas pertinentes, así como de herramientas claras.

Por qué más contexto no siempre es mejor

Aunque la ventana de contexto de los LLM aumente, la atención disponible para una tarea no es ilimitada. Si aumenta la cantidad de tokens poco relevantes, pueden surgir los siguientes problemas.

1. Los requisitos importantes quedan enterrados entre explicaciones prolijas.
2. Instrucciones similares situadas en lugares distintos entran en conflicto de forma sutil.
3. Decisiones antiguas o intentos fallidos influyen en la tarea actual.
4. Los ejemplos actúan como si fueran la respuesta correcta y limitan otras vías de solución.
5. Los registros y las salidas de las herramientas ocupan el espacio necesario para el código, las especificaciones y las pruebas.
6. El modelo consume razonamiento interpretando la prioridad de las instrucciones en lugar de realizar la tarea propiamente dicha.

Anthropic explica el fenómeno de la reducción de la eficiencia en el uso de la información dentro de contextos largos y recomienda diseñar los agentes para que recuperen la información necesaria en el momento oportuno y compriman los registros obsoletos. Lo importante no es llenar el número máximo de tokens, sino aumentar la proporción de tokens de alta señal que influyen en el resultado.

Qué implica el caso de reducción del prompt del sistema

El caso de Anthropic proporcionado explica que, tras revisar las instrucciones internas de Claude Code, se redujo el prompt del sistema al menos un 80 %. Esta cifra no es una regla que obligue a reducir en la misma proporción los prompts de todas las aplicaciones. Debe entenderse como un caso en el que se depuraron instrucciones de comportamiento duplicadas y excesivamente detalladas dentro de un sistema concreto.

Por ejemplo, las siguientes instrucciones podrían aparecer simultáneamente en una solicitud.

Instrucción del sistema: deja documentación adecuada a la situación.
Instrucción de Skill: no añadas comentarios.
Solicitud del usuario: haz que funcione como la versión anterior.

Cada frase puede ser válida por separado, pero al combinarlas surgen varios problemas de interpretación.

• ¿La documentación y los comentarios del código pertenecen a la misma categoría?
• ¿La prohibición de comentarios es una regla sin excepciones?
• ¿El comportamiento de la versión anterior incluye también los comentarios o la estructura de la documentación?
• ¿Qué tiene prioridad, la solicitud actual o el Skill reutilizable?

En este caso, la causa del fallo no es únicamente la capacidad de programación del modelo. También influye que el entorno de información configurado por las personas contenga contradicciones innecesarias.

Seis nuevas reglas de diseño del contexto

1. Sustituye las listas detalladas de prohibiciones por principios basados en el contexto

Para evitar los errores repetitivos de modelos anteriores, a veces se enumeraban extensamente reglas como las siguientes.

• No escribas comentarios.
• No crees docstrings de varios párrafos.
• No generes documentos de planificación que no se hayan solicitado.
• No guardes archivos intermedios de análisis.

Estas reglas evitan fallos específicos, pero no son principios absolutos aplicables a todas las situaciones. Una validación de seguridad compleja o el código concurrente pueden necesitar explicaciones, mientras que en un código CRUD evidente los comentarios pueden generar más ruido.

Es preferible presentar criterios de decisión como los siguientes.

Escribe código que se lea del mismo modo que el código circundante.
Sigue las convenciones de nombres, las expresiones idiomáticas y la densidad de comentarios de los archivos existentes.
Añade únicamente la documentación necesaria para la lógica cuya seguridad o intención no resulte clara sin una explicación.

Sin embargo, no se deben debilitar todas las reglas. Los siguientes elementos deben mantenerse como restricciones explícitas o controles a nivel de herramienta.

• Aprobación para el despliegue en producción y la eliminación de datos
• Restricciones sobre el tratamiento de datos personales e información confidencial
• Verificación de autenticación y autorización
• Idempotencia y registros de auditoría de transacciones financieras
• Políticas de migración de bases de datos
• Cumplimiento legal, de licencias y normativo
• Contratos inmutables de API públicas

2. Diseña herramientas expresivas en lugar de proporcionar muchos ejemplos

Si se siguen añadiendo casos de llamadas correctas e incorrectas a la descripción de una herramienta, el contexto crece y el modelo puede imitar la forma superficial de los ejemplos. Un método mejor consiste en diseñar el nombre de la herramienta, los campos de entrada y las transiciones de estado para que revelen cómo se utiliza.

TodoWrite
Objetivo: crear y actualizar la lista de tareas de la sesión actual

status:
- pending
- in_progress
- completed

Restricción:
- solo una tarea puede estar in_progress al mismo tiempo

Una buena herramienta para agentes tiene las siguientes características.

• Su nombre revela por sí solo la acción y el objeto.
• Distingue entre campos obligatorios y opcionales.
• Limita los valores permitidos mediante enumeraciones.
• Separa la lectura de la escritura, y la vista previa de la ejecución.
• Los errores devuelven de forma estructurada la causa y el método de recuperación.
• Las operaciones peligrosas requieren un token de confirmación o una fase de aprobación.
• Si el resultado es demasiado largo, ofrece un resumen y funciones de paginación.

Conviene añadir ejemplos únicamente cuando sea necesario explicar excepciones o entradas ambiguas difíciles de expresar mediante la interfaz.

3. No introduzcas toda la información desde el principio; revélala progresivamente

No se debe inyectar desde el principio todo el repositorio, todas las políticas y registros extensos solo porque exista la posibilidad de que el agente los necesite para la tarea. Primero hay que proporcionar la información mínima necesaria para explorar y permitir que lea los materiales pertinentes a medida que se concreta la tarea.

El flujo recomendado es el siguiente.

1. Proporciona el objetivo, los criterios de éxito y los límites de seguridad.
2. Localiza las ubicaciones pertinentes mediante la estructura del repositorio o herramientas de búsqueda.
3. Lee solo los archivos y las especificaciones necesarios.
4. Tras la implementación, ejecuta las pruebas y los análisis estáticos pertinentes.
5. Si se produce un fallo, recupera únicamente el error correspondiente y el código circundante.
6. Al terminar, comprime o elimina los registros obsoletos y el razonamiento intermedio.

La revelación progresiva no consiste en ocultar información. Consiste en ofrecer rutas de búsqueda y una estructura de archivos clara para que el modelo pueda descubrir la información necesaria.

4. Elimina las instrucciones duplicadas y establece ubicaciones autorizadas

Si se duplica la misma regla en el prompt del sistema, CLAUDE.md, un Skill y la descripción de una herramienta, la redacción puede divergir con el tiempo. Para cada tipo de instrucción debe establecerse una única ubicación autorizada.

Si la duplicación es inevitable, es más seguro señalar la ubicación autorizada o generar automáticamente el contenido en lugar de copiarlo.

5. Separa las funciones de CLAUDE.md y la memoria automática

CLAUDE.md es adecuado para instrucciones persistentes que los miembros del proyecto pueden revisar y gestionar mediante control de versiones.

• Comandos estándar de compilación y pruebas
• Explicación fundamental de la estructura del repositorio
• Áreas que el equipo ha acordado no modificar
• Procedimientos de validación específicos del proyecto
• Reglas difíciles de deducir mediante herramientas comunes

En cambio, la siguiente información resulta más adecuada para la memoria automática o el estado de la sesión.

• Preferencias personalizadas descubiertas durante tareas repetitivas
• Rutas de exploración útiles en trabajos recientes
• Características temporales del entorno de desarrollo
• Progreso de la sesión actual

No debe asumirse que la memoria automática es siempre exacta o permanente. Debe ser posible modificar o eliminar los elementos obsoletos, y no debe utilizarse como único repositorio de las políticas de seguridad ni de los contratos públicos.

6. Prioriza los materiales de referencia ejecutables sobre los documentos explicativos

Las especificaciones en lenguaje natural son útiles para explicar la intención, pero pueden no representar por completo el comportamiento real. Siempre que sea posible, proporciona también los siguientes materiales.

• Implementaciones existentes similares al código actual
• Pruebas unitarias y de integración
• Esquemas de API y definiciones de tipos
• HTML real o entregables de diseño
• Archivos de migración de bases de datos
• Datos de ejemplo de entrada y salida
• Rúbricas y criterios de evaluación automática

También pueden surgir conflictos entre los materiales de referencia, por lo que es necesario especificar su prioridad. Por ejemplo, se puede determinar que las pruebas de contrato son el criterio autorizado para la API pública y que el README es material explicativo.

Plantilla práctica para estructurar el contexto

La siguiente estructura es un ejemplo de cómo organizar de forma concisa la información necesaria para una tarea de programación.

Objetivo
- Añadir una API de cancelación de pagos.

Criterios de éxito
- Reutilizar la capa de servicio de pagos existente.
- Aunque haya solicitudes duplicadas, la cancelación solo se realiza una vez.
- Las pruebas de contrato pertinentes se superan.

Restricciones estrictas
- No modificar el esquema de respuesta público.
- No acceder a datos de producción.

Materiales de referencia
- src/payments/capture.ts
- tests/contracts/payment-cancel.test.ts
- openapi/payments.yaml

Principios de decisión
- Seguir el tratamiento de errores y las convenciones de nombres del código de pagos circundante.
- Si existe alguna suposición insegura, preguntar antes de implementar.

Validación
- Pruebas unitarias correspondientes
- Pruebas de contrato
- Comprobación de tipos

Este formato no enumera de antemano todas las situaciones. En su lugar, separa el objetivo, las condiciones de éxito, los límites invariables, los materiales autorizados y los métodos de validación.

Procedimiento para depurar el contexto existente

Paso 1: enumera las fuentes de todas las instrucciones

Revisa conjuntamente el prompt del sistema, CLAUDE.md, los Skills, la memoria automática, las descripciones de herramientas y la configuración de CI. Si solo se examina un documento, resulta difícil detectar los conflictos reales.

Paso 2: asigna una clasificación a cada instrucción

• Obligatoria por motivos de seguridad o legales
• Obligatoria según el contrato del producto
• Práctica persistente del equipo
• Explicación necesaria únicamente para una herramienta concreta
• Regla temporal para evitar errores de modelos anteriores
• Regla cuyo fundamento actualmente no está claro

Paso 3: busca duplicaciones y conflictos

Agrupa las frases que expresen de forma diferente el mismo comportamiento. Revisa con prioridad expresiones como siempre, nunca, obligatoriamente y no hagas.

Paso 4: traslada las reglas a pruebas o permisos

Los elementos cuya validación automática sea más fiable que una advertencia en lenguaje natural deben trasladarse a las siguientes capas.

• Pruebas y linters
• Sistemas de tipos y esquemas
• Herramientas con privilegios mínimos
• Procedimientos de aprobación
• Sandboxes
• Políticas de CI

Paso 5: evalúa mediante tareas reales

No basta con medir la longitud del prompt. Hay que comparar los siguientes indicadores en un conjunto representativo de tareas.

• Tasa de éxito y tasa de superación de pruebas
• Número de archivos modificados innecesariamente
• Número de correcciones del usuario
• Tasa de fallos en las llamadas a herramientas
• Tiempo y tokens necesarios hasta la finalización
• Existencia de infracciones de las políticas de seguridad

Paso 6: corrige únicamente la causa del fallo y de forma mínima

Cuando se produce un fallo, no hay que añadir de inmediato una nueva regla de prohibición. Primero debe determinarse si la causa es un objetivo ambiguo, la falta de materiales de referencia o un esquema de herramientas incorrecto.

Instrucciones que no deben eliminarse

La simplificación no consiste en eliminar indiscriminadamente. Si la respuesta a cualquiera de las siguientes preguntas es sí, la instrucción debe mantenerse o trasladarse a un control más estricto.

• ¿Su incumplimiento puede provocar pérdida de datos o daños económicos?
• ¿Está relacionada con obligaciones legales, de privacidad o de licencias?
• ¿Es una política de la organización que el modelo no puede conocer únicamente a partir del código?
• ¿Determina la compatibilidad de una API pública o de un formato de datos?
• ¿Se necesita la aprobación de una persona antes de ejecutar la tarea?
• ¿Es difícil detectar por completo el incumplimiento únicamente mediante pruebas automáticas?

Patrones de fallo habituales

Añadir una nueva regla después de cada fallo

Si un solo error se generaliza y se convierte en una regla permanente, se acumulan excepciones y conflictos. Primero hay que añadir un caso de evaluación y comprobar si se trata de un fallo recurrente.

Utilizar ejemplos largos prácticamente como plantillas

Si un ejemplo es demasiado concreto, el modelo puede darle prioridad sobre el código base actual. Los ejemplos deben limitarse al tamaño mínimo necesario para explicar el principio.

Conservar íntegros todos los registros

Las salidas de las herramientas y los registros de compilación ocupan rápidamente el contexto. Es preferible conservar de forma estructurada únicamente la causa del fallo, el stack pertinente y el estado modificado.

Utilizar la memoria automática como repositorio de políticas

La memoria automática es práctica, pero sus sistemas de revisión, despliegue y auditoría pueden ser débiles. Las políticas obligatorias de la organización deben almacenarse en instrucciones bajo control de versiones o en una jerarquía de permisos.

Evaluar la reducción del contexto únicamente como ahorro de tokens

Un contexto corto no siempre es mejor. Si se eliminan pruebas, reglas de seguridad o especificaciones necesarias, el resultado empeora. El objetivo no es el mínimo número de tokens, sino el mínimo número de tokens de alta señal.

Lista de comprobación final

• ¿Están separados el objetivo y los criterios de éxito de la solicitud actual?
• ¿Se distinguen las reglas de seguridad de las preferencias de estilo?
• ¿La misma instrucción no está duplicada en varios lugares?
• ¿El esquema de la herramienta explica cómo utilizarla sin necesidad de ejemplos largos?
• ¿Es posible buscar los archivos pertinentes cuando sean necesarios?
• ¿Existe una forma de eliminar la memoria y los registros de ejecución obsoletos?
• ¿Es posible imponer las reglas en lenguaje natural mediante pruebas o permisos?
• ¿Está clara la prioridad entre los materiales de referencia?
• ¿Existen tareas de evaluación para comparar el antes y el después de los cambios en las instrucciones?

Conclusión

La ingeniería de contexto para modelos Claude de alto rendimiento no es una técnica para reducir instrucciones de forma indiscriminada. Es un diseño de la información que aclara el objetivo, los límites de seguridad y los fundamentos que el modelo necesita para juzgar la tarea actual, y elimina la información irrelevante y las reglas contradictorias.

El principio más práctico puede resumirse del siguiente modo.

Impón estrictamente la seguridad y los contratos, deja el estilo en manos del contexto, proporciona la información cuando sea necesaria y valida los resultados mediante pruebas ejecutables.