Ingeniería de contexto: que las herramientas de IA entiendan tu código

Los asistentes de IA para programar se entrenaron con el código del mundo, no con el tuyo. Así que cuando pides un cambio, hacen pattern-matching contra un promedio genérico y adivinan los detalles — inventan un servicio que no tienes, importan desde una ruta que nunca existió, ignoran las convenciones de las que depende tu equipo.

La solución casi nunca es un modelo mejor. Es mejor contexto. La ingeniería de contexto es la práctica de escribir lo que tu código asume, en un formato que las herramientas leen automáticamente — para que el asistente deje de adivinar y empiece a seguir.

Empieza con un archivo de contexto

Casi todos los asistentes hoy leen un archivo de proyecto — CLAUDE.md, AGENTS.md o reglas de editor para Cursor y Copilot. Trátalo como un README escrito para un recién llegado muy rápido y muy literal. Lo de mayor valor para incluir:

• La arquitectura en tres frases.
• Las reglas duras que no son obvias en el código.
• Los errores que los recién llegados siempre cometen.

Unas pocas líneas rinden mucho:

# Servicio de pagos

- El dinero siempre son centavos enteros (`amountCents`), nunca floats.
- Los endpoints nuevos van en `src/api/v2` y necesitan un schema Zod en `schemas/`.
- Nunca llames al ledger directamente — usa `LedgerClient`.

Ese fragmento previene toda una categoría de respuestas incorrectas antes de que ocurran.

Codifica las convenciones como reglas, no como esperanza

Si una convención importa, no confíes en que el modelo la infiera. Decláralas. "Prefiere composición sobre herencia", "todas las fechas son UTC", "los errores suben como valores Result tipados" — cada regla que escribes es una clase de comentario de revisión que ya nunca vuelves a dejar.

Dale un diccionario de datos

Las consultas a base de datos generadas son tan buenas como el entendimiento que el asistente tenga de tu esquema. Un diccionario de datos corto — tablas, columnas clave, relaciones y el significado de negocio detrás de ellas — convierte SQL que parece plausible en SQL correcto. Incluso una sola tabla en markdown describiendo tus entidades principales se paga sola rápido.

Captura el trabajo que repites

Todo código tiene operaciones que haces igual cada vez: agregar un endpoint, cablear una migración, generar un componente. Escribe esos pasos como prompts reutilizables (algunas herramientas los llaman "skills" o "comandos"). Ahora las partes aburridas y propensas a error ocurren a tu manera, de forma consistente, en vez de reinventarse en cada pedido.

Un punto de partida mínimo

No necesitas un despliegue grande. En una tarde puedes:

1. Agregar un archivo de contexto en la raíz del repo con tus diez reglas top.
2. Describir tus tres tablas de base de datos más importantes.
3. Capturar tu tarea más repetida como un prompt reutilizable.

El objetivo no es documentar todo. Es escribir el puñado de cosas que el asistente sigue haciendo mal — y dejar que el beneficio se componga desde ahí.

El contexto es la mejora de rendimiento más barata que tus herramientas de IA recibirán. La mayor parte es conocimiento que tu equipo ya tiene; solo que aún no está escrito donde las herramientas puedan leerlo.