Platica, Luego Construye

Las 3 prácticas que hacés antes de tocar Claude Code marcan si tu app sale bien o sale rota. La mayoría salta directo a "abrir terminal y escribir prompt". Resultado: 3 horas después, hay código pero no es lo que querías. La diferencia entre "construir bien" y "rebuilder eternamente" es platicar primero, idealmente con The Architect como interlocutor.

Esta nota cubre las 3 prácticas pre-código, qué es The Architect, y cómo separar la conversación de la construcción para acelerar resultado, no demorarlo.

El antipatrón "abrir y tipear"

Patrón típico que sale mal:

1. Tenés idea: "necesito un dashboard para mis clientes".
2. Abrís Claude Code.
3. Tipeás: "armame un dashboard para mis clientes".
4. Claude empieza a generar código.
5. 30 minutos después tenés algo, pero:
   • El stack no es el que ibas a usar.
   • Falta lo que más importaba.
   • Sobra lo que no necesitabas.
6. Tirás todo y reempezás, o aceptás algo sub-óptimo.

Costo: 1-3 horas de trabajo wasted. Y peor: las decisiones tomadas "rápido" persisten.

Las 3 prácticas pre-código

Práctica 1: definir el "qué" (no el "cómo")

Antes de codear, escribí en lenguaje claro:

• Qué hace el producto. Una frase.
• Para quién. Usuario específico, no "todos".
• Qué problema resuelve. El problema que el usuario tiene hoy.
• Cómo medís éxito. 1-3 métricas concretas.

Ejemplo:

QUÉ: dashboard que muestra a mis clientes (dueños de tiendas online)
sus métricas de venta semanales sin que tengan que loguear a Shopify.

PARA QUIÉN: dueños de tiendas que tienen 1-5 stores en Shopify y no
quieren entrar a cada admin por separado.

PROBLEMA: hoy abren 5 tabs, cada admin de Shopify, comparan a mano.
Pierden 20-30 min cada vez.

ÉXITO: que los 10 clientes piloto reduzcan ese tiempo a 2 minutos.
Que renueven plan en mes 2.

20 minutos de pensar y escribir. Te ahorra horas de codear lo equivocado.

Práctica 2: definir las restricciones

Restricciones son lo que NO va a hacer y CÓMO no va a hacerlo. Sin restricciones, Claude (o cualquier dev) deriva.

NO: 
- No es app móvil nativa. Web responsive es suficiente.
- No maneja órdenes individuales (solo agregados).
- No notifica push (solo email digest semanal).

CÓMO:
- Stack: Next.js 15, TypeScript estricto, Drizzle ORM + Postgres.
- Auth: Clerk (ya tengo cuenta paga).
- Hosting: Vercel.
- Diseño: minimalista, estilo Linear.
- Sin animaciones decorativas.

Restricciones son guía. Sin guía, Claude propone "elegancias" que vos no querías.

Práctica 3: definir el MVP de 7 días

Lo más peligroso: querer todo en una primera versión.

Mejor: definí qué tiene que estar funcionando en 7 días para que un cliente piloto use:

MVP 7 DÍAS:
1. Login con Clerk.
2. Conectar 1 tienda Shopify (OAuth).
3. Dashboard muestra: total ventas semana, top 5 productos, comparativa vs. semana anterior.
4. Email digest cada lunes 8am.

NO en MVP (después):
- Multi-store.
- Custom date ranges.
- Export a CSV.
- White-label.
- Notificaciones realtime.

El MVP es lo que podés probar con clientes. Lo demás se agrega cuando el MVP funciona.

Quién es The Architect

The Architect es una skill open-source que se especializa en planeación arquitectónica. Cuando la activás, Claude no codea — actúa como arquitecto senior.

Instalación:

npx skills@latest add agora/the-architect

Uso:

> /the-architect: [pegás tu Práctica 1 + 2 + 3]

The Architect:

1. Hace preguntas para clarificar (típicamente 3-7).
2. Propone arquitectura: stack, modelos de datos, endpoints, flow de auth, deploy target.
3. Identifica trade-offs y por qué eligió cada cosa.
4. Lista las decisiones que vos tenés que tomar (no decide por vos en cosas con criterios subjetivos).
5. Estima esfuerzo realista por componente.

Output típico: documento de 1.500-3.000 palabras con plan completo.

Tiempo: 15-30 minutos de conversación. Resultado: plan que reduce el tiempo de construcción 30-50%.

Cómo se ve la conversación

Sigamos con el dashboard de tiendas Shopify.

> /the-architect

[Pegás Práctica 1 + 2 + 3]

The Architect:

Buenas. Antes de proponer arquitectura, necesito clarificar:

1. ¿Cuántos clientes piloto esperás en los primeros 30 días?
2. ¿La info de Shopify la traes en tiempo real o sincronizás
   periódicamente (cache local)?
3. ¿Quién paga por el SaaS — vos lo cobrás $X/mes o es gratis?
4. ¿GDPR / compliance específico aplica?
5. ¿Tu hosting actual cubre Postgres o querés managed (Neon, Supabase)?
6. ¿Email digest envías vos o usás SendGrid/Postmark?

Vos respondés cada una. Mientras respondés, te das cuenta de cosas que no habías pensado.

Después:

Propuesta de arquitectura:

STACK
- Next.js 15 con App Router (Server Components).
- TypeScript estricto.
- Drizzle ORM.
- Postgres en Neon (managed, free tier alcanza para piloto).
- Clerk para auth (ya tenés cuenta).
- Vercel para hosting.

MODELOS DE DATOS
- User (gestionado por Clerk).
- Store (id, userId, shopifyDomain, accessToken, lastSyncAt).
- DailySnapshot (id, storeId, date, totalRevenue, totalOrders, topProducts).

SYNC STRATEGY
- Cron 1× al día a las 3am (Vercel Cron) sincroniza todas las stores.
- Guarda snapshot diario.
- Dashboard lee snapshots (rápido), no llama Shopify en cada render.

ENDPOINTS
- POST /api/shopify/connect — OAuth flow.
- GET /api/dashboard — lee snapshots del usuario.
- POST /api/cron/sync — cron job (protegido por secret).

FLOW DE AUTH
- Clerk handlea signup/login.
- Conectar tienda: OAuth con Shopify (scope read-only).

EMAIL DIGEST
- Vercel Cron también dispara lunes 8am.
- Postmark transactional (free tier 100/mes alcanza).

DEPLOY
- Vercel (free tier para piloto).
- Variables: CLERK_*, NEON_DB, SHOPIFY_APP_*, POSTMARK_*.

ESFUERZO ESTIMADO
- Setup base + auth: 4 horas.
- OAuth Shopify: 4 horas.
- Sync job + modelo de datos: 6 horas.
- Dashboard UI: 4 horas.
- Email digest: 3 horas.
- Testing y bugs: 4 horas.
TOTAL: ~25 horas. Con Claude Code agresivo: 15 horas.

DECISIONES QUE TENÉS QUE TOMAR
1. ¿Querés que clientes invitar a otros usuarios? (multi-tenant más complejo)
2. ¿Si el sync falla, qué notificás? (silencioso, email, dashboard alert)
3. ¿Dashboard mobile-first o desktop primero?

RIESGOS
- Si tenés clientes con 50+ stores, el cron de 3am puede tardar. Para piloto no es problema.
- Shopify rate limits: 40 req/min por store. El sync diario está bien dentro de eso.

Vos leés. Te das cuenta:

• El multi-tenant no lo había pensado. Decidís: no, solo single user por cuenta.
• El sync mobile-first no había definido. Decidís: desktop primero, responsive después.
• El "qué notificar si falla sync" lo definís: email al admin (vos).

Re-corrés:

> Ajustá considerando: single user, desktop primero, notificación a admin si falla sync.

The Architect ajusta y te devuelve plan final.

Tiempo total de "platicar" vs. resultado

20 min en Práctica 1+2+3 + 30 min con The Architect = 50 minutos antes de codear.

Lo que ganás:

• Plan claro que no cambia mid-construction.
• Decisiones tomadas con criterio, no improvisadas.
• Trade-offs visibles antes de pagar el costo.
• Esfuerzo estimado realista.

Construcción posterior: 12-18 horas en lugar de 25-40 si improvisás.

Net ahorro: 10-20 horas en proyecto de tamaño mediano.

Por qué la gente igual no hace esto

Tres razones que escuché muchas veces:

Razón 1: "Soy más ágil si arranco a hacer"

Mito. Ágil no es saltearse pensar — es ciclos cortos de pensar+hacer. Pensar 50 minutos para ahorrar 15 horas es ágil. No pensar es chapucear.

Razón 2: "No sé qué quiero todavía"

Si no sabés qué querés, ese es exactamente el problema que The Architect ayuda a resolver. Las preguntas que hace te fuerzan a clarificar.

Razón 3: "Es proyecto chico, no vale el overhead"

Para proyectos REALMENTE chicos (script de 1 hora, fix puntual), saltar este flow está bien. Para todo lo que toma >4 horas de construcción, el overhead vale 10×.

Variantes según contexto

Solo: vos + The Architect

Lo descripto arriba. The Architect cubre lo que normalmente sería revisión con dev senior.

En pareja: tech lead + The Architect

Buena dinámica: vos pensás con The Architect, después lo pasás a tu compañero/a para review. Te llega con plan estructurado, no con "esto se me ocurrió".

Equipo: kickoff con The Architect

Antes de equipo arrancar, una persona corre el flow con The Architect. El plan resultante se discute en kickoff. Equipo arranca alineado.

Cliente: con The Architect en sesión

Para freelance, podés correr The Architect mientras platicás con el cliente. "Antes de cotizarte, déjame correr esto con mi arquitecto." Cliente ve el plan, te da feedback, acordás scope antes del contrato.

Lo que NO hace The Architect

Para que la expectativa sea correcta:

• No decide por vos en cosas subjetivas. Trade-offs los plantea, vos elegís.
• No reemplaza experiencia. Te da plan razonable. Saber si es el mejor plan requiere oficio.
• No cubre operación post-deploy. Setup, sí. Monitoring/scaling/migraciones futuras, no.

Conclusión

"Platica, luego construye" no es opcional para proyectos serios. The Architect es el interlocutor que hace que la plática sea estructurada en lugar de divagación.

Si tu próximo proyecto va a tomar más de 4 horas, dedicá 50 minutos primero a las 3 prácticas + The Architect. Vas a notar la diferencia desde la primera hora de construcción real.

Tags: claude-code, mejores-practicas, arquitecto, workflow, planeacion, the-architect