Un plano que otro Claude construye sin hacerte una sola pregunta.

Dicho sin la metáfora: es un meta-agente. No construye tu producto, construye las instrucciones con las que tu producto se construye. Te entrevista, elige el stack, ordena el trabajo y entrega un documento.

Y ese documento está escrito para que lo lea una máquina antes que tú. Cada paso trae qué archivos crear, cómo se sabe que quedó, el comando que lo comprueba y el punto al que se regresa si el paso siguiente sale mal.

Tres tiempos, tres papeles

El reparto es lo primero que conviene tener claro, porque los tres papeles se suelen confundir en uno solo: tú pones la idea, The Architect pone las decisiones, y una sesión distinta de Claude Code pone el código.

tú lo describes           →  «una app de reservas para barberías»,
                             en tus palabras y sin formato

The Architect lo diseña   →  te entrevista, elige el stack, verifica
                             cada versión y escribe el plano

Claude Code lo construye  →  sesión nueva y sin contexto: abre el
                             plano y ejecuta paso por paso

El tercer renglón es el que casi nadie espera: quien construye no es la sesión que diseñó. Abres una nueva, en la carpeta del proyecto, y lo único que recibe es el plano.

Dónde empieza y dónde se detiene

La confusión más cara con esta herramienta es pedirle código. No lo escribe, y no es algo que le falte: es la decisión que la hace servir. Diseñar y construir son dos trabajos distintos, y mezclarlos en uno es lo que produce proyectos que se leen muy bien y no corren.

Sirve igual para código nuevo y para código que ya existe. En el segundo caso lo primero que hace, antes de preguntarte nada, es leer tu repo y enseñarte lo que entendió para que lo corrijas. Cuál comando te toca en cada caso viene más abajo.

Por qué no es lo mismo que pedirle que «planee»

Claude ya planea si se lo pides. El problema no es la calidad del plan: es dónde vive. Vive en la conversación. Cierras la ventana, se compacta el contexto o simplemente pasan tres días, y ese plan se fue con la sesión. Lo que queda es tu memoria de lo que habían acordado.

El plano es un archivo. Se guarda junto a tu proyecto, se versiona con git, se lee meses después y se puede auditar y actualizar con un comando. Y sobre todo: una sesión nueva —sin memoria de ti y sin una línea de la charla anterior— lo abre y construye sin hacerte una sola pregunta. Ese es el examen del plano, y es justo lo que la versión 2.5 se puso a medir siete veces seguidas.

Los dos sirven, para momentos distintos: el modo plan es para el rato en que estás sentado frente a la sesión, y el plano es para lo que pasa cuando ya no estás. Cuándo te toca cada uno está en Planea antes del automático.

Dos formas de tenerlo, una sola cabeza

Como plugin es la forma completa. Dos comandos en la terminal y queda disponible en cualquier carpeta tuya, con seis slash commands —los atajos que se escriben con una diagonal al inicio— y tres subagentes, que son ayudantes con su propio contexto aparte para no inundar el hilo de la entrevista con lo que van leyendo.

Clonado es la misma cabeza en modo conversación. Bajas el repo, abres Claude Code dentro de esa carpeta y él lee el CLAUDE.md del proyecto: misma entrevista, los mismos dos gates —los filtros obligatorios que bloquean la generación hasta que el diseño esté cerrado— y la misma salida. Lo único que el clon no trae son los slash commands y los subagentes, porque esos dos solo existen empaquetados como plugin.

En cualquiera de los dos modos los prerrequisitos son los mismos y son dos: Claude Code y una suscripción de Claude. No hay llave de API que conseguir ni nada más que pagar.

Escriba lo que escriba, todo cae en el mismo lugar: una carpeta ./blueprints/ dentro de la carpeta donde corriste el comando, nunca dentro del plugin. Así el plano se queda con tu proyecto y viaja con él.

Si conociste The Architect como una carpeta que clonabas y copiabas a mano, esa versión ya no es la que corre. Hoy es un plugin, y el salto de la v1 a la v2.5 no es una función más en la lista: cambió lo que se le exige al plano antes de que llegue a tus manos.

Abajo están las diez diferencias concretas. La que más pesa no es el conteo de comandos ni el de secciones: es que en la v1 nadie comprobaba el plano. Se entregaba y ya.

Diez diferencias entre la v1 y la v2.5

La columna izquierda es la carpeta que clonabas. La derecha es el plugin que instalas hoy.

Nada de esa tabla es nuevo de la 2.5: así estaba desde la 2.0. Lo que hizo la 2.5 fue otra cosa — dejó de afirmar que todo eso funciona y se puso a comprobarlo.

El montaje: un agente escribe el plano, otro intenta construirlo

El experimento es fácil de describir e incómodo de aprobar. Un agente sin contexto previo genera un plano desde el plugin. Otro agente, también sin contexto, lo abre en una sesión limpia e intenta construir el proyecto con comandos reales. Nadie le explica nada por fuera. Si el plano no lo dice, no existe.

Desde el ciclo 4 ese constructor corre en modo literal estricto: tiene prohibido trabajar alrededor de un defecto y prohibido rellenar lo que el plano no diga. Cuando algo no cuadra, se detiene y lo anota como desviación en lugar de resolverlo por su cuenta. Esa prohibición es lo que convierte el ejercicio en una medición y no en una demostración.

El prompt con el que corre ese constructor es el mismo que puedes copiar en la sección 09, y es la pieza más reutilizable de todo esto: sirve para cualquier plano, no solo para los de aquí.

Siete ciclos, cada uno con su plano nuevo y su constructor nuevo. «Desviaciones» son las veces que el constructor tuvo que salirse de lo escrito; las adivinanzas —lo que rellenó porque el plano no lo decía— se cuentan aparte, y por eso el ciclo 7 puede tener cero de unas y dos de las otras.

El ciclo 7 se midió entero: 76 de 76 comandos de verificación en verde, 16 de 16 comandos de arranque, 14 de 14 líneas del gate de aceptación, y 2 adivinanzas, las dos cosméticas — el nombre de un titular de copyright y las versiones mayores de unas acciones de CI. El producto de prueba fue un verificador de enlaces de Markdown, probado desde el binario ya empaquetado e instalado en una carpeta limpia, no desde el árbol de código.

El ciclo 4 es el que vale: 14 de 14 no medía el plano

Mira el ciclo 3 en la tabla. Catorce pasos de catorce, producto funcionando, tres desviaciones. Se lee como éxito. No lo era: ese constructor fue parchando los defectos que se encontraba en el camino. El 14 de 14 no medía la calidad del plano, medía las ganas del constructor de arreglarlo mientras avanzaba.

El ciclo 4 lo sostuvo en literal estricto, sin permiso para parchar nada. El mismo tipo de plano dio 7 de 14 y una desviación bloqueante. El plano no había empeorado: hasta ese momento nadie lo había medido sin ayuda.

De ahí sale la forma de trabajar del resto del proyecto. Cada falla del constructor literal se vuelve una regla del generador, y cada regla del generador se vuelve además un hallazgo del validador — porque tres ciclos seguidos probaron que una regla sin quien la haga cumplir no previene nada.

Las 18 reglas que salieron de los ciclos

Van por letra, de la A a la R, y aquí conservan esa letra porque así se llaman en el repo y en los reportes del validador. Cada una es dos cosas al mismo tiempo: una obligación de quien escribe el plano y un hallazgo de quien lo audita.

Quién hace cumplir las reglas

El validador es un subagente aparte y su trabajo es reprobarte. Pasa 28 barridos sobre el plano —del Sweep 0 al Sweep 27— contra una lista de 37 formas conocidas de estar mal, y califica cada hallazgo como BLOCKER, MAJOR o MINOR con la línea exacta donde está. La barra para pasar es cero BLOCKER y cero MAJOR, y nada llega a tus manos antes de eso. En la v2.0 eran 20 barridos y 29 formas de reprobar.

Las reglas tampoco se aceptaron de palabra. Antes de darlas por buenas, el constructor las sondeó a propósito:

• Escondió el binario ya compilado y confirmó que la forma estricta de afirmar el código de salida sí fallaba, mientras la forma prohibida pasaba como si nada.
• Cambió un orden de comparación por otro y la lista se invirtió exactamente como el plano lo predecía. Tres gates distintos lo cacharon por separado.

Una regla que nunca viste fallar es una opinión. Estas se ejecutaron, y se vio fallar lo que tenían que hacer fallar.

Una aclaración por si la tabla de arriba se lee al revés: la v2.5 no agregó comandos, subagentes ni shapes. Son los mismos seis, los mismos tres y los mismos catorce que ya traía la 2.0. Lo único que creció es el rigor con el que se revisa lo que sale.

Necesitas dos cosas: Claude Code instalado y una suscripción de Claude. Nada más. Ni llave de API, ni cuenta aparte, ni configuración previa.

La instalación son dos comandos que se escriben dentro de una sesión de Claude Code, en la misma caja donde le escribes normalmente. El primero da de alta el catálogo — marketplace, como aparece en la documentación: la lista de plugins que publica una cuenta. Ese comando no instala nada todavía, solo le dice a Claude Code dónde buscar. El segundo instala el plugin.

Todo lo de esta sección pasa en la terminal. Si trabajas desde la app de escritorio de Claude, la sección 04 tiene la ruta del menú y el atajo que hace falta cuando el catálogo es de un tercero, como este.

Ese primer comando apunta al repositorio de GitHub, y de ahí Claude Code lee el catálogo que vive adentro. El catálogo se llama soyenriquerocha y el plugin se llama the-architect: son dos nombres distintos, y por eso el identificador de instalación los lleva pegados con una arroba en medio, plugin@catálogo, igual que un correo. Escribir solo the-architect no alcanza — Claude Code necesita saber de qué catálogo lo saca.

El scope que te va a preguntar

Antes de terminar te pregunta el scope, que es hasta dónde llega la instalación: si el plugin queda disponible para ti en todas partes, para cualquiera que trabaje en ese repositorio, o solo para ti y solo ahí dentro.

Elige user salvo que tengas una razón concreta para no hacerlo. Es lo que quiere casi todo el mundo: lo instalas una vez y lo tienes disponible en cualquier carpeta donde abras Claude Code, sin repetir el trámite por proyecto. project tiene sentido cuando quieres que tu equipo clone el repositorio y ya lo tenga puesto sin instalar nada.

El panel, si prefieres verlo

Escribir /plugin a secas, sin nada después, abre un panel interactivo con cuatro pestañas; te mueves entre ellas con la tecla Tab. Hace lo mismo que los dos comandos de arriba, y además sirve para ver qué se rompió cuando algo no cargó.

/plugin

  Discover    Installed    Marketplaces    Errors
  ────────

  Los plugins de los catálogos que ya tienes dados
  de alta, listos para instalar.

  Tab cambia de pestaña · Enter selecciona

Installed son los que ya tienes puestos, y desde ahí se prenden, se apagan o se desinstalan. Errors es la primera parada cuando un plugin no aparece. Y Marketplaces es la lista de catálogos dados de alta: ahí vuelves en la sección 05, porque es la pestaña donde se prende la actualización automática.

Activarlo en la sesión que ya tienes abierta

Al terminar, la instalación te dice si hace falta recargar. Si lo dice, no cierres nada: recargar los plugins lo activa en la sesión que ya está corriendo, sin perder el hilo de la conversación.

Si te avisa que recargar invalidaría el caché y se detiene ahí, repite el mismo comando con la bandera de forzar: /reload-plugins --force. Cerrar y volver a abrir Claude Code también funciona y no rompe nada; recargar solo te ahorra empezar la conversación de nuevo.

Confirmar que quedó

Este va en la terminal de tu sistema, no dentro de Claude Code. Lista lo que tienes instalado con su versión, su scope y si está prendido, que es la forma más rápida de salir de la duda.

Installed plugins:
  the-architect@soyenriquerocha
    Version: 2.5.0
    Scope: user
    Status: enabled

Cuatro cosas que mirar: el identificador completo con la arroba, la versión —2.5.0 es la actual—, el scope que elegiste, y el estado en enabled. Si dice disabled, está instalado pero apagado, y se prende desde la pestaña Installed del panel. Si la versión dice 2.0.0, estás en la anterior y eso no se arregla solo.

La alternativa: clonarlo

Si prefieres no instalar nada, o quieres leer el código antes de dejarlo entrar a tus sesiones, clona el repositorio y abre Claude Code adentro. Lee el CLAUDE.md de esa carpeta —el archivo de instrucciones que Claude Code carga solo al arrancar ahí— y se convierte en The Architect: la misma entrevista, los mismos dos gates que frenan la generación, y el mismo plano de salida.

Lo que no trae, y no es un detalle menor: dos de las tres piezas del plugin son exclusivas del plugin.

• Los seis slash commands, que son los comandos que se escriben empezando con diagonal. En modo clon no existe /architect ni ninguno de los otros cinco: le describes en palabras lo que quieres construir y la entrevista arranca igual, pero los atajos con banderas —reanudar una construcción, auditar un plano viejo— te toca pedirlos escribiéndolos.
• Los tres subagentes, que son las instancias auxiliares que trabajan aparte: la que verifica cada versión contra los registros, la que escribe los archivos del plano y la que lo audita. Sin ellos ese trabajo se hace en el hilo principal, así que la conversación se llena de material intermedio. Ninguno es obligatorio, y la herramienta te dice en una línea cuando le tocó hacerlo así.

Y funciona solo dentro de esa carpeta: para diseñar otro proyecto, vuelves ahí. Mantenerlo al día es un git pull.

Esta sección no sale del repo. The Architect documenta la terminal y ahí se detiene, así que todo lo que sigue está tomado de la documentación oficial de Claude Code. Si la app cambia de menús, manda la documentación, no esta página.

La app de Claude tiene tres pestañas: Chat, Cowork y Code. La de software es Code, y es la única donde un plugin como este tiene sentido. Ahí adentro todo lo instalado vive en el mismo lugar y se llega por el mismo botón.

La ruta del menú

Los plugins no están en una pantalla de ajustes aparte. Se llega a ellos desde la misma caja donde escribes, con el botón de más que tienes a un lado.

app de Claude   ›   pestaña  Code

   caja de texto
     └─ botón  +
          └─ Plugins
               ├─ los que ya tienes, con sus skills
               ├─ Add plugin       →  el navegador de plugins
               └─ Manage plugins   →  prender, apagar, desinstalar

Esa pantalla de Plugins es el inventario. Los que ya están puestos aparecen listados con las skills que trae cada uno, así que es el primer lugar donde mirar cuando dudas si algo quedó instalado. «Add plugin» abre el navegador para agregar; «Manage plugins» es donde los prendes, los apagas sin desinstalarlos, o los quitas.

La terminal integrada, en tres pasos

La app trae una terminal adentro. Se abre en la misma carpeta de trabajo en la que está tu sesión y comparte su entorno, así que lo que corres ahí es exactamente lo que Claude ve.

Son los mismos dos comandos de la sección 03, con «claude» adelante en lugar de la diagonal. La diagonal es para la caja de texto de Claude; «claude» es para una terminal.

Dónde ves los comandos que quedaron

Dos caminos al mismo listado, y ninguno pide salir de la app.

• Escribes la diagonal en la caja de texto: la lista se abre ahí mismo y los seis de The Architect salen mezclados con los que ya tenías.
• Botón + y luego «Slash commands», si prefieres leer el listado completo antes de escribir nada.

Una nota para que no busques donde no es: la pestaña Cowork no lee la carpeta ~/.claude de tu máquina. Sus skills y sus plugins salen de la configuración de tu cuenta, el panel «Customize» de la barra lateral. Es otro lugar, así que instalar aquí no la surte.

Con esto ya lo tienes puesto, en la terminal o en la app. Lo que sigue es lo que casi nadie hace y a casi todos les hace falta: revisar en qué versión estás, porque un catálogo de terceros no se actualiza solo y quien instaló la 2.0 sigue en la 2.0 hasta que la mueve a mano.

Este dato ordena la sección entera. Los catálogos oficiales de Anthropic —el catálogo es la lista desde la que Claude Code instala plugins— traen la actualización automática prendida de fábrica. Los de terceros y los locales la traen apagada. Este es de terceros.

O sea: si instalaste The Architect cuando salió, sigues en exactamente la versión que instalaste ese día y no se va a mover sola. La 2.5 puede llevar semanas publicada y tu máquina seguir cargando la 2.0 sin mencionarlo.

Primero, en cuál estás

Antes de correr nada, pregúntale a tu instalación. Esto va en la terminal normal, fuera de una sesión de Claude Code, y lista cada plugin instalado con su versión.

Installed plugins:
  the-architect@soyenriquerocha
    Version: 2.5.0
    Scope: user
    Status: enabled

Si la línea de Version dice 2.5.0, ya estás en la actual y esta sección no te toca. Si dice cualquier otra cosa, sigue leyendo: son dos comandos.

Actualizar, dos comandos y un reinicio

El orden importa. El primero baja la lista nueva del catálogo; el segundo instala lo que esa lista dice. Si te saltas el primero, el segundo compara contra la misma copia vieja y te contesta que ya estás al día.

Dejarlo automático de aquí en adelante

Para no repetir el trámite en la siguiente versión, préndele la actualización automática al catálogo. Es una sola vez y se hace desde el panel interactivo: escribes /plugin dentro de Claude Code, te mueves con Tab hasta la pestaña Marketplaces, eliges el catálogo y activas Enable auto-update.

  Discover    Installed    [ Marketplaces ]    Errors
  ───────────────────────────────────────────────────

  soyenriquerocha                       1 plugin
    the-architect              v2.5.0   enabled

  › Enable auto-update
    Update marketplace now
    Remove marketplace

  Tab cambia de pestaña · ↑↓ mueve · Enter elige

Un detalle de cuándo aplica: Claude Code revisa después de que arranca la sesión, con un retraso aleatorio de hasta diez minutos. La sesión que ya está corriendo se queda con las versiones que cargó al abrir, así que lo que baje hoy lo estrenas en la sesión siguiente.

Si actualizó y aun así no aparece nada

Pasa cuando la carpeta de caché se quedó con archivos de la versión anterior: el listado dice la versión nueva y los comandos no salen, o salen y se comportan como antes. Se arregla borrando esa carpeta.

Después de borrarla, reinicia Claude Code y vuelve a instalar el plugin. No pierdes nada tuyo: ahí solo vive la copia descargada. Tus planos están en la carpeta blueprints de cada proyecto y no los toca.

Si lo usas clonado

El modo clon no pasa por el catálogo, así que nada de lo anterior aplica. Entras a la carpeta del repo, jalas los cambios y ya.

La próxima vez que abras Claude Code ahí dentro, va a leer el CLAUDE.md actualizado. Con la misma advertencia de siempre: el clon no trae los seis slash commands ni los tres subagentes.

¿Vale la pena el trámite? Lo que separa a la 2.0 de la 2.5 no son funciones nuevas — los seis comandos, los tres subagentes y los catorce shapes son los mismos. Lo que creció fue el rigor: dieciocho reglas que salieron de siete intentos reales de construir desde un plano. Están contadas una por una en qué trae la 2.5, con los números que dio cada ciclo.

Son seis y no compiten entre sí: cada uno entra por un lado distinto del mismo trabajo. Elegir bien el de entrada te ahorra la mayor parte del trabajo, porque el comando decide qué te va a preguntar, cuánto dura la entrevista y si va a leer tu código antes de opinar.

Tres abren un diseño —desde cero o encima de lo que ya tienes— y tres se usan después, cuando el plano ya existe. Los argumentos van tal cual: escribir mal una bandera es justo lo que rompe el comando.

La decisión que de verdad importa

De los seis, solo dos se pelean por el mismo caso: proyecto nuevo, ¿express o completo? Los otros cuatro los elige la situación, no tú.

Lo que cambia entre uno y otro es cuántas decisiones tomas tú y cuántas toma él. Lo que no cambia es el rigor, y eso es lo que suele sorprender del express.

La regla para elegir cabe en una línea: el completo es el que quieres cuando nadie va a estar ahí para responderle las dudas al constructor después. Si vas a acompañar la construcción y puedes contestar sobre la marcha, el express te deja arrancar hoy sin bajar la barra.

Así se ve un arranque completo. Todo lo que le metas en esa primera línea —a qué se dedica el negocio, cuántos son, para cuándo lo necesitas— es una pregunta que ya no te va a hacer después.

/architect una app de reservas para barberías. Los clientes agendan desde el celular sin crear cuenta, cada barbero ve su día en un calendario, se cobra el anticipo con Stripe y salen recordatorios por WhatsApp la noche anterior. Somos dos personas y queremos algo cobrando en seis semanas.

El express pide lo mismo en una línea. Fíjate en qué trae la descripción: qué corre, qué lee y qué escupe. Con esas tres cosas alcanza para clasificarlo sin ambigüedad.

/architect-quick un CLI en Node que lea mis facturas en PDF de una carpeta y las exporte a un CSV con fecha, proveedor, subtotal, IVA y total.

Y si estás a media conversación y no te acuerdas del comando, no lo necesitas: la herramienta también se activa sola por lo que escribes. Pedirle el shape en voz alta —la familia de proyecto en la que te está clasificando— te deja corregir esa decisión antes de que arrastre a todas las demás.

Diseña la arquitectura completa de una app de inventario para una tienda de ropa con tres sucursales: entradas, salidas, traspasos entre sucursales y un corte diario por sucursal.

Quiero el plano, no código todavía. Antes de escribir nada, dime en qué shape lo estás clasificando y por qué, y hazme las preguntas que te falten.

Qué hace distinto el modo brownfield

Brownfield es diseñar encima de código que ya existe, y arranca con una fase 0 que el flujo de proyecto nuevo no tiene: mapea el repo antes de preguntarte nada. La razón es sencilla. En un proyecto de cero todas las decisiones están abiertas; en el tuyo la mitad las tomaste tú hace meses y no tiene por qué volver a votarlas.

Cuando termina de leer, imprime ese mapa y te pide que corrijas lo que entendió mal antes de diseñar nada. Tu corrección de treinta segundos sale mucho más barata que su suposición.

Esto es lo que revisa antes de abrir la boca:

• El runtime track, o sea la pila que ejecuta el proyecto: manifiesto de paquetes y lockfile, archivos de versión del lenguaje, imagen base del contenedor.
• Framework y topología: puntos de entrada, el directorio de rutas, qué corre en el servidor y qué en el cliente, cómo está armado el workspace.
• Convenciones: cómo nombras, dónde están los límites entre módulos, cómo manejas los errores, y la configuración del linter que de verdad se aplica.
• Capa de datos: migraciones, esquemas y en qué archivos se usa el ORM.
• Pruebas: qué runner corre, dónde viven los archivos, cómo se nombran y qué piso de cobertura hay.
• CI y despliegue: archivos de workflow, configuración de deploy y las variables de entorno que hacen falta.
• Las instrucciones de agente que ya tengas —CLAUDE.md y AGENTS.md—, que le ganan a los defaults del plugin.

En un prompt de brownfield, decir qué no se toca vale tanto como decir qué quieres. Las restricciones son literalmente la mitad del mensaje.

/architect-brownfield agregar inicio de sesión con Google a este proyecto.

Restricciones: el login por correo y contraseña que ya funciona no se toca, y un usuario existente tiene que poder vincular su cuenta de Google al mismo perfil sin perder su historial. No quiero reescribir la capa de sesión.

Las migraciones llevan encima lo que un cambio normal no necesita: paridad entre lo viejo y lo nuevo, una corrida en sombra que compara los dos lados sin que el usuario lo note, criterios exactos para abortar a medio camino, y el plan de apagado de lo viejo una vez que lo nuevo ya es la fuente de verdad.

/architect-brownfield migrar la base de datos de Firebase a Postgres.

Es una app en producción con usuarios reales, así que necesito poder abortar a mitad del camino sin perder datos. Dame el plan de paridad, la corrida en sombra para comparar lecturas de los dos lados, los criterios exactos para cancelar la migración, y el plan de apagado de Firebase una vez que Postgres sea la fuente de verdad.

Y cuando te enseñe el mapa, corrígelo con nombres y renglones, no con un «está mal». Este es el momento más barato de toda la guía para arreglar algo: una carpeta mal entendida aquí es un plano mal diseñado veinte minutos después.

Del mapa que armaste, tres cosas están mal:

1. La carpeta de "utils" no es utilidades sueltas — es la capa de dominio y ahí vive toda la lógica de negocio.
2. Los tests de la carpeta legacy ya no corren en CI; no los cuentes como cobertura.
3. La convención real de nombres de archivo es la del código nuevo, no la del viejo. Toma el código nuevo como referencia.

Corrige el mapa y vuelve a enseñármelo antes de seguir.

Elegido el comando, lo que sigue es la entrevista: cuántas preguntas son, en qué orden llegan, y los dos gates que pueden frenar la generación aunque tú ya hayas dicho que sí.

Escribes una línea de lo que quieres construir y arranca una entrevista de cuatro fases. No es un formulario: cada respuesta tuya cambia las preguntas siguientes, y al terminar la tercera fase tienes la arquitectura completa en pantalla, antes de que exista un solo archivo.

Entre esa arquitectura y la generación hay dos gates. Un gate es una revisión obligatoria que la herramienta se hace a sí misma y que bloquea el paso siguiente hasta que pasa. Los dos existen por la misma razón: el momento más barato para descubrir que el plano está mal es antes de que el plano exista.

Conviene decirlo de una vez, porque se confunde seguido: esta entrevista no es el modo plan de Claude Code. El modo plan vive dentro de la sesión y se va con ella —está contado en Planea antes del automático—. Esta entrevista existe para dejar un archivo en disco que otra sesión sin memoria pueda leer.

Las cuatro fases

Este es el recorrido completo, con la columna que casi nunca se documenta: qué te toca hacer a ti en cada fase.

Que la primera pregunta sea si hay código o no, no es un trámite. Si dices que ya hay repo, el flujo cambia entero: arranca mapeando lo que tienes —stack, convenciones, pruebas, despliegue— antes de preguntarte nada más, y te enseña ese mapa para que corrijas lo que leyó mal.

Los dos gates

Los dos son obligatorios y los dos bloquean la fase 4. No son avisos que puedas saltarte con un «sí, adelante»: mientras uno de los dos esté abierto, no genera.

El Gate B corre lo pidas o no, pero por default archiva lo que encontró y sigue. Si quieres verlo, pídelo: este prompt le exige enseñarte los hallazgos que sobrevivieron y qué hizo con cada uno.

Antes de generar nada, córreme el pre-mortem adversarial completo y enséñame los hallazgos que sobrevivieron a su propia refutación, no la lista larga.

De cada uno quiero saber: si se vuelve un riesgo del registro, si se vuelve un Non-Goal explícito, o si invalida la arquitectura. Si alguno la invalida, no generes: rediseña y vuelve a presentármela.

Los tres que trabajan por debajo

Durante la entrevista y la generación trabajan tres subagentes. No los invocas tú y no aparecen en la conversación: lo que ves es el resultado de lo que hicieron.

Ninguno de los tres es precondición. Si la herramienta de subagentes no está disponible en tu sesión, el mismo chequeo se hace en el hilo principal y te lo dice en una línea. La obligación es el chequeo; la delegación nunca lo es.

La fase 4 es la única donde no hay nada que contestar, y es de lejos la más larga. Vale la pena saber qué esperar para no cancelarla a la mitad creyendo que se trabó.

Por qué no se siente interrogatorio

La entrevista completa son doce a dieciséis preguntas repartidas en seis o siete mensajes, entre cuarenta minutos y una hora. Escrito así suena a trámite, y no lo es, por cuatro reglas de conversación que están puestas a propósito.

• Máximo tres preguntas por mensaje. Nunca te cae el cuestionario de veinte que hace que abandones a la mitad.
• Recomienda una opción y dice por qué, en vez de darte cinco para que elijas. Escoger entre cinco cosas que no conoces no es tener el control: es trabajo que te pasaron.
• Detecta tu idioma en el primer mensaje y se queda ahí. Si escribes en español, la entrevista y el plano salen en español.
• Mantiene un resumen corto de lo ya decidido dentro de la conversación, así que sobrevive a la compactación: cuando la sesión se queda sin espacio y se resume sola, lo que acordaste hace media hora no se evapora.

Cuando los dos gates pasan y la fase 4 termina, lo que tienes en disco es el plano. La sección que sigue lo abre por dentro: las veinte secciones que trae y el contrato de cuatro campos que lleva cada paso de construcción.

Lo que sale de la entrevista es un documento de veinte secciones fijas, siempre las mismas y siempre en el mismo orden. No es una plantilla decorativa: diecinueve existen para que la número 9 —el orden de construcción— se pueda escribir sin adivinar nada.

Si una sección no aplica a tu proyecto no se borra: se queda con su número y dice NO APLICA, con la razón debajo del encabezado. Suena burocrático hasta que aparece la herramienta que indexa por número y busca «la sección 13» donde ahora vive la 14. Y una sección marcada así tampoco puede cargar un contrato del que dependa un paso posterior: cuando eso pasó, quien construía terminó inventando el formato que faltaba.

Las veinte secciones, en orden

Las primeras ocho son diseño. De la 10 a la 20 son ejecución y contexto. La 9 es donde las dos mitades se encuentran, y es la única que un constructor autónomo lee de arriba abajo.

Si vienes de la v1, ese último renglón es el cambio que más se nota. El CLAUDE.md del proyecto destino era la sección 15 y ahora es la 19.1: dejó de ser un documento suelto y pasó a ser una pieza del paquete que se copia al proyecto.

El contrato de cada paso

En la v1 un paso era una instrucción suelta: «crea el webhook de pagos». Quien construye leyendo eso no tiene condición de parada, así que sobre-construye y canta victoria sobre trabajo que nunca corrió. Desde la 2.0 cada paso tiene cuatro campos, y los cuatro son obligatorios.

Un paso de verdad, abreviado

Así se lee un paso del orden de construcción: el webhook de pagos, que en la v1 cabía en un renglón, con los cuatro campos a la vista.

Do
  src/app/api/webhooks/stripe/route.ts
  src/lib/pagos/verificar-firma.ts
  Conecta: el evento checkout.session.completed
  marca la orden como pagada.

Done when
  CUANDO llega un POST con firma válida
  EL SISTEMA DEBE responder 200 y dejar la orden
  en estado "pagada".

  CUANDO llega un POST con firma inválida
  EL SISTEMA DEBE responder 400 y NO tocar la orden.

  CUANDO llega dos veces el mismo evento
  EL SISTEMA DEBE dejar una sola orden pagada.

Verify
  $ npm test -- pagos/webhook
  → 3 passing · sale 0
  $ node scripts/webhook-firma-mala.mjs
  → HTTP 400 · sale 0

Checkpoint
  git commit -m "paso 7: webhook de Stripe"
  git tag paso-07
  Punto de retorno: paso-06 (checkout creado)

Mira el último renglón. El punto de retorno se nombra antes de que haga falta, que es la única hora en que se puede nombrar bien: cuando el paso 8 revienta, ya nadie se acuerda de cuál era el último estado que sí corría.

La forma EARS, y lo que está prohibido

EARS es el molde de esas frases: CUANDO pasa tal cosa, EL SISTEMA DEBE hacer tal otra. Un disparador y una respuesta que se puede mirar desde afuera, sin adjetivos en medio. Se ve rígido a propósito, porque su trabajo es que dos lectores distintos —tú y una máquina— entiendan lo mismo.

La regla que decide si un criterio sirve es una sola: lo tiene que poder resolver un script, hoy, sin salir de tu máquina. Lo que necesita a un humano mirando, o a la cola de revisión de una tienda de aplicaciones, se va a un checklist de lanzamiento posterior — se escribe igual, pero deja de bloquear un paso.

• CUANDO alguien sin sesión abre /panel EL SISTEMA DEBE redirigirlo a /entrar.
• CUANDO el archivo subido pesa más de 10 MB EL SISTEMA DEBE responder 413 y no guardar nada.
• CUANDO la migración corre dos veces seguidas EL SISTEMA DEBE terminar sin error y dejar el esquema igual.

Dos formatos, y no los eliges tú

Al terminar de diseñar cuenta los pasos, y de ese conteo sale el formato: doce pasos o más van en bundle —una carpeta con varios archivos— y once o menos en un archivo único. Te dice cuál te tocó antes de escribir nada. Todo aterriza bajo ./blueprints/ de tu carpeta de trabajo, nunca adentro del plugin.

El bundle no es el plano cortado en pedazos: cada archivo tiene un lector distinto. El blueprint.md lo lees tú, el tasks.json lo lee la máquina que reanuda, y la carpeta workspace no se lee — se copia.

./blueprints/mi-app/
  blueprint.md          ← las 20 secciones, para leer
  tasks.json            ← el grafo de tareas, para la máquina
  epics/
    01-fundacion.md
    02-autenticacion.md
  workspace/            ← esto se copia al proyecto
    CLAUDE.md           ← la sección 19.1
    AGENTS.md
    .claude/
      settings.json
      skills/<nombre>/SKILL.md
      rules/<nombre>.md

La carpeta workspace existe para que el proyecto nazca sabiendo cómo se trabaja adentro de él. No es documentación de consulta: es lo que Claude Code lee cada vez que abres una sesión ahí. Van el CLAUDE.md del proyecto —la sección 19.1—, el AGENTS.md para las herramientas que leen ese otro archivo, la configuración de .claude/, y las skills y reglas propias del proyecto.

Se copia entera a la raíz del proyecto en un solo movimiento, y eso pasa al principio de la construcción: el comando exacto y el momento en que va están en la sección 09.

El conteo decide el formato, pero tu preferencia le gana en cualquier momento. Si ya sabes que vas a construir en varias sesiones, pide bundle aunque el conteo caiga del otro lado: lo que estás pidiendo en realidad es el tasks.json.

Genera en modo bundle aunque el conteo de pasos caiga del lado del archivo único. Voy a construir esto en varias sesiones a lo largo de dos semanas y quiero el tasks.json para poder reanudar.

Los catorce shapes

Nada de lo anterior se decide en abstracto. Antes de la segunda pregunta clasifica tu proyecto en uno de catorce shapes —la forma del producto, que es lo que determina qué te pregunta después y qué secciones del plano pesan—, y esa clasificación te la dice en voz alta en lugar de guardársela.

Si tu descripción es ambigua no elige a ciegas ni te devuelve la pelota con una lista: nombra los dos candidatos, dice cuál elegiría y por qué, y te hace la única pregunta que los separa.

Varios se parecen por fuera y se separan por quién los usa: un panel interno y una app SaaS pueden tener las mismas pantallas, y aun así el shape cambia la autenticación, el despliegue y qué se prueba. Corregirle el shape en la primera respuesta sale mucho más barato que discutirle el stack en la tercera.

Con el plano escrito queda una lectura que ninguna máquina puede hacer por ti. El validador comprueba que el documento sea consistente consigo mismo; lo que no sabe es si el proyecto que describe es el que tú querías.

Antes de que construyamos, léeme el plano y resúmeme en una lista corta:

1. Qué queda explícitamente FUERA de la v1 — la lista de Non-Goals, sin adornos.
2. Cada decisión que se tomó con un default y que yo nunca confirmé.
3. Los pasos que dependen de un servicio externo o de una llave que yo tengo que conseguir, y en qué paso me van a hacer falta.
4. Los tres pasos más largos, y qué pasa si alguno falla a la mitad.

No cambies nada del plano todavía. Solo quiero saber a qué le estoy diciendo que sí.

Con el plano en disco y leído, lo que falta es lo mecánico: sesión nueva, workspace copiado, y un constructor al que le prohíbes improvisar.

Ya tienes el plano escrito en ./blueprints/ y ya pasó su validador. Falta la mitad que casi nadie documenta: cómo se le entrega a quien lo va a construir para que llegue completo, sin que se pierda en el camino lo que costó decidir.

Todo lo que sigue se apoya en el contrato de cuatro campos de cada paso —qué hacer, cómo saber que quedó, los comandos que lo comprueban y el punto de retorno—, que está desarmado en la sección del plano. Aquí se usa, no se vuelve a explicar.

Los cuatro movimientos de arranque

Van en este orden y ninguno se salta. Los cuatro pasan antes de que se escriba la primera línea de código. Son para el bundle —la carpeta que sale cuando el proyecto pasa de once pasos—; con el archivo único, el tercero y el cuarto no aplican.

La bandera de no sobrescribir es la parte importante, y vale la pena saber por qué. Una copia desnuda —el clásico cp -R— encima de un árbol donde el build ya avanzó pisa cada archivo que se haya tocado desde entonces. El caso caro es el manifiesto de paquetes: lo regresa a la versión sin dependencias y se lleva todo lo instalado. Nadie reporta un error en ese momento; el que falla es el comando siguiente, quejándose de un binario que no encuentra, y eso se lee como una instalación rota en vez de un manifiesto pisado. Esa es la regla I del generador, y salió de un ciclo donde repetir la copia dejaba el proyecto en otro estado.

Si te preguntas por qué rsync y no cp con la bandera de no sobrescribir: porque esa versión de cp sale con error 1 en macOS justo cuando se salta un archivo que ya existe —que es el caso que la bandera venía a resolver— mientras que en GNU sale 0. La misma línea, significados opuestos según la máquina. Es la regla N: una guarda no puede fallar ella misma.

Ese mismo orden, escrito como el primer mensaje de la sesión nueva. Cambia la ruta por la de tu bundle. No lleva ni una decisión de diseño: todas están ya en el plano, y el mensaje termina pidiéndole que se pare y te reporte antes de tocar el paso 1.

Vas a construir un proyecto desde un plano que ya está escrito. Tú no lo diseñaste y no lo vas a rediseñar.

Antes de escribir una sola línea de código:

1. Lee ./blueprints/<slug>/blueprint.md completo, de la sección 1 a la 20. No lo hojees.
2. Lee ./blueprints/<slug>/tasks.json para ver el orden de las tareas y sus dependencias.
3. Copia la configuración del agente a la raíz del proyecto, sin sobrescribir nada
   que ya exista:
   rsync -a --ignore-existing blueprints/<slug>/workspace/ .
4. Corre el bloque de arranque de la sección 10 tal como está escrito, en orden.

Cuando termines esos cuatro puntos, párate y dime tres cosas: en qué shape está clasificado el proyecto, cuántos pasos tiene la sección 9, y si el bloque de arranque salió limpio. No empieces el paso 1 hasta que te lo confirme.

El constructor literal

Esto no es una idea de esta guía. Es el protocolo con el que corrieron los ciclos 4 a 7 de la herramienta contra sus propios planos, y existe porque el ciclo 3 dio un resultado que engañaba.

En el ciclo 3, con el constructor suelto, salieron 14 de 14 pasos. Se leía como un éxito. En el ciclo 4, sostenido literal sobre un plano comparable, salieron 7 de 14. La diferencia no estaba en el plano: estaba en cuánto lo estaba parchando el constructor por su cuenta sin decir nada. Un constructor que rellena los huecos en silencio te esconde justo lo que necesitas ver.

Sostenerlo literal no lo vuelve mejor constructor. Lo vuelve mejor informante: los defectos del plano aparecen hoy, en tu pantalla, en vez de aparecer en tres semanas cuando ya hay código encima.

A partir de ahora construyes en modo literal estricto. Estas cinco reglas le ganan a cualquier otra instrucción que traigas:

1. NO trabajes alrededor de un defecto del plano. Si un comando del plano está mal escrito, no lo arregles en silencio: párate y repórtalo.
2. NO supongas nada que el plano no diga. Si te falta un nombre de archivo, un valor, un formato o una decisión, párate y pregúntame. No elijas «lo razonable».
3. Un comando de Verify que no sale 0 es un paso reprobado. No lo declares terminado, no lo intentes de otra forma y no cambies el comando. Repórtalo y espera.
4. NO adelantes trabajo de pasos posteriores, aunque te quede claro hacia dónde va. Un paso a la vez, en el orden de la sección 9.
5. Al cerrar cada paso, haz su Checkpoint tal cual está escrito — el commit y su etiqueta — antes de tocar el paso siguiente.

Y llévame la cuenta. Al terminar cada paso dime, en dos líneas:
- Desviaciones: cuántas veces tuviste que salirte del plano, y cuáles.
- Adivinanzas: cuántas veces rellenaste algo que el plano no decía, y qué fue.

Si las dos van en cero al final, el plano se sostiene solo. Si no, esos números son exactamente lo que hay que arreglarle al plano — no al código.

Empieza por el paso 1.

Al cerrar cada paso te va a dar dos números: desviaciones —cuántas veces tuvo que salirse del plano— y adivinanzas —cuántas veces rellenó algo que el plano no decía—. Si los dos terminan en cero, el plano se sostiene solo y ya sabes que otra sesión puede repetirlo.

Si no terminan en cero, esos números no son un reporte de fallas del constructor: son la lista de lo que hay que arreglarle al PLANO. Cada adivinanza es una decisión que el plano no tomó y que alguien tomó por él sin nadie a quién preguntarle. Corriges allá y el próximo que construya no se topa con lo mismo; corriges solo el código y el hueco sigue en el papel.

Para calibrar: el ciclo 7 cerró en 13 de 13 pasos, 0 desviaciones y 2 adivinanzas, las dos cosméticas — el nombre de un titular de copyright y las versiones mayores de unas acciones de integración continua. Ese es el piso realista.

Cuando un Verify no sale 0

Va a pasar, y el constructor literal tiene prohibido resolverlo por su cuenta. Un comando de verificación que no sale 0 tiene dos causas posibles y se arreglan en lugares distintos: o el código quedó mal, o el comando del plano está mal escrito. Confundirlas sale caro — retorcer el código para que pase un comando equivocado te deja el proyecto torcido y el plano intacto para el siguiente.

Se paró el paso. Antes de tocar nada, diagnostica y contéstame en este orden:

1. Pega la salida completa del comando que falló, sin resumirla.
2. ¿Falló porque el código quedó mal, o porque el comando del plano está mal escrito? Di cuál de las dos, y en qué te basas.
3. Si el código quedó mal: qué criterio de la lista de «Done when» de este paso no se cumple, y qué falta para cumplirlo.
4. Si el comando del plano está mal: qué asume que no es cierto en esta máquina — una ruta que nadie creó, una herramienta que nadie instaló, una variable de entorno que nadie cargó, un número que el plano afirma en un lado y contradice en otro.

No arregles nada todavía. Con tu diagnóstico decido si arreglamos el código o corregimos el plano; si el plano está mal, el arreglo va allá y no aquí, porque si no el próximo que construya se topa con lo mismo.

Reanudar sin volver a explicar nada

Un build de bundle no cabe en una sola sesión, y no tiene por qué. /architect-next lee el tasks.json, encuentra la primera tarea pendiente cuyas dependencias están todas cerradas, y la imprime completa: a qué épica pertenece, sus criterios de aceptación y todos sus comandos de verificación.

Eso es lo que hace que una sesión nueva, sin memoria de nada, conteste la única pregunta que importa al abrir: qué sigue y cómo sé que quedó.

Esas son casi todas las banderas que existen. La herramienta completa tiene cinco: estas cuatro y el --apply de /architect-refresh, que es tema de la sección siguiente. Cualquier otra que se te ocurra no está.

Y el primer mensaje de la sesión que retoma cabe en una línea. La ruta del bundle va detrás cuando hace falta señalarla, por ejemplo si tienes más de una carpeta bajo ./blueprints/.

/architect-next

El gate de aceptación va al final, y va entero

La sección 20 del plano cierra con un gate global: una lista de condiciones que el producto terminado tiene que cumplir, aparte de las que ya cumplió paso por paso. No es un resumen de lo anterior y no se da por aprobado porque todos los pasos hayan pasado.

Correrlo entero es lo que separa «terminé los pasos» de «el producto funciona». En el ciclo 7 fueron 14 líneas de gate y las 14 se corrieron sobre el binario ya empaquetado e instalado en una carpeta limpia, no sobre el árbol de código — que es donde un proyecto acostumbra pasar sus propias pruebas y fallar en la máquina de cualquier otro.

Cuando el gate cierra en verde, The Architect terminó su trabajo. Revisar lo que quedó construido —qué se rompió, qué falta endurecer, qué se coló— es otro oficio y vive en Crea y audita tu app.

Un plano no es un archivo que se lee una vez y se archiva. Se queda en tu repo, lo abres tres meses después y ya no dice del todo la verdad. Envejece de dos maneras distintas, y cada una tiene su propio comando.

Se confunden seguido porque desde afuera se ven igual: un plano viejo que ya no sirve. Por dentro no se parecen en nada. Una es un hueco de formato —le faltan piezas que cuando se escribió no existían—; la otra es un plano perfectamente bien armado al que se le caducaron los números.

Auditar: te califica, no te reescribe

/architect-audit corre el mismo validador que bloquea la generación, pero sobre un plano que ya existe. Le pasas la ruta del blueprint.md o la de la carpeta del bundle —el bundle es el plano repartido en varios archivos— y te devuelve PASS o FAIL con referencias de línea, hallazgo por hallazgo.

Es de solo lectura, y ahí está su gracia: califica, no arregla. No toca un carácter del archivo. Puedes correrlo sobre un plano que te pasaron, sobre uno que ya está a medio construir, o sobre el tuyo antes de decirle que sí a cuarenta pasos de trabajo.

Los hallazgos vienen calificados BLOCKER, MAJOR y MINOR, y la barra es la misma que adentro: pasa con cero BLOCKER y cero MAJOR. Un MINOR no lo detiene, pero queda escrito con su línea.

/architect-audit ./blueprints/mi-app/blueprint.md

El reporte también sirve de lista de trabajo. Cada hallazgo trae su línea, así decides cuáles cierras a mano y cuáles son señal de que conviene volver a generar en vez de remendar.

Desoxidar: la arquitectura aguanta, los números no

El otro caso es el plano que sigue estando bien. La decisión de arquitectura no caducó, el orden de construcción tampoco, y los criterios de aceptación se siguen pudiendo medir. Lo que se movió son las versiones que fijó.

/architect-refresh toma esa lista y la reverifica una por una contra los registros en vivo. No vuelve a abrir el diseño ni te hace preguntas: reporta cuatro cosas.

• Qué se movió: cada versión fijada contra la que hoy está publicada.
• Qué se rompe: los saltos de versión mayor que cambian un comando de arranque, un archivo de configuración o una API que el plano daba por hecha.
• Qué cambiar: la línea exacta del plano y el número que va en su lugar.
• Qué mirar con lupa: prereleases, paquetes sin mantenimiento reciente, y lo que no pudo verificar.

Sin banderas, el comando solo te enseña el reporte y tú decides qué hacer. Con la bandera de aplicar edita el plano en el lugar, con los números nuevos ya escritos donde iban.

/architect-refresh ./blueprints/mi-app/ --apply

Correrlo primero sin la bandera es la costumbre sana: lees el diagnóstico, revisas si algún salto de versión mayor cambia decisiones y no solo dígitos, y aplicas después.

Cuándo sale más barato regenerar

Hay un punto donde parchar deja de valer la pena. Para cualquier cosa que todavía no hayas empezado a construir, correr /architect de nuevo sale más rápido que llevar un plano de la v1 hasta la forma de la v2 a mano: tendrías que inventar de cero los criterios de aceptación de cada paso, los comandos que los comprueban, las épicas y el grafo de tareas. La entrevista te cuesta menos que eso.

Si ya construiste la mitad, el caso cambió de nombre: lo que tienes enfrente dejó de ser un plano viejo y es un repo que existe. Eso entra por el comando de brownfield, el que mapea tu código antes de preguntarte nada. Los seis comandos, con sus argumentos exactos, están en la sección de los comandos.

Nada de lo que sigue es exótico: es lo que de verdad se rompe cuando alguien instala esto y arranca el mismo día. Casi todo se arregla en una línea, y la mitad ni siquiera es una falla — es la herramienta trabajando y tú sin saber que así se ve.

La segunda mitad de esta sección es lo que vive alrededor: las skills que The Architect consulta mientras diseña y las que te deja anotadas en el plano para quien construya después.

Siete tropiezos, y qué hacer con cada uno

En orden de qué tan seguido pasa. Los dos primeros son de instalación, los tres de en medio son de expectativa, y los dos últimos son del plano ya escrito.

Cinco de esos siete ya tienen dueño en esta misma página. El 2 vive en actualizar si te quedaste en la 2.0, con los dos comandos y cómo dejarlo automático. El 4 está entero en veinte secciones y un contrato, donde también está el árbol del bundle. El 5 y el 6 son la misma parada: del plano al proyecto, con la sesión nueva, el workspace copiado y el prompt del constructor literal. Y el 7 es media sección de auditar y desoxidar.

Las skills que lo acompañan

The Architect diseña solo, pero si encuentra ciertas skills instaladas las aprovecha. Todas son opcionales, sin excepción: cuando falta una usa su propia base de conocimiento o la búsqueda web integrada, lo dice en una línea y sigue. Ninguna ausencia bloquea la generación.

Las que usa mientras diseña

Las que recomienda en el plano

Estas no las corre él. Las nombra en la sección 18 del plano, la de skills a usar durante la construcción, dirigidas a quien construya después — tú en otra sesión, u otra instancia de Claude Code.

Cada una entra al plano con su comando de instalación al lado, no solo con su nombre. Nombrar una skill que quien construye no puede instalar rompe la promesa de que el plano se basta solo, y esa promesa es todo el punto de la herramienta.

Con eso cierra la guía. The Architect no construye tu proyecto: escribe el documento del que se construye, y lo que hagas con ese documento —construirlo tú, pasárselo a una sesión sin contexto, o leerlo para descubrir qué todavía no habías decidido— ya es cosa tuya.