Guía completa para escribir System Prompts para Agentes — Lecciones de aplicar ingeniería inversa a Claude Code

Descompilé el system prompt de Claude Code, estudié el código fuente de DeepAgents y construí mi propio agente de IA desde cero. La mayoría de las guías de prompts son puro humo.

Hay un delirio colectivo ocurriendo en la IA ahora mismo.

Todos los tutoriales te dicen que escribas system prompts como si estuvieras conjurando un hechizo — solo encuentra el encantamiento correcto y el modelo obedecerá. "Eres un ingeniero senior EXTREMADAMENTE TALENTOSO con 20 años de experiencia..." ¿Te suena familiar?

He pasado los últimos meses construyendo VibeCom, un asesor de startups con IA que ejecuta investigaciones de mercado profundas y genera análisis a nivel de Venture Capital. En el camino, le hice ingeniería inversa al system prompt de Claude Code, leí el código fuente del middleware de DeepAgents y quemé más créditos de API de los que me gustaría admitir. ¿La mayor lección? La mayoría de las cosas que la gente cree que importan sobre los system prompts, en realidad no importan. Y de las cosas que realmente importan, casi nadie habla.

Este post es el manual de juego completo — no un resumen de 5 minutos, sino todo lo que ojalá alguien me hubiera dicho antes de empezar. Prepárate un café.

1. Filosofía de Diseño: Confía en el Modelo

"Un agente es un modelo. No un framework. No una cadena de prompts." — shareAI-lab/learn-claude-code

Esta idea lo cambió todo para mí. El LLM ya sabe cómo razonar, planificar y ejecutar. Tu system prompt no le está enseñando a pensar — está configurando el entorno en el que va a trabajar.

Piénsalo como si contrataras a un ingeniero senior. No le entregas una lista de 20 pasos para cada tarea. Le dices: esto es lo que somos, estos son los límites, así es como se ve un buen trabajo. Y luego te apartas de su camino.

Tu system prompt tiene exactamente cuatro trabajos:

Dile quién es — rol e identidad
Dile dónde están los muros — restricciones de seguridad
Dile cómo se ve un buen trabajo — estándares de calidad
Dale herramientas — capacidades y conocimiento

Eso es todo. Todo lo demás es ruido.

La Mentalidad de Arnés (Harness)

Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions

Tu system prompt es el manual de operaciones del harness. No estás diseñando un pipeline rígido — estás diseñando un entorno donde el modelo puede hacer su mejor trabajo de forma autónoma.

No escribas tu system prompt como un diagrama de flujo. El modelo decidirá el orden de ejecución por sí mismo.

2. Estructura del Prompt y Orden de las Secciones

El Layout Recomendado (Ingeniería Inversa de Claude Code v2.0.14)

┌─────────────────────────────────────────────┐
│ 1. Identity                                  │  ← Read first, anchors behavior
│ 2. Security & Safety                         │  ← IMPORTANT markers, non-negotiable
│ 3. Tone & Style                              │  ← Controls output format
│ 4. Core Workflow                             │  ← How to do the work
│ 5. Tool Usage Policy                         │  ← Tool selection priorities
│ 6. Domain Knowledge                          │  ← On-demand, not pre-loaded
│ 7. Environment Info                          │  ← Runtime context, dynamically injected
│ 8. Reminders                                 │  ← Re-state critical rules
├─────────────────────────────────────────────┤
│ [Tool Definitions — system-injected]         │  ← Not editable, usually very long
├─────────────────────────────────────────────┤
│ [User Message]                               │
└─────────────────────────────────────────────┘

Por Qué Importa Este Orden

Los LLMs tienen una curva de atención en forma de U — prestan la mayor atención al principio y al final de tu prompt, y se pierden en el medio. Este es el efecto "Lost in the Middle" (Perdido en el Medio), y está bien documentado.

Identidad + Seguridad arriba: El modelo establece su rol y límites primero (efecto de primacía).
Flujo de Trabajo Central (Core Workflow) en el medio-superior: Tu sección más importante — cómo hace su trabajo el agente.
Las Definiciones de Herramientas (Tools) son inyectadas por el sistema después de tu prompt: Las definiciones de herramientas de Claude Code consumen ~11,438 tokens. Esto significa que tu contenido personalizado en realidad termina más cerca del principio de lo que esperarías — lo cual ayuda a que se cumplan las instrucciones.
Recordatorios al final: Aprovecha el sesgo de recencia para reforzar las reglas críticas.

3. Escribiendo Cada Sección

3.1 Identidad — ¿Quién es este Agente?

Objetivo: Anclar el rol del modelo en 1-3 oraciones.

You are Claude Code, Anthropic's official CLI for Claude.
You are an interactive agent that helps users with software engineering tasks.

Directrices:

Mantenlo conciso — máximo 1-3 oraciones.
Nombra el rol explícitamente (ayuda al modelo a distinguir contextos).
Indica la responsabilidad principal ("ayuda con X"), no un vago "eres un asistente útil".
Menciona el SDK/plataforma si aplica ("construido sobre el Claude Agent SDK de Anthropic").

Antipatrones:

"Eres un asistente de IA útil, inofensivo y honesto" — demasiado genérico, no ancla un rol.
Un párrafo entero de historia de fondo y lore — desperdicia tokens, el modelo no necesita desarrollo de personaje.

3.2 Seguridad y Protección — Los Límites Estrictos

Objetivo: Establecer restricciones de comportamiento inquebrantables.

IMPORTANT: Assist with defensive security tasks only.
Refuse to create, modify, or improve code that may be used maliciously.
IMPORTANT: You must NEVER generate or guess URLs for the user.

Directrices:

Usa el prefijo IMPORTANT: — el entrenamiento de jerarquía de instrucciones de Claude le da un peso extra a esto.
Usa lenguaje absoluto: NEVER, MUST NOT, Refuse to.
Indica tanto lo que está permitido COMO lo que está prohibido (las restricciones bidireccionales son más claras).
Colócalo en la parte superior, no enterrado en el medio.
Repite las reglas de seguridad críticas al final — Claude Code hace exactamente esto.

¿Por qué repetir? Efecto de primacía (principio) + Efecto de recencia (final) = doble refuerzo. La declaración de seguridad de Claude Code aparece tanto al principio como al final del prompt. No porque los ingenieros fueran olvidadizos — sino porque entienden la curva de atención en forma de U.

3.3 Tono y Estilo — Controlando el Output

Objetivo: Controlar el formato de salida y la voz.

## Tone and style

- Your responses should be short and concise.
- Only use emojis if the user explicitly requests it.
- Use Github-flavored markdown for formatting.
- NEVER create files unless absolutely necessary.

Directrices:

Enumera comportamientos específicos, no un vago "sé profesional".
Cada regla debe ser comprobable como verdadera/falsa ("corto y conciso" vs. "trata de ser breve").
Incluye requisitos de formato de salida (¿markdown? ¿JSON? ¿texto plano?).
Incluye lo que NO se debe hacer — muchos problemas de estilo se tratan de prohibir comportamientos.

La joya de Claude Code — Objetividad Profesional:

Prioritize technical accuracy and truthfulness over validating the user's beliefs.
Focus on facts and problem-solving, providing direct, objective technical info
without any unnecessary superlatives, praise, or emotional validation.

Este párrafo es crucial: bloquea la tendencia a la adulación (sycophancy) del modelo. Si tu agente necesita dar juicios objetivos (revisión de código, evaluación de ideas, decisiones de arquitectura), necesitas absolutamente una cláusula similar.

3.4 Flujo de Trabajo Central (Core Workflow) — La Sección Más Importante

Objetivo: Enseñarle al modelo cómo trabajar — metodología, no procedimientos rígidos.

Esta es la sección más difícil de escribir bien, y la de mayor impacto cuando lo logras.

El principio fundamental: da principios, no procedimientos.

Dile al LLM cómo se ve un buen resultado y por qué es bueno — deja que él descubra cómo llegar allí. Evita prescribir recuentos exactos de campos, secuencias de pasos o formatos, a menos que el output vaya a ser consumido por máquinas más adelante en el proceso.

El enfoque de Claude Code:

## Doing tasks

The user will primarily request software engineering tasks.
For these tasks the following steps are recommended:

- Use the TodoWrite tool to plan the task if required

Nota la palabra "recommended" (recomendado) — no "debes seguir estos pasos exactos". Esa simple elección de palabras le da al modelo espacio para adaptarse.

Una buena definición de flujo de trabajo:

1. Understand first — read existing code before modifying it
2. Plan first — break complex tasks into steps before executing
3. Minimal changes — only change what's necessary, don't "refactor while you're in there"
4. Verify — confirm your changes work (run tests, lint, etc.)

Cada regla tiene un "por qué" implícito — el modelo puede entender la intención y generalizar a nuevos escenarios.

Antipatrones:

Un procedimiento rígido de 20 pasos — el modelo ejecutará mecánicamente y se congelará ante inputs inesperados.
"Primero haz A, luego haz B, luego haz C" — eso es una cadena de prompts (prompt chain), no un prompt de agente.
Guiar en exceso cosas en las que el LLM ya es bueno — desperdicia tokens.

Aprendí esto a las malas con VibeCom. Las primeras versiones tenían un flujo de trabajo de investigación de 10 pasos. El modelo ejecutaba obedientemente los 10 pasos incluso cuando el paso 3 ya había respondido la pregunta del usuario. Cuando cambié a principios ("investiga hasta que tengas suficiente evidencia, luego sintetiza"), la calidad subió y los costos de tokens bajaron.

La excepción: Cuando el output es consumido por máquinas más adelante (comunicación entre agentes, formatos de respuesta de API), sí debes definir formatos estrictos. Los principios son para el comportamiento; los esquemas (schemas) son para las interfaces.

3.5 Política de Uso de Herramientas — Resolviendo la Ambigüedad

Objetivo: Cuando múltiples herramientas pueden hacer lo mismo, dile al modelo cuál preferir.

## Tool usage policy

- Use specialized tools instead of bash commands:
  - Read for reading files instead of cat/head/tail
  - Edit for editing instead of sed/awk
  - Grep for searching instead of grep/rg
- You can call multiple tools in a single response. If independent, call in parallel.
- Use the Task tool for file search to reduce context usage.

Directrices:

Usa "en lugar de" (instead of) para expresar prioridad (A en lugar de B).
Explica por qué preferir ciertas herramientas ("proporciona una mejor experiencia de usuario", "reduce el uso de contexto").
Define la estrategia de paralelismo (independientes → paralelo, dependientes → secuencial).
Enumera las restricciones de seguridad para el uso de herramientas (validación de rutas, verificación de permisos).

La relación crucial entre herramientas y prompts:

Las definiciones de herramientas (Tools) típicamente son inyectadas por el sistema y no puedes editarlas directamente. Las definiciones de herramientas de Claude Code son de ~11,438 tokens. Esto significa:

No repitas información que ya está en las definiciones de las herramientas.
Usa el system prompt para orientación estratégica: cuándo usar cada herramienta, por qué preferir una sobre otra, orden de prioridad.
La calidad de la definición de la herramienta impacta directamente en la efectividad del agente — si estás construyendo tu propio agente, invierte tiempo en escribir descripciones de herramientas excelentes.

3.6 Conocimiento del Dominio — Carga Bajo Demanda, No por Adelantado

Objetivo: Proporcionar conocimiento especializado del que podrían carecer los datos de entrenamiento del modelo.

El principio clave: divulgación progresiva, no vertederos de conocimiento (knowledge dumps).

❌ Paste all 200 API endpoints into the system prompt → token explosion
✅ Give the model a tool to look things up → "Load knowledge when you need it"

Esta estrategia es compartida por el sistema de Skills de Claude Code y el middleware de Divulgación Progresiva de DeepAgents. Ambos cargan conocimiento bajo demanda a través de llamadas a herramientas (tool calls) en lugar de precargar todo.

Enfoques de implementación:

Pon punteros en el system prompt: "Usa la herramienta get_api_docs para recuperar la documentación cuando sea necesario".
Usa CLAUDE.md / AGENTS.md para el contexto del proyecto — se carga en tiempo de ejecución (runtime), no está hardcodeado.
Usa Skills / SKILL.md para el descubrimiento de capacidades — el modelo ve un menú de habilidades disponibles y obtiene las especificaciones completas bajo demanda.

3.7 Información del Entorno — Contexto en Tiempo de Ejecución

Objetivo: Darle al modelo conciencia de su entorno de ejecución.

<env>
Working directory: /Users/fengliu/Desktop/tfm/vibecom
Is directory a git repo: true
Platform: darwin
Today's date: 2026-03-21
</env>
You are powered by the model named Claude Opus 4.6.

Directrices:

Genéralo dinámicamente, nunca lo hardcodees.
Incluye: directorio de trabajo, plataforma, fecha, nombre del modelo, estado de git.
Usa un formato estructurado (etiquetas XML o bloques de código) para facilitar el parsing.
La fecha importa — el modelo necesita saber el "ahora" para juzgar la frescura de la información.

3.8 Recordatorios — El Refuerzo Final

Objetivo: Reafirmar las reglas más críticas al final del prompt.

Claude Code repite su restricción de seguridad y el requisito de TodoWrite en la parte inferior:

IMPORTANT: Assist with defensive security tasks only. [repeated]
IMPORTANT: Always use the TodoWrite tool to plan and track tasks. [repeated]

Directrices:

Solo repite 2-3 de las reglas más críticas — no dupliques todo.
Aprovecha el sesgo de recencia — el modelo recuerda el contenido reciente con más fuerza.
Mejores candidatos: restricciones de seguridad, reglas violadas con mayor frecuencia, recordatorios del flujo de trabajo central.

4. Presupuesto de Tokens y Gestión del Contexto

Referencia de Asignación de Presupuesto

Sección	Tokens Recomendados	Notas
Identidad + Seguridad	200-500	Conciso pero innegociable
Tono y Estilo	300-800	Las reglas deben ser específicas, pero no divagues
Flujo de Trabajo Central	500-2,000	La sección más importante, vale la pena la inversión
Política de Uso de Herramientas	300-1,000	Depende del número de herramientas
Conocimiento del Dominio	0-1,000	Se prefiere la carga bajo demanda
Información del Entorno	100-300	Generado dinámicamente
Recordatorios	100-300	Solo repite lo esencial
Tu total	1,500-6,000
Definiciones de Herramientas (sistema)	5,000-15,000	Fuera de tu control

Curva de Degradación del Contexto

Pruebas de la comunidad (Reddit u/CodeMonke_) han mapeado la degradación de adherencia en el mundo real:

< 80K tokens: La adherencia al prompt se mantiene estable.
80K - 120K tokens: El seguimiento de instrucciones comienza a degradarse.
> 120K tokens: Degradación significativa — el modelo "olvida" las primeras instrucciones.
> 180K tokens: Degradación severa.

Tu ventana de contexto de 200K ≠ 200K de contexto efectivo. Planifica en consecuencia.

Estrategias de mitigación:

Mantén tu system prompt ligero (< 6,000 tokens para tu parte).
Usa la sumarización para comprimir el historial de conversación (DeepAgents se activa a los ~80K caracteres).
Coloca las reglas críticas en ambos extremos del prompt (atención en forma de U).
Inyecta etiquetas <system-reminder> a mitad de la conversación (más sobre esto en la sección 8).

5. Principios de Escritura

5.1 Da Principios, No Procedimientos

❌ "Step 1: Read the file. Step 2: Find the bug. Step 3: Fix it. Step 4: Run tests."
✅ "Always understand existing code before modifying it. Verify your changes work."

Los principios se generalizan. Los procedimientos solo pueden seguirse mecánicamente. Cuando el modelo se encuentra con una situación que no anticipaste, los principios guían la decisión correcta. Los procedimientos no.

Excepción: Cuando el output es consumido por máquinas (comunicación entre agentes, formatos de API), define esquemas estrictos.

5.2 Usa Lenguaje Absoluto para Restricciones Estrictas

Fuerza	Lenguaje	Usar Para
Prohibición absoluta	`NEVER`, `MUST NOT`	Seguridad, operaciones irreversibles
Requisito fuerte	`ALWAYS`, `MUST`	Reglas del flujo de trabajo central
Recomendación	`recommended`, `prefer`	Mejores prácticas con excepciones
Sugerencia	`consider`, `you may`	Optimizaciones opcionales

Ejemplos de Claude Code:

NEVER update the git config — prohibición absoluta
ALWAYS prefer editing an existing file — fuerte, pero existen excepciones
The following steps are recommended — flujo de trabajo sugerido

5.3 Usa Ejemplos en Lugar de Explicaciones

## Code References

When referencing specific functions or pieces of code include
the pattern `file_path:line_number`.

<example>
user: Where are errors from the client handled?
assistant: Clients are marked as failed in the `connectToServer`
function in src/services/process.ts:712.
</example>

Un ejemplo enseña más que 100 palabras de explicación:

Los modelos aprenden patrones a partir de ejemplos de manera más confiable que a partir de descripciones abstractas.
Envuélvelos con etiquetas <example> para separarlos de las reglas.
Proporciona ejemplos tanto positivos ("haz esto") como negativos ("no hagas esto").
Usa ejemplos reales y específicos — no placeholders como "foo/bar".

5.4 Restricciones Bidireccionales

✅ "Use dedicated tools: Read for reading files, Edit for editing files."
✅ "Do NOT use bash for file operations (cat, head, tail, sed, awk)."

Decir solo "haz esto" → el modelo no sabe cuándo NO hacerlo. Decir solo "no hagas esto" → el modelo no conoce la alternativa. Bidireccional → claro y sin ambigüedades.

5.5 Explica el Por Qué, No Solo el Qué

❌ "Don't use git commit --amend."
✅ "Avoid git commit --amend. ONLY use --amend when either
   (1) user explicitly requested amend OR
   (2) adding edits from pre-commit hook.
   Reason: amending may overwrite others' commits."

Explicar el por qué le permite al modelo emitir juicios correctos en casos límite (edge cases). El protocolo de seguridad de git de Claude Code es una clase magistral — cada regla implica su justificación.

5.6 Estructura por Encima de la Prosa

Encabezados Markdown (##, ###) — los modelos reconocen la jerarquía.
Listas con viñetas sobre párrafos — cada regla es comprobable de forma independiente.
Etiquetas XML para contenido especial: <example>, <env>, <system-reminder>.
Tablas para comparaciones y mapeos.
Nunca viertas texto no estructurado — los prompts estructurados superan consistentemente a la prosa en lenguaje natural en las pruebas de adherencia.

6. Antipatrones que Desperdician tus Tokens

Cadenas de Prompts Disfrazadas de Agentes

"First call tool A to get data.
Then call tool B with the result.
Then format the output as JSON.
Then save to file."

Esto no es un prompt de agente — es un script de pipeline. El modelo ejecutará mecánicamente y perderá su capacidad de planificación autónoma.

La solución: Dile al modelo el objetivo y las restricciones. Deja que él decida los pasos.

Ingeniería de Adulación (Flattery Engineering)

"You are an EXTREMELY TALENTED and INCREDIBLY EXPERIENCED
senior software engineer with 20 years of experience..."

Los cumplidos y superlativos no mejoran la calidad del output. El modelo no tiene un ego que alimentar. Ahorra esos 15 tokens para una regla real.

Vertederos de Conocimiento (Knowledge Dumps)

"Here is the complete API documentation for our 200 endpoints..."

Esto devora tu ventana de contexto y acelera la putrefacción del contexto (context rot). Reemplázalo con carga bajo demanda:

"Use the get_api_docs tool to retrieve API documentation when needed."

Repetir Descripciones de Herramientas

Si la definición de la herramienta ya dice "La herramienta Read lee un archivo del sistema de archivos", no lo digas de nuevo en tu system prompt. Solo agrega orientación estratégica que la definición de la herramienta no cubra — cuándo usarla, por qué preferirla, orden de prioridad.

Falta de Manejo de Errores

Sin una guía explícita, los modelos reintentarán llamadas a herramientas fallidas en un bucle infinito. Incluye siempre:

"If a tool call is denied, do not re-attempt the exact same call.
Think about why it was denied and adjust your approach."

Ignorar la Decadencia de la Ventana de Contexto

Ventana de contexto de 200K ≠ 200K de contexto efectivo. Las pruebas en el mundo real muestran que la degradación comienza a los 80K. Necesitas una estrategia de sumarización.

7. Puntos de Inyección y Prioridad

Los Tres Métodos de Personalización de Claude Code

Método	Reemplaza	Ubicación	Mejor Para
Output Styles	Secciones "Tone and style" + "Doing tasks"	Justo antes de las definiciones de herramientas	Cambiar el estilo de interacción
--append-system-prompt	Nada (aditivo)	Después del estilo de salida, antes de las herramientas	Agregar comportamientos específicos
--system-prompt	Todo el system prompt	Mantiene definiciones de herramientas + una línea de identidad	Personalización completa (opción nuclear)

Si usas múltiples: Output Style → Append Prompt → Tool Definitions

Jerarquía de Instrucciones

Claude está entrenado específicamente con una jerarquía de instrucciones:

1. User's explicit instructions (CLAUDE.md, direct requests)  ← Highest priority
2. Custom system prompt additions                               ← High
3. Default system prompt                                        ← Medium
4. Tool definitions                                             ← Reference level

Esto significa:

Las reglas de CLAUDE.md anulan el comportamiento del system prompt por defecto.
Las solicitudes directas del usuario anulan todo.
Tu prompt personalizado anula el prompt por defecto.

Mecanismos de Inyección Dinámica

<system-reminder> — inyectar en cualquier mensaje a mitad de la conversación para recordarle al modelo reglas críticas.
CLAUDE.md / AGENTS.md — cargados en tiempo de ejecución desde archivos, añadidos al system prompt.
Skills / SKILL.md — cargados bajo demanda vía llamadas a herramientas, cero impacto en el system prompt.

8. Inyección a Mitad de Conversación — El Arma Secreta

El system prompt solo aparece una vez, al principio del array de mensajes. Pero los LLMs aceptan el array completo de mensajes (alternando mensajes de usuario / asistente / herramienta) como input, y puedes inyectar prompts en los mensajes del usuario y en los resultados de las herramientas también. Claude Code usa esta técnica intensamente en producción.

Por Qué es Necesario

Luchando contra la putrefacción del contexto (context rot). A medida que las conversaciones se alargan, la adherencia del modelo a las instrucciones del system prompt se degrada (notable a los 80K+ tokens). Inyectar recordatorios a mitad de la conversación = refrescar las reglas a través del sesgo de recencia.

El modelo mental:

System prompt = la constitución (establecida una vez, autoridad a largo plazo)
Recordatorios en mensajes de usuario = memorándums (enviados periódicamente, manteniendo el cumplimiento)

Tres Puntos de Inyección en el Array de Mensajes

Messages Array:
┌─────────────────────────────────────┐
│ System Prompt                       │ ← Appears once, primacy effect
│   (identity, safety, workflow...)   │
├─────────────────────────────────────┤
│ User Message 1                      │
│ Assistant Message 1                 │
│ User Message 2 + <system-reminder>  │ ← Mid-conversation injection
│ Assistant Message 2                 │
│ Tool Result + <system-reminder>     │ ← Can inject into tool results too
│ ...                                 │
│ User Message N + <system-reminder>  │ ← Latest message, strongest recency
└─────────────────────────────────────┘

Ubicación	Ventaja	Desventaja
System prompt	Efecto de primacía, se lee primero	Aparece una vez, se "olvida" en conversaciones largas
Inyección en mensaje de usuario	Sesgo de recencia, refresco periódico	Cada inyección cuesta tokens
Inyección en resultado de herramienta	Punto de inyección más natural	Solo funciona cuando se llaman herramientas

Cómo lo Usa Realmente Claude Code

Requisito previo — declarar las etiquetas en el system prompt:

Tool results and user messages may include <system-reminder> tags.
<system-reminder> tags contain useful information and reminders.
They are automatically added by the system, and bear no direct
relation to the specific tool results or user messages in which they appear.

Este paso es crítico: le dice al modelo que estas etiquetas son inyectadas por el sistema, no palabras del usuario.

Uso 1: Recordatorios de Comportamiento (refresco periódico de reglas)

<system-reminder>
The task tools haven't been used recently. If you're working on tasks
that would benefit from tracking progress, consider using TaskCreate...
</system-reminder>

Claude Code usa esto para recordarle al modelo que planifique con TodoWrite — porque los modelos tienden a "olvidar" planificar y simplemente empiezan a programar.

Uso 2: Cambio de Modo (Modo Planificación)

<system-reminder>
Plan mode is active. The user indicated that they do not want you to
execute yet -- you MUST NOT make any edits, run any non-readonly tools,
or otherwise make any changes to the system.
</system-reminder>

El modo de planificación no está implementado en el system prompt. Es una etiqueta inyectada en el siguiente mensaje del usuario. Esto te permite alternar modos dinámicamente sin modificar el system prompt. Brillante.

Uso 3: Notificaciones de Cambio de Archivos

<system-reminder>
Note: /path/to/file.ts was modified, either by the user or by a linter.
This change was intentional, so make sure to take it into account.
</system-reminder>

Cuando un proceso externo (linter, formateador, edición manual) modifica un archivo, el sistema notifica al modelo vía recordatorio — previniendo decisiones basadas en contenidos de archivos obsoletos.

Uso 4: Contexto Dinámico (fechas, reglas del proyecto)

<system-reminder>
Today's date is 2026-03-21.
Current branch: dev
claudeMd: [CLAUDE.md content injected here]
</system-reminder>

El contexto en tiempo de ejecución (fecha, estado de git, reglas del proyecto) se inyecta a través de mensajes de usuario, no hardcodeado en el system prompt.

Directrices de Escritura para Recordatorios

Envuelve en etiquetas XML (<system-reminder>) — el modelo puede distinguir la inyección del sistema del habla del usuario.
Pre-declara las etiquetas en el system prompt — de lo contrario, el modelo podría intentar responder al recordatorio.
No inyectes en cada mensaje — cada inyección cuesta tokens, inyecta solo cuando sea necesario.
Mantenlo corto — un recordatorio no es un segundo system prompt, solo 1-2 reglas críticas.
No contradigas el system prompt — los recordatorios complementan y refuerzan, no anulan.
Úsalo para alternancia dinámica — modo de planificación, modo de solo lectura, feature flags.

Cuándo Usar System Prompt vs. Recordatorio en Mensaje de Usuario

Escenario	System Prompt	Recordatorio en Mensaje de Usuario
Definición de rol	✅	❌
Restricciones de seguridad	✅ Primera declaración	✅ Repetición periódica
Metodología de flujo de trabajo	✅	❌
Cambio de modo (modo plan)	❌	✅
Notificaciones de cambio de archivos	❌	✅
Fecha / info del entorno	✅ Valor inicial	✅ Valor actualizado
Corrección de comportamiento	❌	✅
Recordatorios de uso de herramientas	✅ Definición de regla	✅ Empujones de ejecución

9. Caché de Prompts — Ahorra 90% en Tokens Repetidos

El prompt caching de Anthropic te permite almacenar en caché el prefijo estático de tu array de mensajes. Cuando las solicitudes posteriores comparten el mismo prefijo, aciertan en la caché (cache hit) — ahorrando dinero y reduciendo la latencia.

Para los agentes, esto importa mucho: estás reenviando el system prompt + las definiciones de herramientas en cada llamada al LLM dentro de una conversación.

Números Clave

Métrica	Valor
Costo de acierto en caché (hit)	10% del precio normal (90% de ahorro)
Costo de escritura en caché	125% del precio normal (25% de prima en la primera escritura)
TTL de caché	5 minutos (expira si no hay solicitudes)
Longitud mínima cacheable	1,024 tokens (Claude 3.5+)
Granularidad de caché	Coincidencia de prefijo — desde el inicio hasta un punto de interrupción marcado
Máximo de puntos de interrupción	4

Cómo Cambia Esto el Diseño de Prompts

Principio fundamental: contenido estático primero, contenido dinámico al final.

✅ Cache-friendly layout:
  System prompt (static)      ← Cache breakpoint 1
  Tool definitions (static)   ← Cache breakpoint 2
  CLAUDE.md / project rules   ← Cache breakpoint 3 (changes occasionally)
  Conversation history         ← Breakpoint 4 for rolling window

❌ Cache-destroying layout:
  System prompt
  DYNAMIC TIMESTAMP            ← Changes every request, everything after = cache miss
  Tool definitions
  Conversation history

La trampa de la que nadie te advierte: Si pones una marca de tiempo dinámica en el medio de tu system prompt, todo lo que viene después se convierte en un fallo de caché (cache miss). En. Cada. Solicitud. Una marca de tiempo en el lugar equivocado y estarás pagando el precio completo por miles de tokens.

Uso de la API

const response = await anthropic.messages.create({
  model: "claude-sonnet-4-6",
  system: [
    {
      type: "text",
      text: "You are a startup advisor...",
      cache_control: { type: "ephemeral" }  // ← marks a cache breakpoint
    }
  ],
  messages: [...]
});

Estrategia de Múltiples Puntos de Interrupción (Breakpoints)

Breakpoint 1: System prompt           ← Almost never changes
Breakpoint 2: Tool definitions         ← Almost never changes
Breakpoint 3: Project rules / CLAUDE.md ← Changes occasionally
Breakpoint 4: First N history messages  ← Rolling window cache

Incluso cuando el historial de conversación cambia, los primeros 3 breakpoints siguen acertando. Una conversación de 10 turnos ahorra aproximadamente 40-60% en costos de tokens de entrada.

Recomendaciones de Diseño

Cero valores dinámicos de alta frecuencia en el system prompt — la fecha está bien (cambia diariamente), las marcas de tiempo precisas no.
Pon el contexto dinámico (estado de git, etc.) en inyecciones de mensajes de usuario — no en el system prompt, o destruirás la caché.
Mantén estables las definiciones de herramientas — no agregues/elimines herramientas dinámicamente en tiempo de ejecución.
Usa una ventana móvil (rolling window) para el historial de conversación — almacena en caché los primeros N mensajes, solo el mensaje más nuevo es un cache miss.

10. El Checklist

Después de escribir tu system prompt, revísalo contra este checklist:

Estructura

¿La identidad está en la parte superior?
¿Las restricciones de seguridad están marcadas con IMPORTANT y repetidas al final?
¿Hay una clara separación de secciones con encabezados?
¿Los ejemplos están envueltos en etiquetas <example>?

Presupuesto de Tokens

¿Tu parte tiene < 6,000 tokens?
¿No estás repitiendo información que ya está en las definiciones de herramientas?
¿El conocimiento del dominio se carga bajo demanda, no precargado?
¿No hay lore verboso ni historia de fondo del personaje?

Calidad de las Reglas

¿Cada regla es comprobable como verdadera/falsa?
¿Las restricciones estrictas usan lenguaje absoluto (NEVER/MUST)?
¿Las sugerencias suaves usan lenguaje de recomendación (recommended/prefer)?
¿Las reglas críticas explican el por qué, no solo el qué?
¿Hay restricciones bidireccionales (haz esto + no hagas aquello)?

Comportamiento del Agente

¿Se dan principios, no procedimientos rígidos paso a paso?
¿Se maneja el escenario de "llamada a herramienta denegada"?
¿Se maneja la estrategia de "obstáculo encontrado" (no reintentar a la fuerza bruta)?
¿Hay una estrategia de gestión de contexto en su lugar (umbral de sumarización)?

Qué NO Hacer

¿Cero adulación o adjetivos superlativos?
¿Cero declaraciones redundantes de "eres una IA útil"?
¿No está escrito como una cadena de prompts (prompt chain)?
¿Cero sobreingeniería (funcionalidades que nadie pidió)?

Si Estuviera Empezando Hoy

Esto es exactamente lo que haría:

Empieza con identidad + seguridad en las primeras 3 líneas. Dos oraciones para quién es el agente. Restricciones estrictas con NEVER/MUST. Repite las reglas de seguridad al final.
Escribe tu flujo de trabajo central como principios, no como pasos. Máximo 4-5 viñetas. Usa "recommended" y "prefer" para reglas suaves, "NEVER" y "MUST" para las estrictas.
Presupuesta 1,500-6,000 tokens para tu parte. Las definiciones de herramientas añadirán 5,000-15,000 más. Si estás por encima de 6K, probablemente estás vertiendo conocimiento que debería cargarse bajo demanda.
Estructura todo. Encabezados Markdown, listas con viñetas, etiquetas XML para ejemplos. Un prompt estructurado supera a la prosa en lenguaje natural siempre.
Incorpora recordatorios a mitad de conversación desde el primer día. Declara <system-reminder> en tu system prompt. Inyecta recordatorios para reglas críticas, cambios de modo y actualizaciones de contexto.
Diseña para la caché. Contenido estático primero, contenido dinámico al final. Nunca pongas valores cambiantes en el cuerpo de tu system prompt.

¿La ironía de todo este trabajo? Los mejores system prompts son cortos. Las instrucciones personalizadas de Claude Code (excluyendo las definiciones de herramientas) son sorprendentemente concisas. Cada línea se gana su lugar.

Solía pensar que la ingeniería de prompts se trataba de encontrar trucos ingeniosos. Ahora creo que se trata de disciplina — decir menos, decirlo con precisión y confiar en que el modelo descubrirá el resto. El modelo es más inteligente que tu prompt. Diseña el entorno, no el comportamiento.

Referencias

Fuente	Insight Clave
Claude Code v2.0.14 System Prompt	Referencia completa de estructura de prompt de agente en producción
Reddit: Understanding Claude Code's 3 System Prompt Methods	Análisis profundo de Output Styles / --append / --system-prompt, datos reales de putrefacción de contexto
shareAI-lab/learn-claude-code	Filosofía "El modelo es el agente", metodología de ingeniería de harness
Anthropic Prompt Engineering Docs	Mejores prácticas oficiales de prompts
DeepAgents Framework	Middleware de sumarización, divulgación progresiva de skills