Corrige el contexto, no la instrucción

Corrígelo una vez para todos

Cuando un agente se equivoca, el instinto es reescribir la instrucción. Eso corrige una conversación. Escribir la corrección en el repositorio corrige todas las conversaciones futuras, para ti y para cualquier otra persona que trabaje aquí.

Una corrección puede vivir en tres lugares, en orden creciente de durabilidad:

1. La description de la columna en la definición del activo. El agente la lee antes de escribir SQL, así que una buena descripción orienta la siguiente consulta.
2. El archivo AGENTS.md en la raíz del proyecto. El agente lee esta instrucción en cada sesión, por lo que es el lugar para reglas que abarcan todo el proyecto.
3. Una comprobación de calidad que haga imposible publicar el error. Es la más duradera porque falla de forma visible en lugar de depender de que el agente recuerde.

El contexto no es gratis. Las investigaciones sobre archivos de contexto para agentes encontraron que las notas cuidadosas escritas por personas mejoran el éxito de las tareas solo unos pocos puntos porcentuales, y que el contexto generado por máquinas puede empeorar los resultados mientras añade alrededor de un 20 por ciento al coste. Por tanto, el contexto no es bueno automáticamente. Regla: escribe contexto para un fallo concreto que hayas observado, mantenlo breve y verificado, y comprueba que realmente ayudó. Un AGENTS.md largo y genérico es peor que uno breve y preciso.

Con esta plantilla aparecen sobre todo dos correcciones. Registra literalmente la que corresponda al error que viste:

• Eliminó las líneas huérfanas. Un INNER JOIN a products descarta silenciosamente las 15 líneas de pedido cuyo id de producto no tiene coincidencia, junto con 3,637.89 de ingresos reales - el mismo defecto que causa la diferencia de 1,396.89 que viste en los números de 2024. Registra esta regla: «Al unir order_items con products, usa un LEFT JOIN y agrupa las líneas sin coincidencia como 'Unknown'. Un INNER JOIN elimina silenciosamente 15 líneas de ingresos reales.»
• Eligió la columna de ingresos equivocada. Si usó unit_price cuando debía usar net_price, registra: «Los ingresos son quantity * net_price. unit_price es el precio de lista antes del descuento y no representa ingresos.»

Tu tarea

Elige algo que el agente haya hecho mal, o decidido sin consultarte, en las tres últimas lecciones - tus notas de auditoría en queries/audit_v1.md son la lista de tareas. Añade la regla de una línea a AGENTS.md. Después mejora la description de la columna relevante en pipeline/assets/order_items.sql para que la siguiente consulta parta de mejor información; editar una descripción cambia lo que lee el agente, no los datos. Vuelve a hacer la pregunta original y observa si reaparece el error.

Si tu agente no cometió ninguno de los dos errores, también merece la pena notarlo - esta plantilla ya contiene un contexto excepcionalmente bueno, que es el objetivo de la lección. Escribe la corrección de cualquier cosa que sí haya hecho mal, por pequeña que sea, para practicar el mecanismo.

Comprueba tu comprensión

• Nombra los tres lugares donde puede vivir una corrección, en orden de durabilidad.
• ¿Por qué reescribir una instrucción corrige menos que escribir en el repositorio?
• Después de tu corrección, ¿produjo el agente la columna de ingresos correcta y cómo lo confirmaste?

Hazlo con tu agente

Di next lesson y tu agente te enseñará esto, te hará estas preguntas y después asignará la tarea anterior. Hazla a mano y luego di review my work - comparará tu trabajo con una rúbrica y te dirá qué corregir o marcará la lección como terminada.