Análisis de arquitectura full stack con Claude Code

Usar correctamente a Claude Code acelera el entendimiento de una base de código y prepara un entorno local en minutos. Aquí verás cómo obtener una big picture de una arquitectura full stack, documentarla en memoria persistente y levantar el backend con Docker de forma segura.

¿Cómo entender la arquitectura full stack con Claude Code?

Con el editor abierto, se carga el proyecto con tres carpetas: backend, frontend y móvil. Desde Claude Code, se redacta un prompt claro para que analice la estructura y ofrezca un resumen de arquitectura. La clave está en usar menciones a archivos y carpetas con arroba para dar contexto y alcance del análisis.

¿Qué prompt y menciones usar para el análisis?

• Indicar que hay múltiples proyectos dentro del repo.
• Mencionar carpetas: backend, frontend y móvil.
• Pedir una big picture completa: componentes, relaciones y flujo de peticiones.
• Autorizar comandos de lectura seguros cuando el asistente lo solicite.

Resultado: Claude Code explora el directorio raíz, examina cada componente y prepara un informe de la arquitectura.

¿Qué detecta del backend, frontend y móvil?

• Backend en Python con FastAPI y base de datos Postgres. Modelos y endpoints listados con claridad.
• Frontend con Next.js, soporte de Server Side Rendering y Server Side Generation, responsive design con grid “estilo Netflix”, integración con la API vía Fetch y navegación dinámica.
• Móvil para Android y iOS, explicando el ciclo de vida del request: apps cliente piden al backend, que a su vez accede a la base de datos.

Este análisis end-to-end muestra cómo fluye una petición desde cualquier cliente hasta la base de datos y de vuelta. Es claro, accionable y completo.

¿Cómo se guarda la memoria en cloud.md?

Con el análisis listo, se solicita: crear y guardar el archivo cloud.md en la raíz como memoria del proyecto.

• En el editor, se revisa la propuesta antes de aceptar.
• Se confirma que describe arquitectura, stacks, estructura de carpetas y relaciones.
• Tras aceptar, el archivo queda disponible como referencia continua.

Beneficio: memoria persistente para el equipo y para futuras automatizaciones con Claude Code.

¿Cómo configurar el entorno local del backend con Docker y Make?

El objetivo es tener el servicio backend corriendo en local. Claude Code puede ejecutar comandos de CLI con permiso explícito del usuario, lo que hace el proceso más rápido y auditado.

¿Qué permisos y verificaciones hace Claude Code?

• Verifica versión de docker y docker compose antes de iniciar.
• Ofrece opciones: permitir una vez, permitir comandos de Docker durante el proyecto o rechazar.
• Entra al directorio backend, detecta un archivo Makefile y propone usar make start.

Este flujo mantiene el control del usuario y documenta cada paso en la conversación.

¿Cómo resolver el error del daemon de Docker?

Si make start falla porque el daemon no corre, Claude Code actúa con feedback inmediato:

• Inicia Docker en el sistema y espera con un sleep breve.
• Ejecuta docker ps para confirmar que está activo.
• Continúa con el levantamiento de contenedores y la verificación de servicios.
• Revisa make logs. Como los logs quedan en espera, permite enviarlos a background con Control B y continuar.

Ventaja: manejo automático de bloqueos sin perder trazabilidad.

¿Cómo validar servicios, migraciones y datos?

• Ejecuta migraciones de base de datos cuando se requiera.
• Corre seeds de datos. Si existe información previa, usa seed fresh para recrearla.
• Lanza peticiones con curl a varios endpoints para comprobar respuestas esperadas.

Resultado: backend operando localmente, con datos de prueba y endpoints saludables.

¿Qué buenas prácticas y riesgos considerar al ejecutar comandos?

Aunque Claude Code propone comandos, el usuario mantiene la aprobación final. Esto fomenta seguridad y evita acciones destructivas.

¿Cómo revisar comandos antes de aceptar?

• Confirmar que los comandos son de lectura, verificación o despliegue controlado.
• Evitar cualquier instrucción que modifique archivos críticos o elimine datos del sistema.
• Supervisar make start, make logs, migraciones, seeds y pruebas con curl.

Esta revisión rápida reduce riesgos y asegura un entorno confiable.

¿Qué ventajas ofrece la memoria cloud.md para el equipo?

• Documenta la arquitectura, el stack y las relaciones entre componentes.
• Sirve de base para onboarding y para nuevos desarrollos.
• Mantiene contexto útil para próximos prompts y automatizaciones.

¿Te gustaría que preparemos un prompt base para extender la memoria en cloud.md con decisiones de diseño o convenciones de código? Comparte en comentarios qué te interesa documentar a continuación.