$ el problema no es el modelo, es el mapa

Cuando un agente de código se equivoca —reescribe algo que no debía, reinventa una decisión ya tomada, mete una dependencia que ya evité a propósito antes— casi nunca es porque el modelo sea malo. Es porque el proyecto no le dio suficiente información para saberlo.

Un desarrollador humano nuevo en el equipo tampoco lo sabría sin que alguien se lo contara. La diferencia es que a un agente hay que contárselo de forma explícita, escrita, y en un sitio donde la vaya a leer antes de actuar.

Esto es lo que hago para que eso pase.

Un documento de decisiones, no solo un README

El README explica cómo instalar y correr el proyecto. Eso no es lo mismo que explicar por qué el proyecto es como es. Mantengo un documento aparte —piénsalo como un registro de decisiones— con cosas del tipo:

  • Qué alcance tiene la versión actual y qué queda explícitamente fuera.
  • Qué alternativas se descartaron y por qué, para no tener que volver a discutirlas cada vez.
  • Qué reglas no se deben erosionar sin que alguien lo plantee explícitamente.

Sin esto, un agente —o un colaborador nuevo— tiende a "mejorar" cosas que en realidad ya se decidieron en contra a propósito. La decisión sin razón escrita se ve como descuido, y se corrige. La decisión con razón escrita se respeta.

ADRs para lo que sí cambia con el tiempo

Para decisiones técnicas puntuales —por qué esta librería y no otra, por qué esta arquitectura y no la alternativa obvia— uso ADRs cortos. Un archivo por decisión, con fecha, contexto y consecuencias. No hace falta que sea largo. Lo importante es que exista y que un agente pueda leerlo antes de tocar esa parte del código.

La alternativa habitual —que la razón viva solo en la cabeza de quien decidió— funciona hasta que esa persona no está delante para explicarla otra vez. Con un agente, "no está delante" es la situación por defecto.

Instrucciones a nivel de repo, no de prompt

Cada vez es más común que las herramientas de agente lean un archivo de instrucciones propio del repo antes de empezar a trabajar. Ahí no pongo vaguedades tipo "escribe código limpio". Pongo cosas verificables:

  • Convenciones de nombres y estructura de carpetas reales del proyecto, no genéricas.
  • Comandos exactos para testear, compilar y lintear.
  • Qué patrones evitar porque ya se probaron y se descartaron.

Cuanto más concreto y más verificable, menos margen de interpretación libre le dejas al agente. Y menos margen de interpretación es, casi siempre, menos error.

Tareas pequeñas, límites claros

Un agente se pierde más fácilmente en una tarea enorme y ambigua que en cinco tareas pequeñas y concretas. Antes de lanzar algo grande, lo trocero yo mismo: qué archivos toca, qué debería quedar igual, cuál es el criterio de "terminado" para esa parte concreta.

Esto no es exclusivo de trabajar con agentes. Es la misma disciplina de planificar antes de programar que ya aplicaba antes de que existieran estas herramientas. Lo que cambia es que ahora esa disciplina se nota más rápido: un agente ejecuta la tarea mal definida sin pedir aclaraciones, un humano suele parar a preguntar.

El resultado práctico

Con esto en marcha, un agente puede entrar a una parte del repo que no ha tocado nunca y comportarse razonablemente bien, porque el contexto que necesita no depende de que yo se lo explique en el chat cada vez. Vive en el proyecto.

Eso es, en el fondo, lo mismo que se le pide a cualquier documentación buena: que sirva sin que el autor esté presente para aclarar dudas.

Relacionado: Qué es un ADR y por qué lo uso incluso en proyectos pequeños