Construyendo una plataforma de AI de producción con Claude Code en 30 días: La historia honesta
Eran las 2 de la mañana de un martes cuando me di cuenta de que el sistema de facturación estaba cobrando el doble a los usuarios. El bug llevaba seis horas en producción. Claude Code había generado la lógica de conciliación de pagos esa tarde, y yo la había revisado, probado y desplegado. El código parecía perfecto. Pasó todas las pruebas. Y estaba fundamentalmente roto.
Esta es la historia de la construcción de LemonData — 274 rutas de API, 46 modelos de base de datos, más de 100,000 líneas de código — con un asistente de codificación de AI. No es la historia pulida de "mira qué tan productivo te hace la AI". Es la real, con los fallos, las sesiones de debugging a las 3 de la mañana y los momentos en los que me cuestioné si el desarrollo asistido por AI era realmente una buena idea.
La promesa vs. la realidad del desarrollo asistido por AI
La promesa de los asistentes de codificación de AI es seductora: describes lo que quieres, la AI lo escribe, tú lo revisas y lo despliegas. En teoría, un solo desarrollador puede ahora hacer el trabajo de todo un equipo.
¿En la práctica? Las primeras dos semanas fueron increíbles. Claude Code entendía mi base de código, generaba funcionalidades completas, hacía refactorizaciones en varios archivos. Estaba desplegando más rápido que nunca en mi carrera. El golpe de dopamina de cerrar issues tan rápido era embriagador.
Luego empezaron a aparecer las grietas.
La misma función aparecía en tres archivos diferentes con implementaciones ligeramente distintas. Los valores de configuración estaban hardcoded en lugares aleatorios. Las definiciones de tipos se contradecían entre paquetes. La base de código crecía rápido, pero también se estaba convirtiendo en un laberinto de código que "funciona pero no sé por qué".
¿Y aquel bug de facturación? Claude había generado una función de conciliación con un aspecto perfectamente razonable. Pero no tuvo en cuenta una race condition en nuestro flujo asíncrono de confirmación de pagos. La AI no tenía forma de conocer ese edge case porque yo no se lo había dicho explícitamente, y la suite de pruebas —también generada en parte por AI— tampoco lo había cubierto.
Los siete patrones que seguían fallando
Después de un mes construyendo con Claude Code, empecé a llevar una lista. No de bugs exactamente, sino de patrones. Los mismos tipos de fallos seguían ocurriendo, y no eran culpa de Claude —o al menos, no del todo. Eran el resultado predecible de una AI optimizando para "código que funciona hoy" en lugar de "código que funciona mañana".
1. El problema de la consistencia
Claude implementaba la misma lógica de forma diferente dependiendo del archivo en el que estuviera trabajando, de los ejemplos que hubiera visto recientemente o, aparentemente, por simple variación aleatoria. Un endpoint de API devolvía { data: users }, otro devolvía { users }. Ambos funcionaban. Ninguno coincidía con el otro. El debugging se convirtió en arqueología.
2. El problema del copiar y pegar
¿Por qué una AI crearía una utilidad compartida cuando duplicar el código es más rápido y no corre el riesgo de romper la funcionalidad existente? Cada vez que pedía una nueva funcionalidad que se parecía a una existente, obtenía una implementación nueva en lugar de una solución compartida refactorizada. Después de tres semanas, tenía cinco funciones diferentes de "formatear moneda" dispersas por la base de código.
3. El problema de la deriva de tipos (Type Drift)
Se añadía un nuevo valor de estado a un archivo pero no a la definición del enum. Un campo era opcional en la respuesta de la API pero obligatorio en el tipo del frontend. TypeScript detectaba algunos de estos, pero no los desajustes semánticos: los casos en los que los tipos eran técnicamente correctos pero lógicamente inconsistentes.
4. El problema de la dispersión de la configuración
URLs de bases de datos, API keys, feature flags, límites de tasa (rate limits) — Claude los ponía donde fuera conveniente para la tarea actual. A veces en variables de entorno, a veces en un archivo de configuración, a veces hardcoded. Encontrar todos los lugares donde se definía un valor se convirtió en una búsqueda del tesoro.
5. La ilusión de la cobertura de pruebas
Las pruebas generadas por AI tienden a probar exhaustivamente el happy path y omiten por completo los edge cases. El bug de facturación fue un ejemplo perfecto: la suite de pruebas cubría maravillosamente los flujos de pago normales. Nunca probó qué sucede cuando llegan dos confirmaciones de pago en el mismo milisegundo.
6. El problema del fallo silencioso
Claude añadía bloques catch (error) { console.log(error) } que se tragaban las excepciones. En desarrollo, esto parecía estar bien: los errores aparecían en la consola. En producción, los fallos críticos se registraban silenciosamente y se olvidaban.
7. La brecha de documentación
Claude escribe excelentes comentarios de código. Escribe una documentación arquitectónica terrible. Puede explicar qué hace una función, pero no puede explicar por qué el sistema está estructurado de esa manera, o qué restricciones llevaron a una decisión de diseño particular.
La solución CLAUDE.md
El punto de inflexión llegó en la tercera semana, cuando creé CLAUDE.md — un archivo que vive en la raíz del proyecto y contiene cada convención, restricción y decisión arquitectónica que Claude necesita saber.
No es documentación para humanos. Es documentación para la AI.
## API Response Format
Always use: { success: true, data: T } or { success: false, error: string }
Never return raw data without the wrapper.
## Currency
Internal storage: USD. Display: formatCurrency(amount, currency, rate).
Never hardcode exchange rates. Never store CNY directly.
## Error Handling
Never use catch(e) { console.log(e) }.
Always use the logger: logger.error('context', { error }).
El efecto fue inmediato. Claude empezó a seguir las convenciones de forma consistente. Cuando generaba código que violaba una regla, yo podía señalar la línea específica en CLAUDE.md y se autocorregía.
Pero CLAUDE.md por sí solo no era suficiente. Necesitaba una aplicación automatizada.
Construyendo la red de seguridad: CI Gates para código generado por AI
Construimos un pipeline de CI con gates que parecerían paranoicas en una base de código tradicional, porque existen para detectar bugs generados por AI antes que los usuarios:
- Type checking en todo el monorepo (detecta la deriva de tipos)
- Auditoría SSOT que verifica que no existan implementaciones duplicadas
- Verificación de sincronización de enums que asegura que los enums de la base de datos coincidan con los enums de TypeScript
- Validación del formato de respuesta de la API (soluciona el problema de consistencia)
- Security gates para el código de facturación, permisos y autenticación code
La clave: Claude es un amplificador, no un reemplazo. Amplifica tu productividad, pero también amplifica tus errores. Si no tienes convenciones sólidas, Claude inventará las suyas, y no serán consistentes. Si no tienes comprobaciones automatizadas, los bugs de Claude llegarán a producción más rápido de lo que los bugs humanos podrían jamás.
El bug de facturación ya no podría ocurrir. No porque Claude se volviera más inteligente, sino porque el pipeline ahora requería un manejo explícito de las race conditions asíncronas, verificado por un gate que comprobaba el bloqueo (locking) adecuado en los flujos de pago.
Qué significa realmente el "Desarrollo Nativo de AI"
Cuando digo que LemonData es "Infraestructura Nativa de AI", no me refiero a que añadimos funciones de AI a un producto existente. Me refiero a que todo el proceso de desarrollo fue moldeado por la realidad de trabajar con un compañero de codificación de AI.
Nuestra documentación es más detallada de lo que sería de otra manera, porque Claude necesita un contexto explícito que un compañero humano podría inferir. Nuestro sistema de tipos es más estricto de lo necesario, porque Claude explotará cualquier ambigüedad. Nuestro pipeline de CI tiene gates que parecerían paranoicas en una base de código tradicional, porque existen para detectar bugs generados por AI antes que los usuarios.
El resultado es una base de código que es, de hecho, más mantenible que la mayoría en las que he trabajado. No porque la AI escriba mejor código que los humanos, sino porque construir para el desarrollo asistido por AI me obligó a hacer explícitas todas las convenciones y comprobaciones que normalmente solo viven en la cabeza de los desarrolladores senior.
Para más información sobre lo que significa AI Native como filosofía, consulta ¿Qué es AI Native?
Lecciones para desarrolladores que construyen con asistentes de codificación de AI
Si estás empezando un proyecto con Claude Code, Cursor o cualquier asistente de codificación de AI:
- Crea tu CLAUDE.md el primer día — no en la tercera semana como hice yo
- Automatiza la aplicación de convenciones — no confíes en que la AI recordará las reglas
- Revisa el código de la AI como si lo hubiera escrito un desarrollador junior — es rápido y capaz, pero carece de contexto
- Prueba los edge cases manualmente — las pruebas generadas por AI cubren los happy paths, no las race conditions
- Centraliza la configuración desde el principio — el problema de la dispersión se agrava rápido
- Usa TypeScript estricto — es tu mejor defensa contra la deriva de tipos
- Construye CI gates pronto — se pagan solas en la primera semana
¿Lo volvería a hacer?
Absolutamente. Pero empezaría con CLAUDE.md el primer día en lugar de la tercera semana. Y recordaría que el multiplicador de productividad de 10x incluye un multiplicador de 10x en las consecuencias de los errores.
La plataforma que construimos — más de 300 modelos de AI, API unificada, facturación multimoneda, internacionalización en 13 idiomas — le habría tomado meses a un equipo tradicional. Nosotros la lanzamos en 30 días. Los bugs fueron reales, pero la velocidad también lo fue.
El desarrollo asistido por AI no es magia. Es un nuevo tipo de disciplina de ingeniería. Y como todas las disciplinas, recompensa a quienes respetan sus restricciones.
FAQ
¿Puede realmente un solo desarrollador construir una plataforma de producción con Claude Code?
Sí, pero con matices. La AI maneja la generación de código y la refactorización a una velocidad increíble, pero aún necesitas un sólido juicio arquitectónico, gates de calidad automatizados y la disciplina para revisarlo todo cuidadosamente. La velocidad de 10x incluye bugs 10x más rápidos si no tienes cuidado.
¿Qué es CLAUDE.md?
CLAUDE.md es un archivo de instrucciones a nivel de proyecto que los asistentes de codificación de AI leen para obtener contexto. Contiene convenciones de codificación, decisiones arquitectónicas y restricciones que la AI debe seguir. Piénsalo como la documentación de onboarding para tu compañero de AI.
¿Cómo se previenen los bugs generados por AI en producción?
Los CI gates automatizados son esenciales: type checking, auditorías SSOT, verificación de sincronización de enums y gates de seguridad específicos del dominio. La idea clave es que la AI amplifica tanto la productividad como los errores; necesitas comprobaciones automatizadas para detectar los errores amplificados.
¿Es adecuado el desarrollo asistido por AI para sistemas de facturación y pago?
Sí, pero con precaución adicional. El código de pagos necesita un manejo explícito de race conditions, un bloqueo (locking) adecuado y pruebas exhaustivas de edge cases. Las pruebas generadas por AI tienden a cubrir los happy paths; debes probar manualmente los escenarios de fallo y las operaciones concurrentes.
LemonData te da acceso a más de 300 modelos de AI a través de una única API. Lo construimos con AI, para servir a la AI. Empieza gratis — los nuevos usuarios reciben $1 en créditos.
