01 Qué es y por qué separar diseño y construcción
Cuando le pides a un agente que «haga una app», decide sobre la marcha cientos de cosas que nadie le ha dicho: quién ve qué datos, qué pasa al borrar, qué versión de cada librería usar. El resultado parece completo, pero está lleno de suposiciones.
The Architect separa los dos trabajos. Primero diseña contigo y deja todo por escrito en un blueprint en Markdown. Después, otra sesión de Claude Code, sin memoria de la conversación, abre ese archivo y construye paso a paso. Si el plano obliga a preguntar algo, el plano está mal.
Tú describes
Qué quieres construir, para quién y con qué restricciones.
The Architect diseña
Clasifica el proyecto, elige stack, comprueba versiones y escribe el plano.
Claude Code construye
Lee el plano y ejecuta cada paso hasta que su verificación pasa.
02 Instalación
La forma recomendada es como plugin. Dentro de cualquier sesión de Claude Code, añade el catálogo del autor e instala:
/plugin marketplace add Hainrixz/the-architect
/plugin install the-architect@soyenriquerochaSi la sesión ya estaba abierta, ejecuta /reload-plugins para cargarlo sin reiniciar. A partir de ahí puedes usar /architect en cualquier carpeta, y los planos se guardan en ./blueprints/ del directorio en el que trabajes.
También funciona clonando el repositorio y abriendo Claude Code dentro: lee el CLAUDE.md y sigue el mismo flujo, aunque sin los comandos ni los subagentes del plugin.
git clone https://github.com/Hainrixz/the-architect.git
cd the-architect
claude03 Los comandos y cuándo usar cada uno
| Comando | Cuándo |
|---|---|
| /architect | Proyecto nuevo que vas a dejar construir a un agente sin supervisión. Entre 12 y 16 preguntas. |
| /architect-quick | Ya conoces el stack o el proyecto es pequeño. Tres preguntas y valores por defecto que puedes vetar. |
| /architect-brownfield | Un cambio, una integración o una migración sobre código que ya existe. |
| /architect-next | Retomar una construcción: muestra la siguiente tarea desbloqueada con su verificación. |
| /architect-refresh | Revisar las versiones fijadas de un plano antiguo contra los registros actuales. |
| /architect-audit | Volver a pasar el validador sobre un plano existente. |
04 Cómo trabaja: cuatro fases y dos controles
-
1
Descubrimiento
Pregunta si el código es nuevo o existente y encaja el proyecto en una de sus 14 formas: SaaS, web de contenidos, app móvil, API, herramienta interna, tienda online, agente, extensión, automatización, pipeline de datos y otras.
-
2
Profundización
Preguntas específicas de esa forma. Un subagente comprueba cada versión de librería en los registros oficiales.
-
3
Arquitectura
Un único mensaje con el stack, cómo encaja todo, qué entra en la primera versión y qué queda fuera. Aquí pasan los dos controles.
-
4
Generación
Un subagente escribe el plano y otro lo audita hasta que da PASS. Tarda entre 10 y 30 minutos sin mostrar nada; es normal.
Control A: nada sin decidir
Marca cada decisión ambigua y no avanza hasta que la respondes, aceptas un valor por defecto o la declaras fuera de alcance.
Control B: pre-mortem
Ataca el plan desde ocho ángulos (supuestos, mercado, competencia, economía, ejecución…). Lo que sobrevive se convierte en riesgo documentado o en exclusión.
05 Qué obtienes
Un plano de 20 secciones donde cada paso de construcción tiene cuatro campos: qué hacer, cuándo está terminado, cómo se verifica (comandos con el resultado esperado) y un punto de control en git para volver atrás. Los criterios se escriben en formato EARS: «CUANDO ocurre X, EL SISTEMA DEBE hacer Y». Frases como «funciona bien» están prohibidas y el validador las rechaza.
Si el plan tiene 12 pasos o más, genera una carpeta con el plano, un tasks.json con las dependencias, épicas y un workspace/ con el CLAUDE.md y la configuración que el constructor copia a la raíz del proyecto. Con menos pasos, un único archivo.
/architect Quiero una aplicación web para que una clínica de fisioterapia gestione reservas online. Pacientes: reservan, cancelan hasta 24 h antes y reciben recordatorio por email. Fisioterapeutas: ven su agenda y bloquean huecos. Administración: informes mensuales. Pagos con tarjeta por adelantado. Cumplimiento de RGPD obligatorio. Presupuesto de hosting bajo.Lee blueprints/[nombre-del-proyecto]/blueprint.md completo antes de tocar nada. Ejecuta los pasos en orden. No pases al siguiente hasta que todos los criterios de «Done when» se cumplan y los comandos de «Verify» den el resultado esperado. Haz el commit y la etiqueta del «Checkpoint» al terminar cada paso. Si algo del plano es imposible, detente y explícame qué y por qué en vez de improvisar.06 Trabajar sobre código existente
Con /architect-brownfield empieza leyendo tu repositorio: lenguaje, framework, convenciones, base de datos, tests, CI y los CLAUDE.md o AGENTS.md que ya tengas, que mandan sobre sus propios valores por defecto. Te enseña ese mapa para que lo corrijas antes de diseñar. No propone reescribir código que funciona y no le has pedido tocar; en migraciones añade un plan de convivencia, criterios para abortar y retirada del sistema antiguo.
/architect-brownfield Necesito añadir facturación con suscripciones mensuales a esta aplicación. Antes de preguntarme nada, mapea el repositorio y enséñame lo que has entendido de la estructura, la base de datos y los tests para que lo corrija.07 Límites y buenas prácticas
- ✓No escribe código de la aplicación: solo diseña. Necesitas una segunda sesión para construir.
- ✓La generación tarda y consume uso de tu plan; evita lanzarla para cambios triviales.
- ✓Si una versión no se puede verificar, el plano dice «verificar antes de instalar» en lugar de inventarla: revísalo.
- ✓Lo que exige una persona (revisión de una tienda de apps, firma de un contrato) va a una lista de lanzamiento, no a los criterios automáticos.
- ✓Guarda los planos en git junto al proyecto: son la documentación de por qué se decidió cada cosa.
Preguntas frecuentes
El modo plan produce un plan para la misma sesión. The Architect produce un documento autocontenido, auditado y con criterios comprobables por script, pensado para que otra sesión sin contexto lo ejecute.
Sí. Contempla apps móviles, extensiones de navegador, aplicaciones de escritorio, CLI y servidores MCP, automatizaciones y pipelines de datos, entre otras formas.
Sí. La entrevista se hace en el idioma en el que le escribas.
Pásales /architect-audit para ver qué pasos no tienen criterio de terminado y /architect-refresh para actualizar versiones. Si aún no has empezado a construir, suele compensar regenerarlo.
Sobre el autor
Equipo editorial de appyweb
Marketing, SEO y desarrollo con IA
Especialistas de appyweb en SEO, publicidad, desarrollo web y automatización con IA.