Instrucciones para un agente de código: qué va en el archivo

El archivo de reglas es donde el agente aprende qué puede decidir por su cuenta. Si el archivo no dice qué es terminar, el agente se detiene en cuanto el trabajo parece listo, y te toca revisar todo a ti. Las reglas de abajo salen de la documentación de prácticas de Claude Code y de la investigación del Nielsen Norman Group sobre trabajar con IA.

El criterio de fin va antes del pedido

La documentación de prácticas de Claude Code (en inglés) explica el mecanismo en una frase: el agente se detiene cuando el trabajo parece listo. Sin una comprobación que pueda correr por su cuenta, “parece listo” es la única señal que queda, y cada error espera a que lo veas.

El criterio de fin es una señal que el agente lee por su cuenta. Sirve la suite de pruebas, el código de salida del build, el linter, o un script que compara la salida con un archivo de referencia. La misma página lista qué hacer con eso en la práctica. Pide los casos de prueba junto con la función y la captura de pantalla comparada con el diseño. Pide también que el error de build se corrija en la causa, en vez de silenciarlo.

Eso cambia el formato del pedido. Una especificación que funciona nombra los archivos y las interfaces involucrados, dice qué queda fuera de alcance y termina con una verificación de punta a punta. Lo que escribes antes termina valiendo más que cualquier corrección a mitad de camino.

Una comprobación que pasó una vez no es una evaluación. Un agente de código genera de nuevo en cada pedido, y el Nielsen Norman Group recuerda que esa generación varía de una ronda a otra (en inglés). Ejecuta la verificación más de una vez antes de tratar el resultado como una señal firme. El método completo está en evaluación de salida de IA.

El archivo que se carga en cada sesión tiene que ser corto

El archivo de reglas se lee al comienzo de cada conversación, así que todo lo que entra en él ocupa contexto en todas las tareas. La página de prácticas recomienda una prueba por línea: si quitar esa línea no hace que el agente falle, córtala. La propia documentación señala el efecto colateral de un archivo inflado: la regla se pierde en medio del texto y el agente pasa a ignorar instrucciones que están escritas.

Cuando una regla se ignora con frecuencia, el arreglo no es reescribir el archivo entero. La orientación es dar énfasis a esa línea sola, porque un énfasis repartido por varias líneas no destaca ninguna.

Lo que no sea una regla general sale de aquí. El conocimiento que solo vale para un tipo de tarea pertenece a un archivo que el agente carga cuando aparece la tarea, y no al archivo que carga siempre.

La autonomía se escribe junto con el punto de parada

Pedir permiso a cada paso parece seguro y no lo es. La documentación describe el efecto real del modo manual: después de la décima aprobación estás haciendo clic en vez de revisar (en inglés). La pausa que nadie planeó se vuelve un sello automático.

El diseño que funciona separa tres cosas. Las herramientas de lectura y los comandos en los que ya confías entran en una lista de aprobación previa. Lo que modifica el sistema pide una decisión. Lo que no tiene vuelta atrás pide una persona, y esa lista es corta y explícita.

Una regla que no puede fallar no debería vivir como instrucción. La documentación es clara sobre la diferencia: una instrucción en texto es un consejo, un hook, un script que se ejecuta solo ante un evento, es determinístico y garantiza que la acción ocurra. Lint antes del commit, prueba antes del push y el escaneo de secretos son hooks, no frases.

Una instrucción nueva entra en cola, y la investigación va a un subagente

Una instrucción nueva no debería cancelar la ejecución en curso. Entra en la cola y el trabajo anterior termina, porque una tarea interrumpida a medias deja el repositorio en un estado que nadie sabe describir.

La investigación es el caso en el que vale la pena gastar contexto aparte. El artículo IA en el flujo de diseño describe la misma división entre lo que hace la herramienta y lo que queda en manos de la persona. La documentación recomienda subagentes para la indagación, porque se ejecutan con contexto propio y dejan de llenar la conversación principal con archivos que solo servían para encontrar un camino. La lectura de un repositorio grande es el ejemplo que da la página.

Aquí el consejo cambió respecto a lo que se decía antes. El NN/g recomendaba tratar a la IA como pasante (en inglés), con un encargo cerrado y dirección paso a paso, justamente porque un encargo abierto sin dirección produce una salida genérica. La práctica actual invierte la forma del pedido sin invertir el principio: sigues dando dirección, solo que escribiendo el criterio de fin y dejando que el agente trabaje hasta cumplirlo.

La revisión mira el diff, no la base

La revisión del código de un agente se hace por lo que cambió. Un commit grande no lo puede revisar nadie, ni tú la semana siguiente, y por eso la recomendación de un commit pequeño y descriptivo vale el doble aquí.

La documentación también avisa dónde el registro no es confiable: los puntos de control (checkpoints) registran solo los cambios hechos por las herramientas de edición del agente. Lo que pasó por línea de comando o por un proceso externo no entra. Git sigue siendo el historial, y el checkpoint no lo sustituye.

Pide evidencia en vez de una afirmación. La página lo plantea como un ahorro de tiempo. Leer la salida de la prueba, el comando ejecutado y lo que devolvió es más rápido que repetir la verificación por tu cuenta.

Lo que salió sin fuente necesita una marca

Un modelo de lenguaje a veces da una respuesta que suena bien, está mal y llega con total confianza. El NN/g describe la alucinación exactamente así (en inglés), como un dato que parece verdadero y no lo es, presentado de una manera que dificulta la identificación.

El problema es que comprobar cuesta trabajo, y ese trabajo es lo que decide si alguien comprueba o no. La revisión del NN/g muestra que las personas se saltan la verificación (en inglés) porque la herramienta se adoptó justamente por la promesa de eficiencia. El mismo artículo avisa que volver a comprobar es obligatorio después de una corrección, ya que la nueva versión puede introducir otro error.

La regla que queda para el archivo es corta, y ya vale en cualquier flujo de IA, como en el trabajo de síntesis. Toda afirmación de un hecho lleva la fuente o recibe la marca de no verificada. Lo que no se puede verificar no se entrega, y esa frase está en la propia lista de fallos comunes de la documentación de prácticas.

Dónde los artículos del NN/g divergen entre sí

Los dos artículos no coinciden sobre dónde debe vivir la instrucción. El Your AI UX Intern (en inglés) pide una instrucción detallada en el pedido, paso a paso, porque la herramienta se pierde con un encargo abierto. El artículo The 3 Roles of Context for AI Agents (en inglés) señala el camino inverso. Quien usa un agente todos los días arma una biblioteca de contexto, y la palanca pasa a la curaduría de esa biblioteca.

También divergen sobre el valor de una ronda. El One AI Output Is an Example, Not an Evaluation (en inglés) trata la salida aislada como una muestra que no sostiene una conclusión, y pide rondas repetidas con un intervalo de confianza. El artículo de la pasante trata la primera pasada como aprovechable, siempre que alguien la revise después.

Lo que ambos mantienen es la frontera. El agente entrega un borrador y evidencia, y la decisión de aceptar sigue siendo de una persona, con nombre en el commit.