Cómo darle contexto arquitectónico a la IA

“Hazlo funcionar” es la instrucción más común que le damos a una IA. También es la más peligrosa.

Cuando se la escribes así, sin nada más, le estás pidiendo que resuelva un síntoma sin saber nada del sistema completo.

No sabe quién más va a tocar ese código. No sabe qué otras partes dependen de esa función. No sabe cuánto presupuesto tienes, ni si esto va a vivir dos semanas o dos años.

La IA no tiene forma de adivinar nada de eso. Y como no puede dejar la respuesta en blanco, rellena los huecos con lo que vio más veces durante su entrenamiento: la respuesta genérica de un tutorial, no la que necesita tu proyecto específico.

Un prompt sin contexto no es neutral

Esto es lo que más cuesta interiorizar: cuando no das contexto, no recibes una respuesta imparcial. Recibes una respuesta construida sobre supuestos que nunca viste y que nunca aprobaste.

Pide agrega autenticación a mi API sin más detalle, y es muy común recibir JWT con refresh tokens, control de roles y middleware de permisos en cada endpoint. El paquete completo, como si estuvieras construyendo el backend de un banco.

Para una API interna que usan tres personas de tu propio equipo, eso es una arquitectura de seguridad de nivel bancario aplicada a un proyecto que ni siquiera tiene usuarios externos. Vas a mantener refresh tokens que nadie pidió y a depurar expiraciones de sesión que nunca debieron existir.

El código no está mal escrito. El problema es que nadie le dijo a la IA que no hacía falta, y ella no tenía forma de saberlo.

Estos son los supuestos que aparecen una y otra vez cuando falta información:

Las cuatro piezas que cambian el resultado

No hace falta escribir un documento de requisitos. Con cuatro datos concretos, la respuesta cambia por completo.

1. El tamaño real del proyecto

Cuántos usuarios tienes hoy, cuánto tráfico esperas, y si esto va a crecer rápido o se va a quedar chico un buen tiempo.

Sin este dato, la IA asume que estás construyendo algo que necesita escalar desde el inicio, porque esa es la situación más representada en el contenido técnico con el que fue entrenada. Nadie escribe tutoriales sobre cómo servir a cuarenta usuarios.

Decir son menos de 500 visitas diarias y no espero que crezca este año elimina de un golpe la mitad de las propuestas que ibas a recibir.

2. Qué ya existe en tu sistema

Si estás agregando algo a un proyecto que ya tiene una forma establecida de manejar las validaciones, los errores o las respuestas de la API, decírselo evita que te proponga un patrón distinto cada vez.

Este es el origen de un problema muy común en proyectos hechos con IA: cada archivo parece escrito por una persona distinta. Y en cierto sentido lo fue, porque cada conversación empezó sin memoria de las decisiones anteriores.

3. Lo que no quieres

Suena contraintuitivo, pero las restricciones son tan útiles como los objetivos.

Decir no agregues una librería nueva para esto o ya decidí que no voy a usar Redis acota el espacio de soluciones al que de verdad te sirve. Sin esa frontera explícita, la IA tiende a resolver el problema con la herramienta más completa que conoce, no con la más simple que funciona.

4. Quién va a mantener esto

Si la respuesta es solo yo, preguntándole otra vez a la IA en unos meses, vale la pena pedir explícitamente que evite patrones que requieran conocimiento especializado para entenderse.

Un patrón puede ser técnicamente superior y aun así ser la decisión equivocada para tu proyecto, si te deja con código que no puedes explicar ni modificar sin ayuda.

Contexto, rol, tarea y resultado esperado

Cuando la decisión importa, un prompt se sostiene mejor con cuatro elementos: contexto (qué es tu proyecto y en qué etapa está), rol (desde qué prioridad quieres que responda), tarea específica (qué necesitas exactamente, no el objetivo general) y resultado esperado (cómo se ve una buena respuesta para ti).

Compara estos dos prompts para el mismo problema, guardar el carrito de compras de un usuario mientras navega.

“Hazme un sistema de carrito de compras.”

Con ese prompt es común terminar con una tabla nueva en base de datos, un endpoint completo de CRUD, y hasta sincronización entre dispositivos que nadie pidió.

“Contexto: tienda online con menos de 500 visitas diarias, ya uso localStorage para otras preferencias del sitio. Rol: prioriza la solución más simple posible, no la más completa. Tarea: guardar el carrito de un usuario mientras navega, sin que se pierda al recargar la página. Resultado esperado: una solución que no agregue tablas ni endpoints nuevos si se puede evitar.”

La respuesta razonable al segundo es extender lo que ya usas: guardar el carrito en localStorage, sin nada nuevo del lado del servidor. Mismo problema, contexto distinto, solución completamente diferente.

El contexto cambia según lo que estés pidiendo

No todo pedido necesita el mismo tipo de información.

Para una funcionalidad nueva, lo que pesa es el contexto de negocio: para quién es, cuánto tiene que escalar, qué restricciones de presupuesto o plazo existen.

Para un error, lo que pesa es otra cosa: qué esperabas que pasara, qué pasó en realidad, qué cambió desde la última vez que funcionaba, y sobre todo qué ya descartaste.

Ese último punto es el que más se olvida. Cuando pegas solamente el mensaje de error, la IA empieza por las causas más frecuentes, que probablemente ya revisaste. Decir ya verifiqué que la conexión funciona y que la variable llega con valor la obliga a mirar más allá de lo obvio.

Para un refactor, lo que pesa es el límite: qué comportamiento no puede cambiar. Sin esa frontera, es fácil recibir código más elegante que hace algo ligeramente distinto a lo que hacía antes.

Pídele que repita el contexto antes de escribir código

Hay una técnica simple que ahorra mucho trabajo: antes de pedir la implementación, pide un resumen.

“Antes de escribir código, dime en tres puntos qué entendiste que necesito y qué restricciones aplican.”

Si el resumen no coincide con lo que tenías en la cabeza, acabas de detectar el desajuste en diez segundos, en lugar de después de revisar doscientas líneas.

Es el mismo principio que usarías con otra persona: confirmar el entendimiento antes de que empiece a trabajar sale mucho más barato que corregir el resultado terminado.

El contexto que la IA no puede leer del código

Aunque le des acceso al repositorio completo, hay información que simplemente no está ahí.

El código te dice qué hace el sistema. No te dice por qué se decidió así, qué alternativa se descartó, ni qué se intentó antes y falló.

Ese conocimiento vive en la cabeza de quien tomó la decisión, y es justo el que evita que alguien vuelva a proponer el camino que ya se probó sin éxito.

Tres formas típicas de contexto invisible:

• Decisiones descartadas. Probamos mover esto a una cola y la latencia empeoró, lo revertimos. Sin ese dato, la siguiente propuesta va a ser exactamente esa.
• Restricciones del entorno. Una función deshabilitada por el proveedor de hosting, un límite de memoria, una versión que todavía no puedes actualizar.
• Acuerdos de negocio. Un cliente que exige que sus datos no salgan del país, o un contrato que te obliga a seguir soportando un navegador viejo.

Nada de esto se deduce leyendo archivos. Si no queda escrito en alguna parte, se pierde en cada sesión nueva.

Cómo dejar de repetir el contexto en cada conversación

Escribir todo esto cada vez es insostenible. La alternativa es dejarlo una sola vez en el repositorio, en un archivo que puedas pegarle a la IA al inicio de cualquier sesión.

La convención que se está estandarizando para esto es un archivo AGENTS.md en la raíz del proyecto. No tiene un formato obligatorio, pero estas secciones cubren lo esencial:

# AGENTS.md

## Qué es este proyecto
Blog estático en PHP + Twig. El contenido vive en PocketBase y se genera
a HTML plano en cada build. Los visitantes nunca tocan la API.

## Decisiones ya tomadas (no reabrir sin motivo)
- Sin framework de frontend. CSS propio, sin Tailwind.
- Sin build step de JS. Los componentes usan HTML nativo (details,
  dialog, popover) y solo se agrega JS cuando el HTML no alcanza.
- Las imágenes se procesan a WebP en el build. AVIF está descartado:
  el codec no está disponible en este hosting.

## Restricciones del entorno
- PHP 8.2 en hosting compartido.
- exec() y shell_exec() están deshabilitados por el proveedor.
- El webroot se llama public_html en local y en producción.

## Cómo correr esto
php tools/generate.php   # rebuild completo

Lo importante no es el formato, es que incluya las decisiones ya cerradas y las restricciones del entorno. Eso es justo lo que la IA no puede deducir leyendo el código, y lo que más seguido termina rompiendo cuando no lo sabe.

Dos archivos, dos funciones distintas

Conviene separar lo estable de lo que cambia todo el tiempo.

AGENTS.md guarda lo que ya se decidió y no debería reabrirse sin un motivo: stack, patrones, restricciones. Cambia pocas veces.

TASKS.md guarda el estado: qué está hecho, qué quedó a medias, qué sigue. Cambia en cada sesión.

Mezclarlos en un solo documento hace que la parte importante se llene de ruido temporal y termine sin leerse.

Tres errores comunes al dar contexto

Dar contexto también se hace mal, y el resultado puede ser peor que no darlo.

Dar contexto de más. Pegar el proyecto entero no ayuda, diluye lo importante entre ruido. Lo que sirve es lo que afecta a esta decisión puntual, no todo lo que existe.

Describir la solución en lugar del problema. Si escribes agrégame una tabla de sesiones, ya decidiste por la IA. Si escribes necesito que el usuario siga identificado al recargar la página, dejas espacio para que te proponga algo más simple que quizá no habías considerado.

No decir qué ya intentaste. Cuando algo falló antes, decirlo evita que te propongan el mismo camino otra vez. Es la diferencia entre una segunda opinión y una repetición.

Cuándo esta estructura es exagerada

No todos los prompts necesitan los cuatro elementos. Pedirle a la IA que renombre una variable o formatee un archivo no requiere contexto de negocio.

La estructura completa se justifica cuando la decisión tiene costo de revertir: cambios en el modelo de datos, elección de librerías centrales, y cualquier cosa relacionada con autenticación, permisos o pagos.

Para el resto, un prompt directo alcanza. Exigirte el formato completo cada vez solo te haría más lento sin ganar nada a cambio.