Cuadra es un SaaS multi-tenant que maneja dinero, inventario y datos de muchos comercios en una misma base de datos. Es el tipo de sistema donde un error no aparece en la demo: aparece en el cierre de caja de un cliente. Lo desarrollo solo, con Claude Code, y la pregunta nunca fue si el agente escribe buen código —muchas veces lo hace—, sino cómo garantizar que cada cambio sea revisable, probado y dentro del alcance cuando buena parte del código lo propone un agente.
El problema no es el código, es el alcance
Un agente sin límites tiende a hacer de más: arregla algo que vio de paso, agrega una dependencia «útil», refactoriza el módulo vecino. Cada cosa por separado es razonable; juntas producen PRs imposibles de revisar. La solución fue convertir el proceso en algo que el agente ejecuta, no en algo que yo tengo que recordar.
Las reglas viven en el repositorio
CLAUDE.md es el contrato. No es documentación para humanos: son las instrucciones que el agente carga en cada sesión. Arquitectura hexagonal por módulo, cómo se aísla cada tenant, float prohibido para dinero, API contract-first con OpenAPI y qué puede ir en un span y qué no. Las reglas críticas son verificables:
## Multi-tenant (crítico)
- Toda operación de BD de negocio corre dentro de `platform/db.WithTenantTx(ctx, fn)`.
- El `tenant_id` sale solo del token autenticado (contexto), nunca del body o de la URL.
- Cada repositorio nuevo lleva un test de aislamiento: los datos del tenant A
no se ven ni se modifican desde el tenant B./tarea: rama → plan → tests en rojo → implementación
El flujo es un comando propio. /tarea T23 crea la rama desde main actualizada, lee el plan de la fase y los pendientes que le tocan, y presenta un plan corto. Ahí se detiene: nada se escribe hasta que yo lo apruebo.
- Rama: una por tarea. Si hay cambios sin commit en otra, se detiene y avisa.
- Plan: archivos, cambios al contrato OpenAPI, nombres de los tests en español, spans y métricas, preguntas abiertas. Espera aprobación.
- Tests en rojo: escribe solo los tests y muestra que fallan por la razón esperada.
- Implementación: lo mínimo para que pasen; después, refactor.
- Verificación: make check en verde. Nunca se salta ni se desactiva un test.
El paso que más valor aporta es el tercero. Ver el test fallar por la razón correcta es la prueba de que mide algo; un test escrito después de la implementación tiende a confirmar lo que el código ya hace.
Lo que queda fuera no se pierde
Regla: si el agente ve algo que mejorar fuera del alcance, lo anota; no lo hace. Esas notas van a docs/plan/pendientes.md con su origen y su destino, la tarea posterior que lo cubre. Al empezar una tarea, /tarea lee los pendientes que le corresponden y los mete en el plan. Hoy hay unos 40 registrados, desde el rate limit del registro hasta los paneles de Grafana de la caja.
Cerrar es un permiso, no un hábito
El agente no hace commits, push ni PRs por su cuenta. /cerrar-tarea es la autorización explícita y viene con herramientas acotadas: commit, push, abrir el PR y esperar el CI. El merge solo ocurre con squash y con todos los checks en verde. Nunca push directo a main, nunca --force, nunca --admin.
Cada PR trae una sección fija, «Revisar con lupa», que señala dónde están el dinero, el stock, los permisos, el tenant y los datos sensibles de ese cambio. En la tarea de la caja (T23) apuntaba a la cuenta del esperado en el arqueo, a las ventas anuladas antes y después del cierre, a quién puede cerrar una caja y a que los logs lleven solo IDs, nunca montos. Mi revisión empieza ahí.
Los números
- 8 días desde el primer commit (del 9 al 16 de octubre de 2026).
- 42 PRs abiertos, 39 integrados.
- 161 decisiones registradas con fecha y motivo en docs/decisiones.md.
- 110+ archivos de tests entre Go y el frontend.
Lecciones
- El proceso tiene que vivir en el repo y ser ejecutable: un comando que el agente sigue vale más que una buena intención.
- Detenerse a pedir aprobación es una funcionalidad: el plan es el punto más barato para corregir el rumbo.
- Tests en rojo primero: es la única forma de saber que el test prueba algo.
- Lo que depende de disciplina se rompe con un agente. Prefiero lo que impone la herramienta: RLS en la base de datos, CSS Modules en lugar de BEM.
- La revisión humana no desaparece, se enfoca: el PR me dice dónde mirar con lupa.