System Prompts y Contexto Persistente — Prompt Engineering para Desarrolladores

Mas Alla de los Prompts Individuales

Todo lo que hemos cubierto hasta ahora se enfoca en prompts individuales -- una solicitud, una respuesta. Pero los desarrolladores mas productivos usando herramientas de IA no empiezan de cero cada sesion. Configuran su entorno de IA con contexto persistente que se mantiene en cada interaccion: convenciones del proyecto, estandares de codigo, patrones preferidos y conocimiento especifico del dominio.

Esta es la diferencia entre un desarrollador junior que hace las mismas preguntas cada manana y un desarrollador senior que ha internalizado las practicas 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 mas poderosa para un comportamiento consistente de la IA entre sesiones.

Un archivo CLAUDE.md en la raiz de tu proyecto se carga automaticamente cada vez que inicias una sesion de Claude Code en ese directorio. Moldea cada respuesta, cada generacion de codigo y cada refactorizacion que la IA realiza.

Que 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

Que NO Incluir

No pongas secretos, API keys ni credenciales en CLAUDE.md. Este archivo es parte de tu proyecto y podria ser commiteado al control de versiones. No incluyas explicaciones extensas ni documentacion -- mantenlo conciso. La IA lee esto en cada inicio de sesion, asi que archivos largos desperdician espacio de la ventana de contexto.

No incluyas instrucciones temporales ni tareas especificas de sesion. Esas pertenecen en tu prompt, no en la configuracion persistente.

La Jerarquia de Contexto

Las herramientas de IA que soportan archivos de contexto persistente usan una jerarquia de especificidad. Entender esta jerarquia 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 raiz de tu proyecto. Establece estandares especificos 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 especificas por area:

# 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 mas especificos sobreescriben a los menos especificos. Un prompt de tarea que diga "usa console.log para depuracion" 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 especifica definiendo un rol. Esto cambia a que presta atencion la IA y que tipo de salida produce.

Revisor de Seguridad

Para esta sesion, actua como revisor de seguridad. Cuando te muestre codigo:
- Enfocate 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:
- Enfocate 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 Codigo

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 mayoria de las herramientas de desarrollo no exponen controles de temperatura directamente, puedes influir en el estilo de salida a traves de tus prompts.

Cuando quieres salida determinista y predecible (generacion de codigo, correccion 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, resolucion 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 explicito sobre en que modo estas. La IA por defecto es conservadora con el codigo (lo cual generalmente es correcto), pero a veces quieres que piense ampliamente.

Seleccion de Modelo para Diferentes Tareas

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

Modelos rapidos (Claude Sonnet, GPT-4o-mini) funcionan bien para:

Generacion de codigo simple con patrones claros
Documentacion inline y comentarios
Explicaciones y consultas rapidas
Generacion de tests desde listas explicitas de casos de test
Sugerencias de formateo y linting

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

Depuracion compleja con contexto multi-archivo
Decisiones de arquitectura y analisis de tradeoffs
Refactorizacion a gran escala en muchos archivos
Auditorias de seguridad y analisis de vulnerabilidades
Code review con feedback matizado

En Claude Code, puedes cambiar de modelo a mitad de sesion con el comando /model o iniciar con un modelo especifico usando el flag --model.

El Meta-Prompt: Mejorando Tus Propios Prompts

Uno de los usos mas poderosos de la IA es mejorar tus propios prompts. Cuando consistentemente obtienes malos resultados de un prompt, pidele 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 tecnica de meta-prompt es especialmente util cuando estas empezando. Con el tiempo, internalizas los patrones y escribes prompts precisos de forma natural.

Construyendo la Configuracion de IA de Tu Proyecto

Aqui hay un enfoque practico para construir contexto persistente efectivo para tu proyecto:

Comienza con lo minimo. Crea un CLAUDE.md con solo tu stack tecnologico y las 5 convenciones de codigo principales. Usalo 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 habria prevenido. "NO usar punto y coma" o "Siempre usar exports con nombre" -- estas reglas especificas se acumulan en una guia 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 friccion en code review y mejorando la uniformidad del codebase.

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