Cómo llevar un proyecto grande con Claude Code: datos, maqueta, carriles y un agente que manda

Con un proyecto grande en Claude Code, el problema deja de ser que el agente escriba buen código. El problema es que escriba el código correcto, en el sitio correcto, sin pisar lo que hizo otra sesión la semana pasada. Un agente de código rinde mucho cuando no tiene que adivinar, y rinde poco cuando cada tarea le obliga a decidir cosas que nadie decidió antes.

Esta guía cuenta un método sencillo para trabajar así, el mismo con el que construimos cada día la web, el campus y el CRM de Ciade. Para que se entienda sin ser programador, lo seguimos con un caso: imagina una clínica dental que quiere su propio sistema de citas, con pacientes, doctoras, tratamientos, recordatorios por WhatsApp y un panel para recepción. Es un proyecto grande para una sola persona con un agente, y es justo donde el método marca la diferencia.

Antes de pensar en pantallas o de escribir el primer encargo, se decide qué cosas existen en el negocio y cómo se relacionan. Un contacto pertenece a una empresa o no. Una tarea cuelga de un contacto, de una empresa o de las dos. Una lista es fija o se recalcula sola. Un pago tiene estados, y cada estado tiene quién lo puede cambiar.

Cada una de esas frases es una decisión que condiciona todo lo demás. Si se toma al principio y se escribe, el agente la tiene como referencia en cada pantalla, y tú puedes revisar que la implementación la respete. Si no se toma, el agente la toma por ti en cada tarea, y cada vez un poco distinta: así aparecen los parches que, con el tiempo, vuelven caótico un proyecto.

No hace falta saber de bases de datos para hacerlo bien. Basta con escribir en español los objetos, sus relaciones y sus estados, y pedirle al agente que proponga el esquema y te lo explique antes de crear nada.

La segunda entrada es la experiencia completa, dibujada antes de programarla. No pantallas sueltas: todos los estados de cada pantalla. La lista con datos, la lista vacía, la lista cargando, la lista con error, el formulario abierto, el guardado con su aviso. Cada uno de esos estados es una escena, y un flujo de trabajo es una cadena de escenas.

Se puede llevar muy lejos: una maqueta navegable de toda la aplicación, con un índice de escenas a un lado, la aplicación pintada al otro y una nota en cada detalle: qué pasa al pulsar, qué se ve mientras carga, qué dice exactamente el error. La idea de fondo sirve a cualquier escala: lo que no está descrito lo acaba decidiendo alguien —o algo— sobre la marcha.

Dos reglas hacen que la maqueta siga siendo útil:

• Consistencia estricta. Las mismas cosas se llaman igual, los espaciados y los tamaños de letra salen de una escala cerrada y nada se pinta fuera de los componentes del sistema de diseño. Un pequeño script puede comprobarlo solo.
• Documento vivo. Ninguna pantalla se programa sin haber pasado antes por la maqueta, y cuando el código cambia una pantalla, la maqueta se actualiza en la misma sesión. Si se deja para después, pronto deja de contar la verdad.

En Ciade lo aplicamos a las piezas grandes: el campus nuevo, por ejemplo, no se programó hasta tener aprobadas las maquetas y una especificación escrita.

En un proyecto grande no conviene que una sola sesión lo sepa todo. Se trabaja por ámbitos: un conjunto de pantallas o flujos que resuelven un mismo problema y que se tocan poco con el resto. En un CRM, por ejemplo, la telefonía, el correo, las listas, el enriquecimiento de datos o el propio sistema de diseño.

Cada ámbito tiene una carpeta de documentación con tres cosas, y es lo primero que lee el agente al empezar:

• En qué estado está: qué funciona, qué falta, qué se decidió.
• Qué archivos son su terreno: lo que puede tocar sin preguntar.
• Qué trampas se han encontrado: lo que ya falló una vez y por qué.

Mejorar un agente suele pasar por mejorar ese documento. Y cuanto más separado está un ámbito del resto, menos se pisan las sesiones entre sí.

Lo que sostiene todo lo anterior es una regla de reparto: un solo agente integra. Hay una sesión principal que vive en la rama principal del repositorio y es la única que fusiona, despliega y aplica cambios en la base de datos común. El resto trabaja en carriles: cada uno en su propia copia del repositorio —un worktree de git—, en su propia rama, sin permiso para subir nada.

Así se pueden tener varias tareas en marcha a la vez sin que un cambio acabe en la rama equivocada ni una compilación mezcle dos trabajos. Cuando un carril termina, el principal revisa, fusiona, despliega y cierra esa copia.

En Ciade funciona así a diario. El agente principal es una sesión de Claude Code que reparte el trabajo; los carriles son otras sesiones —a veces con otros modelos para tareas acotadas— que escriben en su carpeta de .worktrees/, hacen commit en su rama y nunca hacen push. Las migraciones de la base de datos solo se aplican desde la rama principal.

Que el código compile y los tests pasen no significa que esté bien. En Ciade, antes de publicar contenido o de desplegar código que toca a usuarios, correos o pagos, otro modelo lo revisa en modo solo lectura y devuelve una lista: archivo, frase exacta, por qué es un problema y el arreglo mínimo. Ese paso ha cazado afirmaciones que no se sostenían, pasos de instalación que no funcionaban y fallos que los tests no cubrían.

Lo importante es que el revisor no sea el mismo que escribió, y que no pueda editar: solo señala. El principal decide qué se arregla.

Un agente trabaja bien mientras tiene el contexto justo: ni menos, ni más. Por eso el archivo de instrucciones general debe ser corto —lo que hay que saber siempre— y el detalle vive en el documento de cada ámbito. Un archivo de instrucciones de mil líneas se lee entero en cada sesión y ocupa la ventana de contexto con cosas que esa tarea no necesita.

Conviene tener a la vista cuánto contexto queda y cuánto uso te queda en el plan. Claude Code permite configurar una línea de estado con esos datos. Y conviene aprender cuándo cerrar una sesión y abrir otra limpia: una conversación larga acumula decisiones viejas que confunden a la nueva tarea. Para no perder el hilo entre sesiones, en Ciade cada tarea tiene un archivo de punto de control con sus criterios de aceptación, lo decidido, las pruebas y el siguiente paso.

• Parar procesos por nombre. Un carril paró servidores de otros proyectos que corrían en la misma computadora porque buscó los procesos por un patrón demasiado amplio. Regla desde entonces: se para un proceso por su puerto o por el identificador que lanzó esa misma sesión.
• Carriles que se cortan sin guardar. Un carril que escribe cinco piezas y guarda al final puede perderlo todo si se interrumpe. Ahora cada pieza se guarda en cuanto está lista.
• Dos ramas con la misma migración. Dos ramas crearon un cambio de base de datos con el mismo número. Al integrar hubo que renumerar el nuestro. Por eso las migraciones solo nacen en la rama principal o se revisan antes de fusionar.
• Validadores que se quedan viejos. Un comprobador de contenido que no conocía dos series nuevas marcaba errores falsos y acabó ignorándose. Un validador que da falsos avisos es peor que ninguno: se actualiza con el código.

No sustituye saber qué quieres construir: si el modelo de datos está mal pensado, el agente lo implementará bien y seguirá estando mal. Tampoco elimina la revisión: cada fusión la aprueba una persona o el agente principal con criterios escritos. Lo que sí hace es quitarle al agente las decisiones que no le tocan, que es donde se pierden los días.

Si quieres profundizar en las piezas, sigue con qué es un subagente y cómo se orquestan varios agentes.