Claude Code sin improvisar: arquitectura, método de agentes y validación humana para no programadores

El problema no es Claude Code. Eres tú usando mal la herramienta

Un bombero de 44 años sin formación técnica construyó una app iOS que acabó en la App Store usando Claude y Gemini. No porque sea un genio ni porque tenga un máster en ciencias de la computación guardado en un cajón. Porque aprendió a estructurar el trabajo antes de pedirle nada a la IA.

Eso es exactamente lo que distingue una aplicación que aguanta de una chapuza que se cae a los tres meses: lo que haces antes de escribir el primer prompt.

La mayoría de la gente llega a Claude Code, le describe vagamente lo que quiere y espera que el agente haga magia. Y el agente la hace, en el sentido de que genera código que compila y parece funcionar. El problema es que ese código está construido sobre arena: sin pensar en concurrencia, sin gestionar bien los roles, sin idempotencia, sin deduplicación. Todo eso suena a jerga técnica de paper, pero se traduce en una cosa muy concreta: tu app explota cuando dos usuarios hacen lo mismo al mismo tiempo, o empieza a guardar datos duplicados, o simplemente se vuelve imposible de mantener cuando quieres añadir una feature nueva.

Este artículo no es sobre qué es Claude Code ni sobre su arquitectura interna. Es sobre cómo usarlo de puta madre para construir cosas que funcionen, incluso si no eres programador.

Paso 1: Diseña la arquitectura antes de abrir Claude

Esta es la regla más importante y la que más gente salta. No arranques Claude hasta que tengas claro en papel qué estás construyendo.

No es burocracia. Es que el contexto de un agente de IA es finito y caro. Si le mandas construir sin rumbo, el agente toma decisiones de diseño sobre la marcha, decisiones que después son difíciles de revertir y que acumulan deuda técnica desde el primer día.

¿Qué escribes en ese documento previo?

• Qué hace tu app: no "una app de gestión", sino "los usuarios crean proyectos, cada proyecto tiene tareas, cada tarea tiene un responsable y un estado". Cuanto más concreto, mejor.
• Qué datos necesitas guardar: lista las entidades principales. Proyectos, usuarios, tareas. Piensa en las relaciones: un usuario tiene muchos proyectos, un proyecto tiene muchas tareas.
• Qué pasará cuando tengas 1.000 usuarios simultáneos: no para que lo resuelvas ahora, sino para que no diseñes algo que sólo escala hasta 10.
• El stack: si es backend de datos, Python + FastAPI + PostgreSQL es un estándar probado. Si habrá interfaz de usuario, decide el framework de frontend antes de que Claude lo elija por ti (porque lo elegirá, y puede que elija algo que no encaja con lo que necesitas).
• Las pantallas principales: no un diseño de UX elaborado. Solo un boceto de qué ve el usuario en cada paso y cómo navega entre secciones.
• Qué datos querrás analizar en 6 meses: esto es clave y casi nadie lo piensa al principio. Si en 6 meses querrás saber cuántos usuarios activos tienes por semana, necesitas guardar las fechas de actividad correctamente desde el día uno. Si no lo piensas ahora, lo pagarás caro después.

El papel aguanta. El contexto del agente, no. Si no tienes esto escrito antes de empezar, Claude te va a construir funciones que parecen útiles pero que están conectadas por los huevos y se rompen en cuanto el proyecto crece.

Paso 2: El prompt de auditoría con rol de senior

Tienes tu diseño en papel. Ahora sí, abres Claude. Pero no para construir: para auditar lo que has diseñado tú.

Este paso es el que más valor aporta por unidad de tiempo invertida. Toma tu esquema de tablas, tu stack elegido y tu descripción de funcionalidad, y usa este prompt:

Actúa como arquitecto de software senior con 15 años de experiencia.
Revisa esta arquitectura e identifica:
- Vulnerabilidades de seguridad
- Problemas de concurrencia
- Limitaciones de rate limiting
- Falta de idempotencia y deduplicación
- Problemas de escalado a medio plazo
- Scope de roles y permisos si la app tendrá múltiples usuarios

Dame una lista priorizada de cambios antes de escribir una línea de código.
Piensa a 2 años vista.

Pega tu esquema debajo y espera.

Cuando añades "piensa a 2 años vista", Claude cambia el registro completamente. En vez de optimizar para que funcione hoy, empieza a señalar los cuellos de botella que ahora mismo no ves porque estás en modo "quiero que esto funcione ya".

Algunos conceptos que aparecerán y que conviene entender mínimamente:

Idempotencia: si el mismo usuario pulsa "guardar" dos veces seguidas (porque la conexión tardó), ¿tu sistema guarda el dato una o dos veces? Si guarda dos, tienes un problema de idempotencia. Una operación idempotente produce el mismo resultado si se ejecuta una o cien veces.

Rate limiting: cuántas peticiones puede hacer un usuario en un tiempo dado. Sin límite, un script malicioso puede tumbar tu servidor en segundos.

Concurrencia: qué pasa cuando dos usuarios modifican el mismo registro al mismo tiempo. Sin gestión de concurrencia, uno sobreescribe al otro y nadie se entera.

No necesitas saber implementar esto. Necesitas saber que existe para poder pedirle a Claude que lo contemple en el diseño.

El trabajo de auditoría antes de programar una sola línea de código es el 80% de la diferencia entre un proyecto que escala y uno que explota.

Paso 3: CLAUDE.md y la carpeta /docs, la memoria que no pierde el hilo

Claude Code no tiene memoria persistente entre sesiones. Cada vez que abres una conversación nueva, parte de cero. Si no tienes un sistema para pasarle el contexto, cada mañana el agente empieza a repetir errores que ya resolviste la semana pasada.

La solución es simple: un archivo CLAUDE.md en la raíz del proyecto y una carpeta /docs con tres archivos.

CLAUDE.md contiene las reglas del proyecto: stack elegido, convenciones de nombres de variables y funciones, restricciones (por ejemplo, "nunca uses librerías externas sin preguntarme primero"), y la descripción del proyecto en tres frases. Claude Code lo lee automáticamente al inicio de cada sesión. Es lo primero que tiene el agente antes de hacer nada.

La carpeta /docs tiene tres archivos:

• backlog.md: lista de funcionalidades pendientes, ordenadas por prioridad. No un documento de 40 páginas; una lista viva que actualizas.
• decisions.md: cada decisión arquitectónica importante y el porqué. "Elegimos PostgreSQL en vez de MySQL porque necesitamos soporte de JSONB para los metadatos." Si en tres meses alguien pregunta por qué está así, tienes la respuesta.
• state.md: dónde lo dejaste al final de cada sesión. "Implementé el endpoint de creación de usuarios. Pendiente: validación de email y gestión de tokens."

Empieza cada sesión nueva con este prompt: "Lee CLAUDE.md y docs/state.md antes de hacer nada."

Sin esto, el contexto se degrada. El agente empieza a usar nombres de variables que no siguen las convenciones, a reintroducir bugs que ya habías corregido, a tomar decisiones que contradicen las que tomaste hace dos semanas. Es exactamente el mismo problema que tener un equipo de desarrolladores que no se comunican entre ellos.

Paso 4: El método de agentes por tarea, por qué un solo agente lo pudre todo

Aquí está uno de los errores más comunes y menos evidentes: usar un único agente para todo el proyecto, desde la planificación hasta el testing, en sesiones interminables.

El problema es técnico. Los modelos de lenguaje tienen una ventana de contexto, la cantidad de información que pueden manejar a la vez, y cuando esa ventana se llena con el historial de una sesión larga, la calidad del output cae. El agente empieza a "olvidar" decisiones tomadas al principio de la conversación, a contradecirse, a generar código inconsistente que parece escrito por tres personas distintas que nunca se hablaron.

La solución es dividir el trabajo en agentes especializados con roles concretos:

Agente de planificación: recibe el CLAUDE.md, el state.md y el backlog. Su único trabajo es decidir qué tarea se acomete en esta sesión y descomponerla en pasos. No codifica.

Agente de desarrollo: recibe el output del agente de planificación y las instrucciones específicas de la tarea. Codifica y nada más.

Agente de debugging: cuando algo falla, recibe el código problemático y el mensaje de error. Su contexto está limpio de toda la historia del proyecto; solo ve el problema concreto.

Agente de testing: recibe el código generado y su único trabajo es generar tests y detectar casos edge que el agente de desarrollo no contempló.

Claude Code no tiene un comando slash dedicado para lanzar subagentes manualmente: los crea de forma automática internamente mediante su Agent tool. Cuando el agente principal detecta una subtarea independiente, crea un subagente con su tipo, prompt y parámetros propios; ese subagente opera con contexto propio y devuelve un resultado estructurado al agente principal. Si varias subtareas no dependen entre sí, Claude Code las lanza en paralelo sin que tengas que hacer nada.

Existen tres tipos de subagentes que Claude Code usa internamente:

• General-purpose: acceso completo (lectura, escritura, ejecución de comandos). Es el que hace el trabajo de construcción real.
• Explore: solo lectura. Lo usa para entender el código antes de modificarlo. Tiene tres niveles de profundidad: quick (5-15 segundos) para localizar un archivo o función, medium (15-45 segundos) para entender un módulo, y very thorough (45-120 segundos) para auditorías completas.
• Plan: solo lectura. Genera un plan de implementación detallado sin escribir una línea de código.

Si quieres ver todos los subagentes y tareas activos en la sesión actual, el comando /tasks los lista. Y si necesitas configurar subagentes personalizados para tu proyecto, puedes hacerlo editando archivos en .claude/agents/ dentro del repositorio, o en ~/.claude/agents/ para configuraciones globales.

Shortcuts Playground, un plugin open source para Claude Code, implementa el patrón de agente revisor que valida la sintaxis y notifica errores al agente principal, cerrando el bucle de verificación sin intervención humana constante.

El principio que articula todo esto viene de Andrej Karpathy, cofundador de OpenAI, que acuñó el concepto de vibe coding y lo resume en tres ideas: la IA es un fantasma sin ego ni memoria, su inteligencia es irregular (sobrehumana en una tarea, débil en otra), y solo se debe confiar en ella hasta donde el resultado pueda comprobarse. Ese último punto es el verification loop: cuanto más comprobable sea una tarea, pruebas automáticas, archivos que se pueden inspeccionar, números que se pueden verificar, más puedes delegar. Donde no puedes comprobar, el juicio es humano.

La delegación sin posibilidad de verificación es exactamente lo que convierte el vibe coding en deuda técnica acumulada.

Si quieres entender más sobre cuándo tiene sentido usar herramientas de orquestación frente a código propio en estos flujos, el análisis de n8n vs. código directo cubre bien ese trade-off.

Paso 5: El archivo de skills del proyecto, instrucciones que no se repiten

Hay una feature de Claude que los no programadores raramente usan y que cambia radicalmente la consistencia del trabajo: las skills.

Una skill es una carpeta con instrucciones que le dices a Claude para que siempre realice una tarea de la misma forma. El archivo central es SKILL.md con un encabezado YAML que define el nombre y la descripción. Opcionalmente puede incluir scripts de referencia, ejemplos y assets.

Para un proyecto de desarrollo, puedes crear skills por tipo de tarea:

• Una skill dev-planning con las instrucciones de cómo descomponer una feature en tareas.
• Una skill dev-debugging con el proceso estándar de debugging: leer el error, identificar el archivo, proponer hipótesis antes de cambiar nada.
• Una skill dev-testing con las convenciones de testing del proyecto.
• Una skill dev-task-closure con el checklist de cierre de tarea: actualizar state.md, anotar decisiones en decisions.md, marcar la tarea en backlog.md.

Lo importante sobre cómo Claude carga las skills: primero lee solo el nombre y la descripción del frontmatter YAML para decidir si aplica. Si aplica, carga el cuerpo completo de SKILL.md. Solo si necesita más contexto, accede a los archivos de referencia adicionales. Esto significa que la descripción del frontmatter es lo más crítico: tiene que dejar claro en una frase cuándo se usa esa skill.

Para usar skills en Claude Code, creas la carpeta en ~/.claude/skills/<nombre>/ para skills globales, o en <repo>/.claude/skills/ para skills específicas del proyecto. El repositorio del proyecto es la ubicación correcta si las convenciones son propias de ese proyecto y no quieres que se mezclen con otros.

Paso 6: Validación humana, por qué necesitas entender lo mínimo aunque no sepas programar

Aquí viene la parte que más incomoda a la gente que llega al vibe coding pensando que es magia: no puedes delegar la validación.

No necesitas saber programar. Necesitas entender lo suficiente para saber si lo que generó Claude hace lo que pediste. Hay una diferencia importante entre saber escribir código y saber leerlo con criterio.

Los fundamentos mínimos que necesitas:

Qué es una API y qué hace un endpoint: una API es la puerta de entrada a tu aplicación desde el exterior. Un endpoint es una dirección específica dentro de esa puerta. Cuando tu app móvil le pide al servidor la lista de tareas del usuario, está llamando a un endpoint. Necesitas saber cuáles existen en tu proyecto y qué hace cada uno.

Qué es una tabla SQL y por qué importa el tipo de dato: una tabla es como una hoja de cálculo en tu base de datos. Cada columna tiene un tipo: texto, número, fecha, booleano. Si guardas una fecha como texto, después no puedes hacer operaciones con ella. Necesitas revisar que los tipos de las columnas tengan sentido para lo que vas a hacer con esos datos.

Qué es una foreign key: es el mecanismo que relaciona una fila de una tabla con una fila de otra. Si tu tabla de tareas tiene una columna proyecto_id, esa columna es una foreign key que apunta a la tabla de proyectos. Necesitas verificar que estas relaciones estén bien definidas porque si no lo están, puedes borrar un proyecto y quedarte con tareas huérfanas que nadie puede ver.

La forma práctica de hacer esto sin saber programar: pide a Claude que te explique cada bloque de código en lenguaje llano antes de ejecutarlo. No "explícame qué hace esta función línea por línea" sino "explícame qué problema resuelve este código y qué pasa si falla".

Si la explicación no tiene sentido o si Claude empieza a dudar, es una señal de que algo no está bien diseñado.

Si saltas la validación humana, firmas código que parece funcionar pero que guarda datos duplicados o se cae cuando dos usuarios hacen lo mismo al mismo tiempo.

El material del curso lo dice claro: Claude Code no sustituye la necesidad de tener claro el objetivo, explicarlo bien, revisar y validar resultados. La IA genera; tú validas. Ese es el contrato.

Para entender mejor qué separa a alguien que realmente construye cosas funcionales con IA de alguien que solo prompta, el artículo sobre AI Engineer real desarrolla por qué los fundamentos de data engineering y backend no son opcionales aunque uses IA para el código.

Errores comunes que destrozan proyectos antes de que empiecen

Diseñar sobre la marcha. Decirle a Claude "empieza a construir" sin arquitectura previa es el error más caro. El agente construye algo que funciona hoy y acumula deuda técnica que explotas en tres meses. No es culpa de Claude; es que no tenía información suficiente para tomar buenas decisiones de diseño.

Un único agente para todo el proyecto. Es la forma más rápida de obtener código inconsistente. El contexto se degrada, el agente "olvida" decisiones anteriores y el output de la sesión 20 no tiene nada que ver con el de la sesión 1.

No versionar el proyecto. Si no usas Git desde el primer commit, cada vez que Claude rompe algo no tienes forma de volver al estado anterior. Git no es opcional; es la red de seguridad que te permite experimentar sin miedo.

Pedir la feature completa en un solo prompt. Los mejores resultados salen de tareas pequeñas y concretas, con verificación entre cada una. "Implementa el sistema de autenticación completo" es una instrucción que garantiza código mediocre. "Crea el endpoint de registro de usuario con validación de email y devuélveme el código antes de integrarlo" es una instrucción que puedes revisar y aprobar.

Confundir "compila" con "funciona". Que el código no dé errores al ejecutarse no significa que hace lo que necesitas. Necesitas probar los casos edge: qué pasa si el usuario deja un campo vacío, qué pasa si pulsa el botón dos veces seguidas, qué pasa si dos usuarios editan el mismo registro a la vez.

Preguntas frecuentes

¿Necesito saber programar para usar Claude Code?

No necesitas saber programar, pero sí necesitas entender los fundamentos: qué es una API, qué hace un endpoint, cómo funciona una tabla SQL y qué es una foreign key. Sin esos mínimos, no puedes validar el código que genera la IA y firmas ciegamente algo que puede parecer funcional pero guardar datos duplicados o romperse bajo carga. La IA genera; el criterio para validar lo pones tú.

¿Cuántos agentes necesito para un proyecto pequeño?

Para un proyecto pequeño bastan tres: uno de planificación (qué hacer y cómo descomponerlo), uno de desarrollo (que codifica) y uno de revisión o debugging (para cuando algo falla). El principio clave es no mezclar roles en la misma sesión larga: el contexto se degrada y la calidad del código cae. Cada agente arranca con el contexto limpio y una tarea concreta.

¿Qué diferencia hay entre Claude Code y usar Claude en el navegador para programar?

Claude en el navegador es conversacional: responde preguntas, genera código que copias manualmente y no toca tu sistema. Claude Code trabaja directamente en tu equipo: lee archivos, los edita, ejecuta comandos y sigue hasta terminar la tarea. Para construir un proyecto real necesitas Claude Code; el chat del navegador no puede interactuar con tu base de datos, tu sistema de archivos ni ejecutar pruebas.

¿Qué pasa si no creo el archivo CLAUDE.md ni la carpeta /docs?

Cada sesión nueva parte de cero. El agente no recuerda las convenciones del proyecto, las decisiones tomadas ni dónde lo dejaste. El resultado práctico: errores repetidos que ya habías corregido, nombres de variables inconsistentes y decisiones de diseño contradictorias entre sesiones. El CLAUDE.md y los archivos de /docs son la memoria persistente que el agente no tiene por sí mismo.