Cómo construí Roger-arq: mi arquitectura convertida en una skill para agentes

Respuesta corta: Roger-arq es una skill —un archivo de instrucciones que un agente de IA carga antes de trabajar— donde escribí cómo construyo software: qué comandos nunca se ejecutan, cómo se separan las capas, cómo se nombran los archivos, cómo responde cada endpoint y cómo se autoriza cada fila. Nació de cansarme de repetir lo mismo en cada proyecto. Hoy es la diferencia entre un agente que escribe código plausible y uno que escribe código como yo lo escribiría.

Te cuento cómo la construí para que hagas la tuya.

El problema: explicar lo mismo diez veces

Trabajo en varios productos a la vez: un ERP, apps móviles, plataformas con pagos y facturación. Todos comparten stack (Next.js, tRPC, Prisma, Zod, Tailwind, shadcn) y, sobre todo, comparten decisiones: cómo se manejan errores, dónde vive la autorización, cuándo se abre una transacción.

Con agentes, cada sesión empezaba igual: "no uses any", "no hagas db push", "el error es un código, no texto libre", "filtra en el where, no después". Si una regla vive solo en mi cabeza, cada agente —y cada persona nueva— la va a romper.

La estructura de Roger-arq

Después de muchas iteraciones, la skill quedó organizada así, y el orden importa:

1. Reglas críticas (no negociables). Lo primero que el agente lee: no ejecutar builds que toquen la base de datos, no correr migraciones, no imprimir secretos. Pocas, absolutas y verificables.
2. Prioridades. Cuando dos reglas chocan, cuál gana: correctitud y seguridad de datos, tipado estricto, separación por capas, módulos localizados, respuestas uniformes, cambios pequeños.
3. Stack. Qué librerías se usan y cuáles no se agregan (una sola librería de animación, una de gráficas).
4. Anatomía de módulo. Un árbol de carpetas concreto: page.tsx delgado, _components privados, servicio de dominio en servidor, reglas puras en src/lib, i18n y spec.
5. Capas. UI → cliente tRPC → procedure → servicio → Prisma. Cada capa con una responsabilidad y prohibiciones claras.
6. Autorización y alcance por fila. Una fila fuera del alcance responde 404, nunca 403. Toda escritura carga primero la fila dentro del alcance del usuario.
7. Contrato tRPC. Toda procedure responde con la misma forma (result, error, status, message), construida solo con ok/fail, y el error siempre es un código de catálogo que la UI traduce.
8. Datos, UI, tablas, dashboards, motion. Reglas de transacciones, serialización, shell, vistas de tabla y kits de diseño.
9. Checklist final y anexos con skills complementarias y referencias a implementaciones reales.

Decisiones que la hicieron funcionar

• Reglas, no opiniones. "Escribe código limpio" no sirve. "Prohibido any, as any y @ts-ignore" sí: es verificable.
• Ejemplos reales, no inventados. Cada patrón apunta a un archivo de un proyecto mío donde ya funciona. El agente copia de algo probado.
• Fuente de verdad para cada kit. Mis kits de UI (shell, tablas, gráficas, chat de agente) se copian siempre desde un repo concreto, y toda mejora vuelve ahí. Sin esto, cinco proyectos terminan con cinco versiones divergentes.
• Lo que el agente NO debe hacer, explícito. Las prohibiciones evitan más daño que cualquier instrucción positiva. Un agente que corre db push en el proyecto equivocado te arruina la semana.
• Composición con otras skills. Roger-arq no intenta saberlo todo: delega diseño, motion, 3D y móvil a skills especializadas y declara que, si contradicen el contrato, gana el contrato. Para móvil tengo una variante hermana, Roger-arq-mobile.

Un ejemplo del contrato

list: salesProcedure.input(listSchema).query(async ({ ctx, input }) => {
  try {
    return ok(await listOrders(ctx.db, viewerFromSession(ctx.session), input), 'OK')
  } catch (error: unknown) {
    const { code, status } = normalizeError(error)
    return fail(code, status, 'No se pudo listar')
  }
}),

Tres reglas en diez líneas: el servicio recibe el viewer (nunca lee la sesión), el error se normaliza a un código estable y nada interno llega al cliente.

Cómo construir tu propia skill (paso a paso)

1. Junta tus repeticiones. Revisa tus últimos 20 code reviews y prompts. Lo que corregiste más de dos veces es tu primer borrador.
2. Crea el archivo. Un SKILL.md con frontmatter:

---
name: mi-arq
description: Contrato de arquitectura para proyectos X. Úsala al crear o modificar módulos, endpoints o modelos de datos.
---

# Mi Arq

## 1. Reglas críticas
1. Nunca ejecutes migraciones; entrega el comando al usuario.
2. ...

3. Escribe primero lo no negociable, en imperativo y verificable.
4. Añade la anatomía: un árbol de carpetas real vale más que tres párrafos.
5. Apunta a ejemplos reales de tu código.
6. Pruébala en una tarea real con un agente. Cada error del agente es una regla que falta o que está mal escrita.
7. Versiónala y mejórala como cualquier otro código.

La description es crítica: es lo que el agente lee para decidir si cargar la skill. Di qué hace y cuándo usarla.

Por qué deberías hacerlo

Una skill es tu experiencia en un formato que escala: la usan tus agentes, tu equipo y tu yo del futuro. Y si la compartes, ayudas a que la comunidad deje de aprender las mismas lecciones a golpes. Yo empecé con diez reglas escritas en una tarde; hoy es el contrato que siguen todos mis proyectos.

No necesitas una arquitectura perfecta para empezar. Necesitas escribir la que ya tienes.

Relacionado: el flujo de desarrollo ya vive en la nube.

Preguntas frecuentes

¿Qué es una skill para agentes de IA?

Un paquete de instrucciones (un archivo SKILL.md con nombre y descripción, más referencias opcionales) que el agente carga cuando la tarea entra en su área. Convierte conocimiento tácito de un equipo en reglas explícitas, reutilizables y versionables.

¿Qué es Roger-arq?

Es la skill de arquitectura de Nathan Lazo para proyectos T3 (Next.js App Router, tRPC, Prisma, Zod, Tailwind, shadcn). Define reglas críticas de ejecución, capas, anatomía de módulos, un contrato uniforme de respuestas tRPC, autorización por fila, manejo de datos y kits de diseño con fuente de verdad.

¿Cómo empiezo mi propia skill?

Busca lo que repites en cada proyecto o code review, escríbelo como reglas verificables (no como opiniones), pon primero lo no negociable, añade ejemplos de referencia reales, pruébala con un agente en una tarea real y corrige cada vez que el agente se equivoque.