System prompts en coding agents: depura mejor en 2026

TL;DR

Los system prompts y modelos internos que usan Claude Code, Codex y otros coding agents explican por qué dos herramientas dan resultados distintos sobre el mismo código. Leer esos prompts (cuando son públicos o filtrados) ayuda a separar problemas de configuración, modelo y flujo, y a comparar coste con criterio. En este artículo verás cómo localizarlos, qué mirar y cómo convertirlos en una check-list propia para auditar tu agente antes de echarle la culpa al modelo.

El problema: dos coding agents, el mismo bug, resultados opuestos

Tienes una función rota. La pegas en Claude Code y te propone un fix razonable. La pegas en Codex con casi el mismo prompt y te devuelve algo totalmente distinto, a veces mejor, a veces peor. Si solo miras el output, la conclusión fácil es "uno es mejor que el otro". La conclusión útil es otra: cada agente tiene un system prompt, una temperatura, una ventana de contexto y un set de tools que lo condicionan antes de que tú escribas nada.

Sin entender esa capa, todas las comparativas son ruido. Y peor, cuando el agente falla en producción no sabes si el culpable es el modelo, tu prompt de usuario, una skill mal escrita o una regla interna que tú no ves. Repos como x1xhlol/system-prompts-and-models-of-ai-tools (más de 136.000 estrellas a fecha de mayo de 2026) están publicando los prompts internos de Claude Code, Cursor, Codex, Devin, v0, Windsurf y otros. Lo que antes era opaco hoy es revisable, y eso cambia cómo deberías evaluar tu stack.

¿Qué es un system prompt en un coding agent?

Un system prompt es la instrucción base que el agente envía al modelo antes de tu mensaje. Define el rol ("eres un ingeniero senior"), las herramientas disponibles, el estilo de respuesta, las reglas de seguridad y, en muchos casos, cómo debe estructurar el plan antes de escribir código.

En un coding agent el system prompt suele incluir cuatro bloques:

• Identidad y objetivos: tono, formato de salida, prioridades (correctness, brevedad, etc.).
• Tool definitions: qué puede hacer (read, edit, bash, web fetch) y con qué restricciones.
• Reglas operativas: cuándo pedir confirmación, qué no tocar, cómo manejar errores.
• Contexto del entorno: sistema operativo, versión, fecha, repositorio.

El modelo subyacente (Claude Opus 4.7, GPT-5.5, Gemini 2.5, etc.) cambia el comportamiento, pero el system prompt define el carril. Cambiar de modelo sin cambiar el system prompt es como cambiar el motor del coche sin tocar la dirección.

Por qué leer el system prompt cambia tu forma de depurar

Cuando un agente "alucina" un import o usa una librería que no existe, la primera reacción es culpar al modelo. En la práctica, el problema suele estar antes:

• El system prompt no obliga al agente a verificar imports contra el repo.
• La regla de "no inventes APIs" está, pero el agente la ignora porque hay otra regla con prioridad más alta (ej: "responde rápido").
• El modelo no tiene acceso a la tool de búsqueda en archivos por defecto.

Si lees el prompt y entiendes la jerarquía de reglas, puedes ajustar tu propio CLAUDE.md, AGENTS.md o configuración para corregir el comportamiento sin esperar a una nueva versión del modelo. En equipos de producto, esto se traduce en menos sesiones perdidas y menos pull requests con código que no compila.

Cómo localizar y comparar el system prompt de tu agente

No todos los agentes publican su prompt oficialmente, pero hay tres rutas razonables:

1. Documentación oficial y release notes

Anthropic publica fragmentos de su system prompt para Claude Code en la documentación. OpenAI hace lo mismo con Codex CLI en sus release notes. Empieza siempre por la fuente oficial: la versión es la correcta y no hay riesgo de leer un prompt obsoleto.

2. Repositorios comunitarios de prompts filtrados

Repos como x1xhlol/system-prompts-and-models-of-ai-tools recopilan prompts internos extraídos por usuarios. Útil para comparar herramientas, pero verifica la fecha del último update y la versión a la que corresponde el prompt antes de basar decisiones en él.

3. Inspección local cuando el agente lo permite

En Claude Code puedes ver parte del system prompt activo mirando los archivos cargados (CLAUDE.md, skills, hooks). En Codex CLI hay flags de debug que muestran las instrucciones que se envían al modelo. No verás el prompt completo de Anthropic u OpenAI, pero sí la capa que tú añades, que es la que de verdad puedes cambiar.

Agente	Modelo por defecto (mayo 2026)	Prompt visible	Personalización
Claude Code	Claude Opus 4.7	Parcial (docs + CLAUDE.md)	Alta (skills, hooks, MCP)
Codex CLI	GPT-5.5	Parcial (release notes + AGENTS.md)	Media-alta
Cursor	Configurable	Filtrado en repos comunitarios	Alta (rules, MCP)
Gemini CLI	Gemini 2.5 Pro	Parcial (GEMINI.md)	Media

Caso real: por qué un mismo CLAUDE.md no rinde igual en Opus que en Sonnet

En un proyecto interno cambié el modelo de Claude Sonnet 4.6 a Opus 4.7 esperando una mejora directa. Los primeros días el agente parecía menos disciplinado: se saltaba el paso de "lee el archivo antes de editarlo" que tengo en mi CLAUDE.md. Mi primera sospecha fue que Opus "razona demasiado" y se confía. La causa real era otra: Opus pondera distinto las reglas largas. Mi CLAUDE.md tenía la regla crítica enterrada en la línea 80, y el modelo le daba menos peso.

La corrección fue mover la regla a las primeras 20 líneas y reformularla como imperativa corta. El comportamiento volvió a ser el esperado. Sin entender que el system prompt y el CLAUDE.md se concatenan y compiten por atención, habría descartado Opus por "peor para mi flujo". Si te interesa cómo estructurar reglas operativas en un CLAUDE.md, escribí antes sobre memoria, MCPs y mapa de repo en Claude Code.

En Producción

Auditar prompts no es un ejercicio académico. En un entorno de equipo conviene tratarlo como infraestructura:

• Versiona tu CLAUDE.md y AGENTS.md en el repo. Cualquier cambio debe pasar por pull request, igual que el código.
• Mide el impacto: cuando ajustes una regla, repite 3-5 tareas representativas (un bugfix pequeño, un refactor acotado, un cambio con tests) y compara salidas. Si te interesa el método, lo desarrollé en cómo leer benchmarks de coding agents sin caer en el hype.
• Vigila el coste: prompts largos consumen tokens en cada turno. Un CLAUDE.md de 600 líneas puede sumar 10-15 € extra al mes en una cuenta activa de Claude Code, y suele aportar menos que una versión de 150 líneas bien priorizadas.
• Separa reglas globales de reglas de proyecto: las globales viven en ~/.claude/CLAUDE.md, las de proyecto en el repo. Mezclar ambas hace imposible auditar quién está provocando qué comportamiento.
• Documenta los cambios: cuando tocas una regla operativa importante, anota la fecha y el motivo. En seis meses no te acordarás de por qué pusiste "no toques migrations sin confirmación".

En cuanto a escala: para un dev solo o un equipo de 3-5, esto se gestiona con git y un par de evals manuales. A partir de 10 personas conviene tener un script que ejecute las mismas tareas contra cada combinación de agente + reglas y guarde los resultados, parecido al patrón que usa un harness unificado para varios coding agents.

Errores comunes y cómo depurarlos

• Error: el agente ignora una regla de tu CLAUDE.md → Causa: regla enterrada al final del archivo o en lenguaje ambiguo → Solución: muévela a las primeras 30 líneas, reformúlala como imperativa corta ("NEVER use cat", no "preferimos no usar cat").
• Error: el agente inventa una API que no existe → Causa: no tiene tool de búsqueda activa o el system prompt no exige verificación → Solución: revisa qué tools están habilitadas y añade una regla explícita: "antes de usar una librería, verifica que existe en package.json o requirements.txt". Toqué este patrón en MCP defensivo contra paquetes falsos.
• Error: cambias de modelo y el comportamiento empeora sin razón aparente → Causa: el nuevo modelo pondera distinto tus reglas → Solución: ejecuta tu set de evals corto antes y después, ajusta el orden de reglas en el CLAUDE.md.
• Error: el agente filtra información sensible en los logs → Causa: regla de redacción ausente o débil → Solución: añade una regla explícita y combínala con scanning como el de secret scanning en GitHub MCP.

Preguntas frecuentes

¿Es legal o ético leer system prompts filtrados?

Leer un prompt filtrado para entender cómo funciona tu herramienta es legítimo. Distribuir comercialmente prompts propietarios o usarlos para clonar un producto sí entra en zona gris. Para uso personal de aprendizaje y depuración, los repos comunitarios son una fuente válida.

¿Vale la pena escribir mi propio system prompt desde cero?

No para uso individual. Claude Code, Codex y Cursor traen system prompts maduros que ya cubren cientos de casos. Lo rentable es añadir tu capa: CLAUDE.md, skills, reglas de equipo. Reescribir el prompt completo solo tiene sentido si construyes tu propio harness sobre la API.

¿Cómo sé si una regla nueva en mi CLAUDE.md está funcionando?

Define una tarea reproducible que dependa de esa regla y ejecútala 3-5 veces antes y después del cambio. Si no ves diferencia clara, la regla no está activa o el modelo la ignora; reformúlala o muévela arriba en el archivo.

Cierre

Los coding agents dejaron de ser cajas negras hace meses. Hoy puedes leer sus system prompts, comparar modelos y ajustar tu propia capa de reglas con datos en lugar de intuición. La diferencia entre un equipo que culpa al modelo y otro que mejora su flujo está en si trata la configuración del agente como infraestructura o como detalle del prompt. La práctica concreta cabe en tres pasos: versionar tu CLAUDE.md como código, ejecutar evals cortos cuando cambies algo importante y leer la documentación oficial de tu agente cada vez que salga una versión nueva.

¿Has auditado alguna vez el system prompt de tu coding agent y has cambiado algo basándote en ello? Cuéntamelo en Twitter @sergiomarquezp_. En el siguiente artículo voy a entrar en cómo construir un set de evals minimalista para validar cambios de modelo o de reglas sin montar infraestructura compleja.