Nuevas reglas de ingeniería de contexto para los modelos Claude 5

• En Claude Opus 5 y Claude Fable 5, se redujo en más de 80% el system prompt de Claude Code sin una caída medible de rendimiento en evaluaciones de programación
• Las reglas detalladas que antes evitaban los peores casos pueden entrar en conflicto entre el system prompt, Skills, CLAUDE.md y las solicitudes del usuario, así que en los modelos más recientes es mejor permitirles usar el contexto circundante y su propio criterio
• En lugar de dar por adelantado todas las instrucciones y ejemplos de herramientas, se aplica divulgación progresiva (progressive disclosure) con interfaces expresivas y cargando información y herramientas cuando se necesitan
• Se recomienda que en CLAUDE.md solo se registren de forma concisa las trampas del repositorio, que las instrucciones largas se separen en Skills, y que se aprovechen materiales de referencia ricos como especificaciones, suites de pruebas, maquetas HTML, código y rúbricas de evaluación
• Con /doctor y claude doctor se puede ajustar el tamaño de Skills y CLAUDE.md, y el contexto de los modelos recientes debe organizarse para reducir la repetición y las restricciones excesivas y encontrar la información relevante cuando haga falta

---

Ingeniería de contexto más allá del prompt

• Cuando Claude procesa mensajes, el prompt del usuario es solo una parte del contexto total, y el resto se ensambla desde el system prompt, Skills, CLAUDE.md, memoria y más
• La ingeniería de contexto se aplica en común a múltiples solicitudes, por lo que es más difícil de escribir con la misma especificidad que un prompt individual, pero influye mucho en los resultados de Claude Code y de agentes propios
• Hay que diseñar prompts e instrucciones generales sin conocer de antemano la solicitud del usuario, y conforme las capacidades de Claude avanzan, también cambia la forma adecuada de hacerlo
• En Claude Opus 5 y Claude Fable 5, incluso al eliminar más de 80% del system prompt de Claude Code no hubo una caída medible de rendimiento en evaluaciones de programación
• Estas buenas prácticas ya están reflejadas en claude doctor, y en Claude Code se puede usar /doctor para ajustar Skills y CLAUDE.md a un tamaño adecuado

Liberar al modelo de restricciones excesivas

• Claude Code antes estaba sometido a demasiadas restricciones no solo en el system prompt, sino también en CLAUDE.md y Skills
  • En una misma solicitud podían entrar en conflicto instrucciones como “deja la documentación adecuada” y “no agregues comentarios” a través del system prompt, Skills y la solicitud del usuario
  • Aunque Claude pueda interpretar la intención del usuario, las instrucciones superpuestas o conflictivas hacen que tenga que pensar con más cuidado antes de decidir cómo actuar
• Antes estas restricciones eran necesarias para evitar los peores casos, pero los modelos actuales permiten eliminar varias de ellas y aprovechar el contexto circundante y su propio criterio
• También han aumentado las herramientas que Claude Code puede usar
  • Antes, CLAUDE.md era el repositorio principal de memoria, información e instrucciones
  • Ahora puede cargar y compartir contexto entre sesiones mediante memoria, artifacts y Skills

Usar juicio basado en contexto en lugar de reglas fijas

• En las primeras versiones de Claude Code se incluyeron instrucciones fuertes, no siempre adecuadas, para evitar peores casos como borrar archivos
• El system prompt anterior exigía no escribir comentarios en el código por defecto, prohibía docstrings de varios párrafos o comentarios multilínea, y pedía no crear documentos de planificación, toma de decisiones o análisis si el usuario no lo solicitaba
• Estas reglas pueden ser inapropiadas para algunas solicitudes
  • El usuario puede tener preferencias distintas sobre documentación
  • Algunas partes específicas de código complejo pueden necesitar comentarios multilínea
• En modelos antiguos este tipo de compromiso era necesario porque sin barandales de protección solían escribir comentarios incorrectos, pero los modelos actuales manejan mejor estas decisiones aun sin reglas explícitas
• El nuevo system prompt usa instrucciones basadas en contexto como “escribe código que se lea como el código circundante y alinea la densidad de comentarios, los nombres y los modismos”

Diseñar interfaces expresivas en vez de depender de ejemplos

• Antes, la regla clave para usar herramientas era darle a Claude ejemplos de uso
• En los modelos recientes, los ejemplos pueden limitar el espacio de exploración a un área específica, así que conviene priorizar la expresividad de la interfaz y de los parámetros de herramientas, scripts y archivos
• Si el status de una herramienta Todo se define como el enum pending, in_progress, completed, eso sugiere naturalmente cómo usarla
• La instrucción de mantener solo un elemento en in_progress concreta el comportamiento solicitado a nivel de interfaz

Divulgación progresiva: abrir la información cuando hace falta

• Cuando Claude Code estaba más enfocado en programar, se incluían en detalle en el system prompt los métodos de revisión y validación de código
• Esa información no siempre era necesaria, pero sí era importante en ciertas tareas
• Ahora se puede usar divulgación progresiva para cargar el contexto adecuado en el momento necesario
  • Mover las guías de validación y revisión de código a Skills separadas para que Claude Code las invoque de forma selectiva
  • Algunas herramientas se cargan de manera diferida, y el agente debe buscar su definición completa con ToolSearch antes de usarlas
  • Es posible ofrecer muchas herramientas como la herramienta Task sin ocupar contexto antes de que realmente se necesiten
• No hace falta convertir CLAUDE.md y Skill.md en un repositorio central de todas las prácticas posibles
• En su lugar, pueden organizarse como un árbol de archivos que se carga cuando hace falta; este enfoque también se trata en un arnés de flujos de trabajo dinámicos para cada tarea

Integrar instrucciones repetidas en descripciones simples de herramientas

• En modelos anteriores de Claude a veces era necesario repetir la misma instrucción, y en ocasiones seguían mejor las instrucciones ubicadas al final del contexto que las del inicio
• Por eso se incluían las mismas instrucciones o ejemplos de uso de herramientas tanto en el cuerpo del system prompt como en la descripción de la herramienta
• En los modelos recientes se pueden eliminar los ejemplos repetidos y dejar el uso de la herramienta solo en su descripción

De CLAUDE.md a memoria automática

• Antes se recomendaba que el usuario guardara directamente la memoria de Claude usando la escritura automática de información en CLAUDE.md con el atajo #
• Ahora Claude memoriza automáticamente la información relevante sobre tareas y usuarios

Materiales de referencia ricos más allá de especificaciones simples

• En modo de planificación, Claude Code dependía mucho de archivos de plan en Markdown para volver a consultarlos cuando hiciera falta, y en proyectos de largo plazo a veces también se guardaban especificaciones dentro del codebase
• Claude actual puede manejar materiales de referencia en formatos más complejos
  • Artifacts HTML generados con la nueva función de artifacts
  • Código, como funciones para portar desde otros codebases
  • Especificaciones expresadas como suites de pruebas detalladas
• Una rúbrica es otro formato de referencia que permite a Claude intentar y validar gustos o criterios de calidad de un dominio específico
  • Se pueden definir criterios sobre qué constituye un buen diseño de API
  • Mediante flujos de trabajo dinámicos se puede crear un agente de validación que use esa rúbrica

Rol de cada componente del contexto

• System prompt

  • Está estrechamente ligado al contexto del producto y le dice a Claude en qué producto está y qué trabajo realiza
  • Los usuarios de Claude Code casi nunca lo modifican, pero si construyes tu propio arnés de agente, es un área a la que conviene dedicar mucho tiempo

• CLAUDE.md

  • Debe mantenerse ligero y describir brevemente para qué sirve el repositorio, pero la mayoría de los tokens deberían usarse para registrar trampas o riesgos del codebase
  • Vale la pena registrar reglas del repositorio como que todos los tipos deben estar en un solo archivo
  • Conviene evitar información obvia que Claude pueda deducir revisando el sistema de archivos o el repositorio
  • Si hay varias instrucciones únicas para validar tareas, se puede crear una Skill de validación y referenciarla desde CLAUDE.md para aplicar divulgación progresiva

• Skills

  • Deben componerse como guías ligeras que ayuden a Claude a encontrar información cuando la necesite
  • Salvo en áreas muy críticas, conviene evitar restricciones excesivas
  • Las Skills largas es mejor dividirlas en varios archivos para que se carguen progresivamente
  • Son especialmente útiles para capturar perspectivas, conocimiento y buenas prácticas específicas de una persona, equipo o producto

• Materiales de referencia

  • Al mencionar archivos con @, Claude puede revisar detalles relacionados con el plan actual
  • Archivos de especificación, maquetas e incluso el codebase completo pueden ser materiales de referencia
  • Como el código ofrece instrucciones claras y fieles en un lenguaje que Claude conoce bien, por lo general conviene priorizar archivos en forma de código
  • Las maquetas de diseño en HTML suelen dar mejores resultados que descripciones de diseño o capturas de pantalla

Simplificar el contexto existente

• Hay que simplificar el contexto eliminando reglas, repeticiones e información innecesaria del system prompt, Skills y CLAUDE.md
• El comando claude doctor ayuda automáticamente con este trabajo de simplificación
• Para más sobre cómo escribir prompts para modelos avanzados, se puede consultar la guía de campo de Claude Fable