Tu primer proyecto con agentes de código: el sistema completo

TLDR: El primer proyecto con agentes falla casi siempre por el mismo motivo: delegar demasiado y demasiado pronto sin preparar el terreno. El sistema que funciona: un fichero de instrucciones que le enseña tu proyecto al agente, una escalera de confianza que empieza por tareas pequeñas, todo en ramas con revisión, y CodeRabbit como segunda red cazando lo mecánico. Con Claude Code o con Gemini CLI, el sistema es el mismo.

Esta guía es para desarrolladores que ya eligieron agente (si no, la guía de elegir agente de código es el paso previo) y quieren incorporarlo a un proyecto real sin que la primera semana acabe en desconfianza mutua.

La idea que lo ordena todo: el agente es un compañero nuevo con mucha capacidad y cero contexto. Todo lo que harías con esa incorporación (documentar, empezar por tareas acotadas, revisar su trabajo) aplica exacto.

1. Prepara el repositorio para el agente

La media hora mejor invertida de todo el proceso: el fichero de instrucciones en la raíz del repositorio. Los agentes lo leen al empezar, y su contenido es lo que separa a un agente que adivina de uno que sabe: las convenciones del proyecto (estilo, estructura, patrones que se usan y los que no), los comandos (cómo se ejecutan las pruebas, el linter, el arranque local) y el mapa mínimo (qué vive dónde y qué zonas no se tocan).

Escríbelo como escribirías el documento de bienvenida de un compañero: concreto, con ejemplos, sin filosofía. Y trátalo como código: cuando el agente falle por no saber algo, la corrección va al fichero, no solo a la conversación.

Completa la preparación con higiene básica: pruebas que pasen (son la verificación del trabajo del agente), y un repositorio ordenado, porque el agente hereda el caos igual que lo heredaría el humano nuevo.

2. Calibra qué delegar con una escalera de confianza

La primera semana no se delega la refactorización del núcleo: se sube una escalera de tres peldaños.

Con Claude Code, el criterio en tareas ambiguas permite subir la escalera más rápido. Con Gemini CLI, de código abierto, el mismo sistema funciona quedándose un peldaño más abajo: tareas más acotadas, más verificación. El sistema es idéntico, cambia la altura de crucero.

Si una tarea vuelve mal dos veces, no era de ese peldaño.

Bájala, trocéala o hazla tú, y anota en el fichero de instrucciones lo que el agente no sabía.

3. Trabaja en ramas y revisa cada cambio

La regla no negociable del sistema: el agente trabaja en ramas y tú fusionas después de revisar. Git es la red de seguridad que convierte cualquier desastre en un descarte de rama, y la revisión es el trabajo que queda del lado humano, con una advertencia que la experiencia colectiva ya destiló: la tentación de aprobar sin leer crece con cada éxito del agente, y el día que apruebas sin leer es el día del susto.

La revisión eficaz de código de agente tiene su técnica: primero el diff completo por encima (¿tocó lo que esperabas y nada más?), después las pruebas (¿existen, pasan, prueban lo importante?) y al final la lectura fina de la lógica nueva. El orden importa porque el primer filtro descarta rápido los desvíos grandes.

4. Añade la segunda red con revisión automática

Tu revisión es la red principal y no debería ser la única. CodeRabbit revisa cada pull request al llegar: resume el cambio, caza errores probables y comenta línea a línea, con lo que tu revisión humana empieza con lo mecánico ya filtrado. Gratis para proyectos de código abierto, con capa gratuita limitada en privados y desde 24 dólares al mes.

La combinación agente-más-revisor automático es el patrón que más crece por una razón simple: el volumen de código generado pide una primera pasada automática antes de la atención humana. El detalle completo está en la guía de revisar código de IA.

Con el sistema rodando, las mejoras siguientes son de flujo: el trabajo en paralelo está en la guía de agentes en paralelo, y la capa de contexto persistente en la de memoria de producto con PaellaDoc. Todo el sector, en IA para desarrollo de software.

Errores comunes

Delegar la tarea grande el primer día. Es la receta del desencanto: sin contexto ni calibración, el resultado desvía y la conclusión errónea es que “esto no funciona”.

Saltarse el fichero de instrucciones. El agente sin contexto adivina, y adivinar convenciones produce ese código correcto que no encaja en ningún sitio.

Aprobar sin leer. El éxito acumulado del agente es exactamente lo que erosiona la disciplina de revisión, y el coste llega junto, no repartido.

Corregir en la conversación y no en el fichero. Lo que solo se dijo en el chat se olvida en la siguiente sesión. Lo que está en el fichero de instrucciones es permanente.

Preguntas frecuentes

¿Cuánto tarda en notarse la productividad?

Con el sistema de esta guía, la primera semana ya deja tareas hechas que no hiciste tú. El salto grande llega en el mes uno-dos, cuando la calibración está hecha y el fichero de instrucciones maduro.

¿Sirve el mismo sistema con un agente de código abierto?

Sí: escalera, ramas y revisión funcionan igual con Gemini CLI o Qwen Code. La diferencia es la altura de crucero (tareas más acotadas) y más verificación en lo ambiguo.

¿Qué pongo exactamente en el fichero de instrucciones?

Convenciones con ejemplos, comandos del proyecto y mapa de qué vive dónde. La prueba de calidad: si un compañero nuevo pudiera empezar a trabajar con solo ese documento, está bien escrito.

¿El agente puede romper algo grave?

Con el sistema de ramas y revisión, el radio de daño es una rama descartada. Los sustos reales vienen de saltarse el sistema: trabajar sobre la rama principal o fusionar sin leer.