System Prompts y Contexto Persistente — Prompt Engineering para Desarrolladores

Más Allá de los Prompts Individuales

Todo lo que hemos cubierto hasta ahora se enfoca en prompts individuales -- una solicitud, una respuesta. Pero los desarrolladores más productivos usando herramientas de IA no empiezan de cero cada sesión. Configuran su entorno de IA con contexto persistente que se mantiene en cada interacción: convenciones del proyecto, estándares de código, patrones preferidos y conocimiento específico del dominio.

Esta es la diferencia entre un desarrollador junior que hace las mismas preguntas cada mañana y un desarrollador senior que ha internalizado las prácticas del equipo. Los system prompts y archivos de contexto persistente te permiten construir ese conocimiento institucional en tus herramientas de IA.

CLAUDE.md como System Prompt

Claude Code lee archivos CLAUDE.md de tu directorio de proyecto y los trata como instrucciones persistentes. Esta es tu herramienta más poderosa para un comportamiento consistente de la IA entre sesiones.

Un archivo CLAUDE.md en la raíz de tu proyecto se carga automáticamente cada vez que inicias una sesión de Claude Code en ese directorio. Moldea cada respuesta, cada generación de código y cada refactorización que la IA realiza.

Qué Incluir

# Proyecto: API de E-Commerce

## Stack Tecnologico
- Express.js 4 con TypeScript 5 (modo estricto)
- Prisma ORM con PostgreSQL 15
- Vitest para testing
- Zod para validacion de entrada
- Pino para logging estructurado

## Convenciones de Codigo
- Usar async/await, nunca callbacks crudos ni cadenas .then()
- Manejo de errores: lanzar subclases de AppError, nunca Error plano
- Nombres: camelCase para variables/funciones, PascalCase para tipos/clases
- Estructura de archivos: una clase/funcion exportada por archivo
- Imports: usar alias de ruta (@/services, @/utils, @/routes)

## Patrones a Seguir
- Servicios: inyeccion de dependencias por constructor
- Rutas: handlers delgados que delegan a servicios
- Validacion: schemas Zod en src/schemas/, usados en middleware de rutas
- Tests: factories para datos de prueba, mocks en directorio __mocks__/

## Patrones a Evitar
- NO usar tipos any/unknown sin justificacion explicita
- NO instalar paquetes nuevos sin preguntar primero
- NO usar console.log (usar el logger de src/lib/logger.ts)
- NO escribir SQL directamente (usar Prisma)

## Comandos Comunes
- npm test -- ejecutar todos los tests
- npm run test:watch -- ejecutar tests en modo watch
- npx prisma migrate dev -- ejecutar migraciones de base de datos
- npm run lint -- ejecutar ESLint

Qué NO Incluir

No pongas secretos, API keys ni credenciales en CLAUDE.md. Este archivo es parte de tu proyecto y podría ser commiteado al control de versiones. No incluyas explicaciones extensas ni documentación -- mantenlo conciso. La IA lee esto en cada inicio de sesión, así que archivos largos desperdician espacio de la ventana de contexto.

No incluyas instrucciones temporales ni tareas específicas de sesión. Esas pertenecen en tu prompt, no en la configuración persistente.

La Jerarquía de Contexto

Las herramientas de IA que soportan archivos de contexto persistente usan una jerarquía de especificidad. Entender esta jerarquía te permite configurar el comportamiento al nivel correcto.

Nivel 1 -- Preferencias globales (aplica a todos los proyectos):

En Claude Code, esto es ~/.claude/CLAUDE.md. Establece preferencias que aplican en todas partes:

# Preferencias Globales
- Siempre responder en espanol
- Usar conventional commits: feat:, fix:, refactor:, docs:, test:
- Preferir TypeScript con modo estricto
- Usar async/await, nunca callbacks

Nivel 2 -- Convenciones del proyecto (aplica a un proyecto):

Este es el CLAUDE.md en la raíz de tu proyecto. Establece estándares específicos del proyecto:

# Proyecto: API de App Movil
- Framework: Fastify (NO Express)
- ORM: Drizzle (NO Prisma)
- Testing: Vitest con Testing Library

Nivel 3 -- Instrucciones por directorio (aplica a archivos en un directorio):

Puedes colocar archivos CLAUDE.md en subdirectorios para reglas específicas por área:

# src/services/CLAUDE.md
- Todos los servicios usan inyeccion por constructor
- Los servicios deben tener un archivo .test.ts correspondiente
- Los servicios no deben importar de routes/ ni middleware/

Nivel 4 -- Instrucciones por tarea (aplica a un prompt):

Estos son tus prompts individuales. Sobreescriben todo lo anterior para la tarea actual.

Cuando las instrucciones entran en conflicto, los niveles más específicos sobreescriben a los menos específicos. Un prompt de tarea que diga "usa console.log para depuración" sobreescribe un CLAUDE.md del proyecto que dice "nunca uses console.log."

Instrucciones Personalizadas para Diferentes Roles

Puedes dirigir a la IA para que adopte una perspectiva específica definiendo un rol. Esto cambia a qué presta atención la IA y qué tipo de salida produce.

Revisor de Seguridad

Para esta sesion, actua como revisor de seguridad. Cuando te muestre codigo:
- Enfócate exclusivamente en vulnerabilidades de seguridad
- Verifica: inyeccion SQL, XSS, CSRF, bypasses de autenticacion,
  deserializacion insegura, path traversal, exposicion de datos sensibles
- Califica cada hallazgo como Critico, Alto, Medio o Bajo
- Para cada hallazgo, muestra el codigo vulnerable y una version corregida
- Ignora completamente estilo de codigo, rendimiento y legibilidad

Optimizador de Rendimiento

Para esta sesion, actua como ingeniero de rendimiento. Al revisar codigo:
- Enfócate en rendimiento en tiempo de ejecucion y uso de recursos
- Identifica: consultas N+1, re-renders innecesarios, fugas de memoria,
  operaciones bloqueantes, consultas sin indice, imports grandes del bundle
- Cuantifica el impacto donde sea posible (ej. "esta consulta N+1 hara
  100 llamadas a la base de datos para una lista de 100 items")
- Sugiere correcciones con comparacion antes/despues
- Ignora seguridad, documentacion y estilo de codigo

Revisor de Código

Para esta sesion, actua como un desarrollador senior haciendo code review.
Cuando comparta diffs:
- Verifica correctitud primero (errores de logica, casos extremos faltantes)
- Luego verifica mantenibilidad (nombres, complejidad, acoplamiento)
- Luego verifica consistencia con los patrones de nuestro proyecto
- Senala cualquier cosa que seria dificil de cambiar despues (cambios de
  esquema, superficie de API publica)
- Formatea como comentarios de PR: archivo, linea, severidad (debe-corregir,
  deberia-corregir, nit), comentario

Temperatura y Creatividad

Diferentes tareas se benefician de diferentes niveles de creatividad de la IA. Aunque la mayoría de las herramientas de desarrollo no exponen controles de temperatura directamente, puedes influir en el estilo de salida a través de tus prompts.

Cuando quieres salida determinista y predecible (generación de código, corrección de bugs, tests):

Genera la implementacion exacta basada en la especificacion. No agregues
funcionalidades extra, optimizaciones ni alternativas. Sigue los patrones
de nuestro codebase exactamente. Si algo es ambiguo, pregunta en lugar
de adivinar.

Cuando quieres salida creativa y exploratoria (arquitectura, brainstorming, resolución de problemas):

Propone multiples enfoques. Incluye soluciones no convencionales. Explica
los tradeoffs de cada una. Estoy en modo exploracion -- quiero ver el
espacio completo de soluciones antes de reducir opciones.

La clave es ser explícito sobre en qué modo estás. La IA por defecto es conservadora con el código (lo cual generalmente es correcto), pero a veces quieres que piense ampliamente.

Selección de Modelo para Diferentes Tareas

Diferentes modelos de IA tienen diferentes fortalezas. Si tu herramienta permite selección de modelo, empareja el modelo con la tarea.

Modelos rápidos (Claude Sonnet, GPT-4o-mini) funcionan bien para:

Generación de código simple con patrones claros
Documentación inline y comentarios
Explicaciones y consultas rápidas
Generación de tests desde listas explícitas de casos de test
Sugerencias de formateo y linting

Modelos poderosos (Claude Opus, GPT-4o, o1) valen el costo para:

Depuración compleja con contexto multi-archivo
Decisiones de arquitectura y análisis de tradeoffs
Refactorización a gran escala en muchos archivos
Auditorías de seguridad y análisis de vulnerabilidades
Code review con feedback matizado

En Claude Code, puedes cambiar de modelo a mitad de sesión con el comando /model o iniciar con un modelo específico usando el flag --model.

El Meta-Prompt: Mejorando Tus Propios Prompts

Uno de los usos más poderosos de la IA es mejorar tus propios prompts. Cuando consistentemente obtienes malos resultados de un prompt, pídele a la IA que te ayude a reescribirlo.

Sigo usando este prompt pero los resultados son inconsistentes:

"Refactoriza el componente para que sea mas performante"

Ayudame a reescribir este prompt para que sea mas especifico y accionable.
Hazme preguntas de clarificacion sobre:
1. Que problema de rendimiento especifico estoy viendo
2. Para que metricas estoy optimizando (tiempo de render, tamano de bundle, memoria)
3. Que restricciones tengo (no puedo cambiar la API, debo soportar IE11, etc.)
4. Que patrones quiero que el codigo refactorizado siga

Luego escribe una version mejorada de mi prompt basada en mis respuestas.

Esta técnica de meta-prompt es especialmente útil cuando estás empezando. Con el tiempo, internalizas los patrones y escribes prompts precisos de forma natural.

Construyendo la Configuración de IA de Tu Proyecto

Aquí hay un enfoque práctico para construir contexto persistente efectivo para tu proyecto:

Comienza con lo mínimo. Crea un CLAUDE.md con solo tu stack tecnológico y las 5 convenciones de código principales. Úsalo por una semana.
Agrega reglas reactivamente. Cada vez que la IA produce salida que no coincide con el estilo de tu proyecto, agrega una regla a CLAUDE.md que lo habría prevenido. "NO usar punto y coma" o "Siempre usar exports con nombre" -- estas reglas específicas se acumulan en una guía de estilo completa.
Revisa mensualmente. Elimina reglas que ya no aplican. Consolida duplicados. Reordena por importancia. Tu CLAUDE.md debe ser un documento vivo, no un archivo que se escribe una vez.
Comparte con tu equipo. Commitea CLAUDE.md a tu repositorio. Cuando cada desarrollador del equipo usa el mismo contexto persistente, la salida de la IA se vuelve consistente en todo el equipo -- reduciendo la fricción en code review y mejorando la uniformidad del codebase.

La inversión en construir buen contexto persistente paga retornos en cada interacción con IA durante la vida del proyecto. Un CLAUDE.md bien elaborado puede ahorrar horas por semana en un equipo de desarrollo.